[−][src]Module sequoia_guide::chapter_01
Describes key creation, signing and verification.
In this chapter, we will see how to use Sequoia's low-level API to
generate an OpenPGP key, and use it to sign and verify some data. We
will construct this program from top to bottom, concatenating the
fragments yields the openpgp/examples/generate-sign-verify.rs
.
use std::io::{self, Write}; use std::convert::TryInto; extern crate sequoia_openpgp as openpgp; use openpgp::cert::prelude::*; use openpgp::serialize::stream::*; use openpgp::packet::prelude::*; use openpgp::parse::{Parse, stream::*}; use openpgp::policy::Policy; use openpgp::policy::StandardPolicy as P; const MESSAGE: &'static str = "дружба"; fn main() -> openpgp::Result<()> { let p = &P::new(); // Generate a key. let key = generate()?; // Sign the message. let mut signed_message = Vec::new(); sign(p, &mut signed_message, MESSAGE, &key)?; // Verify the message. let mut plaintext = Vec::new(); verify(p, &mut plaintext, &signed_message, &key)?; assert_eq!(MESSAGE.as_bytes(), &plaintext[..]); Ok(()) }
Key generation
First, we need to generate a new key. This key shall have one user
id, and one signing-capable subkey. We use the CertBuilder
to
create it:
/// Generates an signing-capable key. fn generate() -> openpgp::Result<openpgp::Cert> { let (cert, _revocation) = CertBuilder::new() .add_userid("someone@example.org") .add_signing_subkey() .generate()?; // Save the revocation certificate somewhere. Ok(cert) }
Signing
To sign a message, we first compose a writer stack corresponding to
the desired output format and packet structure. The resulting object
implements io::Write
, and we simply write the plaintext to it.
/// Signs the given message. fn sign(policy: &dyn Policy, sink: &mut (dyn Write + Send + Sync), plaintext: &str, tsk: &openpgp::Cert) -> openpgp::Result<()> { // Get the keypair to do the signing from the Cert. let keypair = tsk .keys().unencrypted_secret() .with_policy(policy, None).alive().revoked(false).for_signing() .nth(0).unwrap().key().clone().into_keypair()?; // Start streaming an OpenPGP message. let message = Message::new(sink); // We want to sign a literal data packet. let message = Signer::new(message, keypair).build()?; // Emit a literal data packet. let mut message = LiteralWriter::new(message).build()?; // Sign the data. message.write_all(plaintext.as_bytes())?; // Finalize the OpenPGP message to make sure that all data is // written. message.finalize()?; Ok(()) }
Verification
Verification is more difficult than signing. When we sign, we control the packet structure being generated. However, when we verify, the 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
certificates for the signature verification, and implements the
signature verification policy.
To verify messages, we create a Verifier
with our helper.
Verified data can be read from this using io::Read
.
/// Verifies the given message. fn verify(policy: &dyn Policy, sink: &mut dyn Write, signed_message: &[u8], sender: &openpgp::Cert) -> openpgp::Result<()> { // Make a helper that that feeds the sender's public key to the // verifier. let helper = Helper { cert: sender, }; // Now, create a verifier with a helper using the given Certs. let mut verifier = VerifierBuilder::from_bytes(signed_message)? .with_policy(policy, None, helper)?; // Verify the data. io::copy(&mut verifier, sink)?; Ok(()) } struct Helper<'a> { cert: &'a openpgp::Cert, } impl<'a> VerificationHelper for Helper<'a> { 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()]) } fn check(&mut self, structure: MessageStructure) -> openpgp::Result<()> { // In this function, we implement our signature verification // policy. let mut good = false; for (i, layer) in structure.into_iter().enumerate() { match (i, layer) { // First, we are interested in signatures over the // data, i.e. level 0 signatures. (0, MessageLayer::SignatureGroup { results }) => { // Finally, given a VerificationResult, which only says // whether the signature checks out mathematically, we apply // our policy. match results.into_iter().next() { Some(Ok(_)) => good = true, Some(Err(e)) => return Err(openpgp::Error::from(e).into()), None => return Err(anyhow::anyhow!("No signature")), } }, _ => return Err(anyhow::anyhow!( "Unexpected message structure")), } } if good { Ok(()) // Good signature. } else { Err(anyhow::anyhow!("Signature verification failed")) } } }
Further reading
For more examples on how to read a key from a file, and then either
create a signed message, or a detached signature, see
openpgp/examples/sign.rs
and
openpgp/examples/sign-detached.rs
.