Module sequoia_openpgp::parse::stream[−][src]

Expand description

Streaming decryption and verification.

This module provides convenient filters for decryption and verification of OpenPGP messages (see Section 11.3 of RFC 4880). It is the preferred interface to process OpenPGP messages:

Use the Verifier to verify a signed message,
DetachedVerifier to verify a detached signature,
or Decryptor to decrypt and verify an encrypted and possibly signed message.

Consuming OpenPGP messages is more difficult than producing them. When we produce the message, we control the packet structure being generated using our programs control flow. However, when we consume a message, the control flow is determined by the message being processed.

To use Sequoia’s streaming Verifier and Decryptor, you need to provide an object that implements VerificationHelper, and for the Decryptor also DecryptionHelper.

The VerificationHelper trait give certificates for the signature verification to the Verifier or Decryptor, let you inspect the message structure (see Section 11.3 of RFC 4880), and implements the signature verification policy.

The DecryptionHelper trait is concerned with producing the session key to decrypt a message, most commonly by decrypting one of the messages’ PKESK or SKESK packets. It could also use a cached session key, or one that has been explicitly provided to the decryption operation.

The Verifier and Decryptor are filters: they consume OpenPGP data from a reader, file, or bytes, and implement io::Read that can be used to read the verified and/or decrypted data.

DetachedVerifier does not provide the io::Read interface, because in this case, the data to be verified is easily available without any transformation. Not providing a filter-like interface allows for a very performant implementation of the verification.

Examples

This example demonstrates how to use the streaming interface using the Verifier. For brevity, no certificates are fed to the verifier, and the message structure is not verified, i.e. this merely extracts the literal data. See the Verifier examples and the Decryptor examples for how to verify the message and its structure.

use std::io::Read;
use sequoia_openpgp as openpgp;
use openpgp::{KeyHandle, Cert, Result};
use openpgp::parse::{Parse, stream::*};
use openpgp::policy::StandardPolicy;

let p = &StandardPolicy::new();

// This fetches keys and computes the validity of the verification.
struct Helper {};
impl VerificationHelper for Helper {
    fn get_certs(&mut self, _ids: &[KeyHandle]) -> Result<Vec<Cert>> {
        Ok(Vec::new()) // Feed the Certs to the verifier here...
    }
    fn check(&mut self, structure: MessageStructure) -> Result<()> {
        Ok(()) // Implement your verification policy here.
    }
}

let message =
   b"-----BEGIN PGP MESSAGE-----

     xA0DAAoWBpwMNI3YLBkByxJiAAAAAABIZWxsbyBXb3JsZCHCdQQAFgoAJwWCW37P
     8RahBI6MM/pGJjN5dtl5eAacDDSN2CwZCZAGnAw0jdgsGQAAeZQA/2amPbBXT96Q
     O7PFms9DRuehsVVrFkaDtjN2WSxI4RGvAQDq/pzNdCMpy/Yo7AZNqZv5qNMtDdhE
     b2WH5lghfKe/AQ==
     =DjuO
     -----END PGP MESSAGE-----";

let h = Helper {};
let mut v = VerifierBuilder::from_bytes(&message[..])?
    .with_policy(p, None, h)?;

let mut content = Vec::new();
v.read_to_end(&mut content)?;
assert_eq!(content, b"Hello World!");