diff options
Diffstat (limited to 'guide/src')
| -rw-r--r-- | guide/src/chapter_00.md | 14 | ||||
| -rw-r--r-- | guide/src/chapter_01.md | 32 | ||||
| -rw-r--r-- | guide/src/chapter_02.md | 130 | ||||
| -rw-r--r-- | guide/src/chapter_03.md | 6 |
4 files changed, 85 insertions, 97 deletions
diff --git a/guide/src/chapter_00.md b/guide/src/chapter_00.md index 10570cf4..fafa17f9 100644 --- a/guide/src/chapter_00.md +++ b/guide/src/chapter_00.md @@ -25,9 +25,16 @@ $ cd example Now add Sequoia to the `[dependencies]` section in `Cargo.toml`: ```toml -sequoia-openpgp = "0.3" +sequoia-openpgp = "*" ``` +Note: Explicitly stating a major version for dependencies is usually +better than just using the wildcard here (read how to [specify +dependencies]). Also, please check that the crate's version matches +the version of this guide. + +[specify dependencies]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html + If you want to use the bleeding edge, you can instead refer to the version in git: @@ -67,10 +74,7 @@ Running the application now prints a friendly message to stdout. A word on the `armored` macro. We will use this macro in this guide to inline OpenPGP data into the source code. Sequoia includes filters for ASCII armored data. You can use these filters to read armored -data from any `Read`er, or write armored data to any `Write`r. The -`armored` macro does the same for string literals. In order to use -this macro, you need to use `#[macro_use]` when importing the -`openpgp` crate. +data from any `Read`er, or write armored data to any `Write`r. # Building the Sequoia tool diff --git a/guide/src/chapter_01.md b/guide/src/chapter_01.md index e2c2a88f..3d2af662 100644 --- a/guide/src/chapter_01.md +++ b/guide/src/chapter_01.md @@ -16,7 +16,7 @@ extern crate sequoia_openpgp as openpgp; use openpgp::cert::prelude::*; use openpgp::serialize::stream::*; use openpgp::packet::prelude::*; -use openpgp::parse::stream::*; +use openpgp::parse::{Parse, stream::*}; use openpgp::policy::Policy; use openpgp::policy::StandardPolicy as P; @@ -92,7 +92,8 @@ fn main() { # }; # # // Now, create a verifier with a helper using the given Certs. -# let mut verifier = Verifier::from_bytes(policy, signed_message, helper, None)?; +# let mut verifier = VerifierBuilder::from_bytes(signed_message)? +# .with_policy(policy, None, helper)?; # # // Verify the data. # io::copy(&mut verifier, sink)?; @@ -105,7 +106,7 @@ fn main() { # } # # impl<'a> VerificationHelper for Helper<'a> { -# fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) +# fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) # -> openpgp::Result<Vec<openpgp::Cert>> { # // Return public keys for signature verification here. # Ok(vec![self.cert.clone()]) @@ -164,7 +165,7 @@ create it: # use openpgp::cert::prelude::*; # use openpgp::serialize::stream::*; # use openpgp::packet::prelude::*; -# use openpgp::parse::stream::*; +# use openpgp::parse::{Parse, stream::*}; # use openpgp::policy::Policy; # use openpgp::policy::StandardPolicy as P; # @@ -240,7 +241,8 @@ fn generate() -> openpgp::Result<openpgp::Cert> { # }; # # // Now, create a verifier with a helper using the given Certs. -# let mut verifier = Verifier::from_bytes(policy, signed_message, helper, None)?; +# let mut verifier = VerifierBuilder::from_bytes(signed_message)? +# .with_policy(policy, None, helper)?; # # // Verify the data. # io::copy(&mut verifier, sink)?; @@ -253,7 +255,7 @@ fn generate() -> openpgp::Result<openpgp::Cert> { # } # # impl<'a> VerificationHelper for Helper<'a> { -# fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) +# fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) # -> openpgp::Result<Vec<openpgp::Cert>> { # // Return public keys for signature verification here. # Ok(vec![self.cert.clone()]) @@ -312,7 +314,7 @@ implements [`io::Write`], and we simply write the plaintext to it. # use openpgp::cert::prelude::*; # use openpgp::serialize::stream::*; # use openpgp::packet::prelude::*; -# use openpgp::parse::stream::*; +# use openpgp::parse::{Parse, stream::*}; # use openpgp::policy::Policy; # use openpgp::policy::StandardPolicy as P; # @@ -388,7 +390,8 @@ fn sign(policy: &dyn Policy, # }; # # // Now, create a verifier with a helper using the given Certs. -# let mut verifier = Verifier::from_bytes(policy, signed_message, helper, None)?; +# let mut verifier = VerifierBuilder::from_bytes(signed_message)? +# .with_policy(policy, None, helper)?; # # // Verify the data. # io::copy(&mut verifier, sink)?; @@ -401,7 +404,7 @@ fn sign(policy: &dyn Policy, # } # # impl<'a> VerificationHelper for Helper<'a> { -# fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) +# fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) # -> openpgp::Result<Vec<openpgp::Cert>> { # // Return public keys for signature verification here. # Ok(vec![self.cert.clone()]) @@ -452,12 +455,12 @@ control flow is determined by the message being processed. To use Sequoia's low-level streaming verifier, we need to provide an object that implements [`VerificationHelper`]. This object provides -public and for the signature verification, and implements the +certificates for the signature verification, and implements the signature verification policy. [`VerificationHelper`]: ../../sequoia_openpgp/parse/stream/trait.VerificationHelper.html -To decrypt messages, we create a [`Verifier`] with our helper. +To verify messages, we create a [`Verifier`] with our helper. Verified data can be read from this using [`io::Read`]. [`Verifier`]: ../../sequoia_openpgp/parse/stream/struct.Verifier.html @@ -471,7 +474,7 @@ Verified data can be read from this using [`io::Read`]. # use openpgp::cert::prelude::*; # use openpgp::serialize::stream::*; # use openpgp::packet::prelude::*; -# use openpgp::parse::stream::*; +# use openpgp::parse::{Parse, stream::*}; # use openpgp::policy::Policy; # use openpgp::policy::StandardPolicy as P; # @@ -547,7 +550,8 @@ fn verify(policy: &dyn Policy, }; // Now, create a verifier with a helper using the given Certs. - let mut verifier = Verifier::from_bytes(policy, signed_message, helper, None)?; + let mut verifier = VerifierBuilder::from_bytes(signed_message)? + .with_policy(policy, None, helper)?; // Verify the data. io::copy(&mut verifier, sink)?; @@ -560,7 +564,7 @@ struct Helper<'a> { } impl<'a> VerificationHelper for Helper<'a> { - fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) + fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) -> openpgp::Result<Vec<openpgp::Cert>> { // Return public keys for signature verification here. Ok(vec![self.cert.clone()]) diff --git a/guide/src/chapter_02.md b/guide/src/chapter_02.md index 3b95e516..fe7e9856 100644 --- a/guide/src/chapter_02.md +++ b/guide/src/chapter_02.md @@ -16,7 +16,7 @@ use openpgp::cert::prelude::*; use openpgp::crypto::SessionKey; use openpgp::types::SymmetricAlgorithm; use openpgp::serialize::stream::*; -use openpgp::parse::stream::*; +use openpgp::parse::{Parse, stream::*}; use openpgp::policy::Policy; use openpgp::policy::StandardPolicy as P; @@ -55,23 +55,16 @@ fn main() { # fn encrypt(policy: &dyn Policy, # sink: &mut Write, plaintext: &str, recipient: &openpgp::Cert) # -> openpgp::Result<()> { -# // Build a vector of recipients to hand to Encryptor. -# let mut recipients = +# let recipients = # recipient.keys().with_policy(policy, None).alive().revoked(false) -# .for_transport_encryption() -# .map(|ka| ka.key().into()) -# .collect::<Vec<_>>(); +# .for_transport_encryption(); # # // Start streaming an OpenPGP message. # let message = Message::new(sink); # -# // We want to encrypt a literal data packet. -# let mut encryptor = Encryptor::for_recipient( -# message, recipients.pop().expect("No encryption key found")); -# for r in recipients { -# encryptor = encryptor.add_recipient(r) -# } -# let encryptor = encryptor.build().expect("Failed to create encryptor"); +# // We want to encrypt a literal data packet. +# let encryptor = Encryptor::for_recipients(message, recipients) +# .build()?; # # // Emit a literal data packet. # let mut literal_writer = LiteralWriter::new(encryptor).build()?; @@ -93,12 +86,13 @@ fn main() { # // Make a helper that that feeds the recipient's secret key to the # // decryptor. # let helper = Helper { -# policy: policy, +# policy, # secret: recipient, # }; # # // Now, create a decryptor with a helper using the given Certs. -# let mut decryptor = Decryptor::from_bytes(policy, ciphertext, helper, None)?; +# let mut decryptor = DecryptorBuilder::from_bytes(ciphertext)? +# .with_policy(policy, None, helper)?; # # // Decrypt the data. # io::copy(&mut decryptor, sink)?; @@ -112,7 +106,7 @@ fn main() { # } # # impl<'a> VerificationHelper for Helper<'a> { -# fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) +# fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) # -> openpgp::Result<Vec<openpgp::Cert>> { # // Return public keys for signature verification here. # Ok(Vec::new()) @@ -132,7 +126,7 @@ fn main() { # sym_algo: Option<SymmetricAlgorithm>, # mut decrypt: D) # -> openpgp::Result<Option<openpgp::Fingerprint>> -# where D: FnMut(SymmetricAlgorithm, &SessionKey) -> openpgp::Result<()> +# where D: FnMut(SymmetricAlgorithm, &SessionKey) -> bool # { # // The encryption key is the first and only subkey. # let key = self.secret.keys().unencrypted_secret() @@ -143,10 +137,11 @@ fn main() { # let mut pair = key.into_keypair().unwrap(); # # pkesks[0].decrypt(&mut pair, sym_algo) -# .and_then(|(algo, session_key)| decrypt(algo, &session_key)) -# .map(|_| None) +# .map(|(algo, session_key)| decrypt(algo, &session_key)); +# # // XXX: In production code, return the Fingerprint of the # // recipient's Cert here +# Ok(None) # } # } ``` @@ -167,7 +162,7 @@ create it: # use openpgp::crypto::SessionKey; # use openpgp::types::SymmetricAlgorithm; # use openpgp::serialize::stream::*; -# use openpgp::parse::stream::*; +# use openpgp::parse::{Parse, stream::*}; # use openpgp::policy::Policy; # use openpgp::policy::StandardPolicy as P; # @@ -206,23 +201,16 @@ fn generate() -> openpgp::Result<openpgp::Cert> { # fn encrypt(policy: &dyn Policy, # sink: &mut Write, plaintext: &str, recipient: &openpgp::Cert) # -> openpgp::Result<()> { -# // Build a vector of recipients to hand to Encryptor. -# let mut recipients = +# let recipients = # recipient.keys().with_policy(policy, None).alive().revoked(false) -# .for_transport_encryption() -# .map(|ka| ka.key().into()) -# .collect::<Vec<_>>(); +# .for_transport_encryption(); # # // Start streaming an OpenPGP message. # let message = Message::new(sink); # -# // We want to encrypt a literal data packet. -# let mut encryptor = Encryptor::for_recipient( -# message, recipients.pop().expect("No encryption key found")); -# for r in recipients { -# encryptor = encryptor.add_recipient(r) -# } -# let encryptor = encryptor.build().expect("Failed to create encryptor"); +# // We want to encrypt a literal data packet. +# let encryptor = Encryptor::for_recipients(message, recipients) +# .build()?; # # // Emit a literal data packet. # let mut literal_writer = LiteralWriter::new(encryptor).build()?; @@ -244,12 +232,13 @@ fn generate() -> openpgp::Result<openpgp::Cert> { # // Make a helper that that feeds the recipient's secret key to the # // decryptor. # let helper = Helper { -# policy: policy, +# policy, # secret: recipient, # }; # # // Now, create a decryptor with a helper using the given Certs. -# let mut decryptor = Decryptor::from_bytes(policy, ciphertext, helper, None)?; +# let mut decryptor = DecryptorBuilder::from_bytes(ciphertext)? +# .with_policy(policy, None, helper)?; # # // Decrypt the data. # io::copy(&mut decryptor, sink)?; @@ -263,7 +252,7 @@ fn generate() -> openpgp::Result<openpgp::Cert> { # } # # impl<'a> VerificationHelper for Helper<'a> { -# fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) +# fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) # -> openpgp::Result<Vec<openpgp::Cert>> { # // Return public keys for signature verification here. # Ok(Vec::new()) @@ -283,7 +272,7 @@ fn generate() -> openpgp::Result<openpgp::Cert> { # sym_algo: Option<SymmetricAlgorithm>, # mut decrypt: D) # -> openpgp::Result<Option<openpgp::Fingerprint>> -# where D: FnMut(SymmetricAlgorithm, &SessionKey) -> openpgp::Result<()> +# where D: FnMut(SymmetricAlgorithm, &SessionKey) -> bool # { # // The encryption key is the first and only subkey. # let key = self.secret.keys().unencrypted_secret() @@ -294,10 +283,11 @@ fn generate() -> openpgp::Result<openpgp::Cert> { # let mut pair = key.into_keypair().unwrap(); # # pkesks[0].decrypt(&mut pair, sym_algo) -# .and_then(|(algo, session_key)| decrypt(algo, &session_key)) -# .map(|_| None) +# .map(|(algo, session_key)| decrypt(algo, &session_key)); +# # // XXX: In production code, return the Fingerprint of the # // recipient's Cert here +# Ok(None) # } # } ``` @@ -318,7 +308,7 @@ implements [`io::Write`], and we simply write the plaintext to it. # use openpgp::crypto::SessionKey; # use openpgp::types::SymmetricAlgorithm; # use openpgp::serialize::stream::*; -# use openpgp::parse::stream::*; +# use openpgp::parse::{Parse, stream::*}; # use openpgp::policy::Policy; # use openpgp::policy::StandardPolicy as P; # @@ -357,23 +347,16 @@ implements [`io::Write`], and we simply write the plaintext to it. fn encrypt(policy: &dyn Policy, sink: &mut Write, plaintext: &str, recipient: &openpgp::Cert) -> openpgp::Result<()> { - // Build a vector of recipients to hand to Encryptor. - let mut recipients = + let recipients = recipient.keys().with_policy(policy, None).alive().revoked(false) - .for_transport_encryption() - .map(|ka| ka.key().into()) - .collect::<Vec<_>>(); + .for_transport_encryption(); // Start streaming an OpenPGP message. let message = Message::new(sink); // We want to encrypt a literal data packet. - let mut encryptor = Encryptor::for_recipient( - message, recipients.pop().expect("No encryption key found")); - for r in recipients { - encryptor = encryptor.add_recipient(r) - } - let encryptor = encryptor.build().expect("Failed to create encryptor"); + let encryptor = Encryptor::for_recipients(message, recipients) + .build()?; // Emit a literal data packet. let mut literal_writer = LiteralWriter::new(encryptor).build()?; @@ -395,12 +378,13 @@ fn encrypt(policy: &dyn Policy, # // Make a helper that that feeds the recipient's secret key to the # // decryptor. # let helper = Helper { -# policy: policy, +# policy, # secret: recipient, # }; # # // Now, create a decryptor with a helper using the given Certs. -# let mut decryptor = Decryptor::from_bytes(policy, ciphertext, helper, None)?; +# let mut decryptor = DecryptorBuilder::from_bytes(ciphertext)? +# .with_policy(policy, None, helper)?; # # // Decrypt the data. # io::copy(&mut decryptor, sink)?; @@ -414,7 +398,7 @@ fn encrypt(policy: &dyn Policy, # } # # impl<'a> VerificationHelper for Helper<'a> { -# fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) +# fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) # -> openpgp::Result<Vec<openpgp::Cert>> { # // Return public keys for signature verification here. # Ok(Vec::new()) @@ -434,7 +418,7 @@ fn encrypt(policy: &dyn Policy, # sym_algo: Option<SymmetricAlgorithm>, # mut decrypt: D) # -> openpgp::Result<Option<openpgp::Fingerprint>> -# where D: FnMut(SymmetricAlgorithm, &SessionKey) -> openpgp::Result<()> +# where D: FnMut(SymmetricAlgorithm, &SessionKey) -> bool # { # // The encryption key is the first and only subkey. # let key = self.secret.keys().unencrypted_secret() @@ -445,10 +429,11 @@ fn encrypt(policy: &dyn Policy, # let mut pair = key.into_keypair().unwrap(); # # pkesks[0].decrypt(&mut pair, sym_algo) -# .and_then(|(algo, session_key)| decrypt(algo, &session_key)) -# .map(|_| None) +# .map(|(algo, session_key)| decrypt(algo, &session_key)); +# # // XXX: In production code, return the Fingerprint of the # // recipient's Cert here +# Ok(None) # } # } ``` @@ -483,7 +468,7 @@ Decrypted data can be read from this using [`io::Read`]. # use openpgp::crypto::SessionKey; # use openpgp::types::SymmetricAlgorithm; # use openpgp::serialize::stream::*; -# use openpgp::parse::stream::*; +# use openpgp::parse::{Parse, stream::*}; # use openpgp::policy::Policy; # use openpgp::policy::StandardPolicy as P; # @@ -522,23 +507,16 @@ Decrypted data can be read from this using [`io::Read`]. # fn encrypt(policy: &dyn Policy, # sink: &mut Write, plaintext: &str, recipient: &openpgp::Cert) # -> openpgp::Result<()> { -# // Build a vector of recipients to hand to Encryptor. -# let mut recipients = +# let recipients = # recipient.keys().with_policy(policy, None).alive().revoked(false) -# .for_transport_encryption() -# .map(|ka| ka.key().into()) -# .collect::<Vec<_>>(); +# .for_transport_encryption(); # # // Start streaming an OpenPGP message. # let message = Message::new(sink); # -# // We want to encrypt a literal data packet. -# let mut encryptor = Encryptor::for_recipient( -# message, recipients.pop().expect("No encryption key found")); -# for r in recipients { -# encryptor = encryptor.add_recipient(r) -# } -# let encryptor = encryptor.build().expect("Failed to create encryptor"); +# // We want to encrypt a literal data packet. +# let encryptor = Encryptor::for_recipients(message, recipients) +# .build()?; # # // Emit a literal data packet. # let mut literal_writer = LiteralWriter::new(encryptor).build()?; @@ -560,12 +538,13 @@ fn decrypt(policy: &dyn Policy, // Make a helper that that feeds the recipient's secret key to the // decryptor. let helper = Helper { - policy: policy, + policy, secret: recipient, }; // Now, create a decryptor with a helper using the given Certs. - let mut decryptor = Decryptor::from_bytes(policy, ciphertext, helper, None)?; + let mut decryptor = DecryptorBuilder::from_bytes(ciphertext)? + .with_policy(policy, None, helper)?; // Decrypt the data. io::copy(&mut decryptor, sink)?; @@ -579,7 +558,7 @@ struct Helper<'a> { } impl<'a> VerificationHelper for Helper<'a> { - fn get_public_keys(&mut self, _ids: &[openpgp::KeyHandle]) + fn get_certs(&mut self, _ids: &[openpgp::KeyHandle]) -> openpgp::Result<Vec<openpgp::Cert>> { // Return public keys for signature verification here. Ok(Vec::new()) @@ -599,7 +578,7 @@ impl<'a> DecryptionHelper for Helper<'a> { sym_algo: Option<SymmetricAlgorithm>, mut decrypt: D) -> openpgp::Result<Option<openpgp::Fingerprint>> - where D: FnMut(SymmetricAlgorithm, &SessionKey) -> openpgp::Result<()> + where D: FnMut(SymmetricAlgorithm, &SessionKey) -> bool { // The encryption key is the first and only subkey. let key = self.secret.keys().unencrypted_secret() @@ -610,10 +589,11 @@ impl<'a> DecryptionHelper for Helper<'a> { let mut pair = key.into_keypair().unwrap(); pkesks[0].decrypt(&mut pair, sym_algo) - .and_then(|(algo, session_key)| decrypt(algo, &session_key)) - .map(|_| None) + .map(|(algo, session_key)| decrypt(algo, &session_key)); + // XXX: In production code, return the Fingerprint of the // recipient's Cert here + Ok(None) } } ``` diff --git a/guide/src/chapter_03.md b/guide/src/chapter_03.md index 91f07b04..4d48717c 100644 --- a/guide/src/chapter_03.md +++ b/guide/src/chapter_03.md @@ -95,13 +95,13 @@ fn main() { [`PacketPile`]s are unstructured sequences of OpenPGP packets. Packet piles can be inspected, manipulated, validated using a formal grammar and thereby turned into [`Message`]s or [`Cert`]s using -[`Message::from_packet_pile`] or [`Cert::from_packet_pile`], or just +[`Message::try_from`] or [`Cert::try_from`], or just turned into a vector of [`Packet`]s: [`PacketPile`]: ../../sequoia_openpgp/struct.PacketPile.html [`Packet`]: ../../sequoia_openpgp/enum.Packet.html -[`Cert::from_packet_pile`]: ../../sequoia_openpgp/cert/struct.Cert.html#method.from_packet_pile -[`Message::from_packet_pile`]: ../../sequoia_openpgp/struct.Message.html#method.from_packet_pile +[`Cert::try_from`]: ../../sequoia_openpgp/cert/struct.Cert.html#method.try_from +[`Message::try_from`]: ../../sequoia_openpgp/struct.Message.html#method.try_from ```rust extern crate sequoia_openpgp as openpgp; |