Trait sequoia_openpgp::parse::stream::VerificationHelper

pub trait VerificationHelper {
    // Required methods
    fn get_certs(&mut self, ids: &[KeyHandle]) -> Result<Vec<Cert>>;
    fn check(&mut self, structure: MessageStructure<'_>) -> Result<()>;

    // Provided method
    fn inspect(&mut self, pp: &PacketParser<'_>) -> Result<()> { ... }
}

Helper for signature verification.

This trait abstracts over signature and message structure verification. It allows us to provide the Verifier, DetachedVerifier, and Decryptor without imposing a policy on how certificates for signature verification are looked up, or what message structure is considered acceptable.

It also allows you to inspect each packet that is processed during verification or decryption, optionally providing a Map for each packet.

Required Methods

fn get_certs(&mut self, ids: &[KeyHandle]) -> Result<Vec<Cert>>

Retrieves the certificates containing the specified keys.

When implementing this method, you should return as many certificates corresponding to the ids as you can.

If an identifier is ambiguous, because, for instance, there are multiple certificates with the same Key ID, then you should return all of them.

You should only return an error if processing should be aborted. In general, you shouldn’t return an error if you don’t have a certificate for a given identifier: if there are multiple signatures, then, depending on your policy, verifying a subset of them may be sufficient.

This method will be called at most once per message.

Examples

This example demonstrates how to look up the certificates for the signature verification given the list of signature issuers.

use sequoia_openpgp as openpgp;
use openpgp::{KeyHandle, Cert, Result};
use openpgp::parse::stream::*;

struct Helper { /* ... */ };
impl VerificationHelper for Helper {
    fn get_certs(&mut self, ids: &[KeyHandle]) -> Result<Vec<Cert>> {
        let mut certs = Vec::new();
        for id in ids {
            certs.push(lookup_cert_by_handle(id)?);
        }
        Ok(certs)
    }
    // ...
}

fn check(&mut self, structure: MessageStructure<'_>) -> Result<()>

Validates the message structure.

This function must validate the message’s structure according to an application specific policy. For example, it could check that the required number of signatures or notarizations were confirmed as good, and evaluate every signature’s validity under an trust model.

A valid OpenPGP message contains one literal data packet with optional encryption, signing, and compression layers on top. Notably, the message structure contains the results of signature verifications. See MessageStructure for more information.

When verifying a message, this callback will be called exactly once per message after the last signature has been verified and before all of the data has been returned. Any error returned by this function will abort reading, and the error will be propagated via the io::Read operation.

After this method was called, Verifier::message_processed and Decryptor::message_processed return true.

When verifying a detached signature using the DetachedVerifier, this method will be called with a MessageStructure containing exactly one layer, a signature group.

Examples

This example demonstrates how to verify that the message is an encrypted, optionally compressed, and signed message that has at least one valid signature.

use sequoia_openpgp as openpgp;
use openpgp::{KeyHandle, Cert, Result};
use openpgp::parse::stream::*;

struct Helper { /* ... */ };
impl VerificationHelper for Helper {
    fn check(&mut self, structure: MessageStructure) -> Result<()> {
        for (i, layer) in structure.into_iter().enumerate() {
            match layer {
                MessageLayer::Encryption { .. } if i == 0 => (),
                MessageLayer::Compression { .. } if i == 1 => (),
                MessageLayer::SignatureGroup { ref results }
                    if i == 1 || i == 2 =>
                {
                    if ! results.iter().any(|r| r.is_ok()) {
                        return Err(anyhow::anyhow!(
                                       "No valid signature"));
                    }
                }
                _ => return Err(anyhow::anyhow!(
                                    "Unexpected message structure")),
            }
        }
        Ok(())
    }
    // ...
}

Provided Methods

fn inspect(&mut self, pp: &PacketParser<'_>) -> Result<()>

Inspects the message.

Called once per packet. Can be used to inspect and dump packets in encrypted messages.

The default implementation does nothing.

Implementors