Module stream

Streaming decryption and verification.

This module provides convenient filters for decryption and verification of OpenPGP messages (see Section 10.3 of RFC 9580). 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 10.3 of RFC 9580), 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!");

Structs

Decryptor

Decrypts and verifies an encrypted and optionally signed OpenPGP message.

DecryptorBuilder

A builder for Decryptor.

DetachedVerifier

Verifies a detached signature.

DetachedVerifierBuilder

A builder for DetachedVerifier.

GoodChecksum

A good signature.

MessageStructure

Communicates the message structure to the VerificationHelper.

Verifier

Verifies a signed OpenPGP message.

VerifierBuilder

A builder for Verifier.

Enums

MessageLayer

Represents a layer of the message structure.

VerificationError

A bad signature.

Constants

DEFAULT_BUFFER_SIZE

How much data to buffer before giving it to the caller.

Traits

DecryptionHelper

Helper for decrypting messages.

VerificationHelper

Helper for signature verification.

Type Aliases

VerificationResult

Result of a signature verification.