Struct viadkim::verifier::Verifier

pub struct Verifier { /* private fields */ }

A verifier of DKIM signatures in an email message.

Verifier is the high-level API for verifying a message. It implements a three-phase, staged design that allows processing the message in chunks, and shortcutting unnecessary body processing.

1. verify_header (async): first, perform signature verification on the message header and return a verifier that carries the preliminary results; this is where most of the actual work is done
2. process_body_chunk: then, any number of chunks of the message body are fed to the verification process
3. finish: finally, the body hashes are computed and the final verification results are returned

Compare this with the similar but distinct procedure of Signer.

For convenience, the free function verify can be used to perform all stages in one go.

Examples

The following example shows how to verify a message’s signatures using the high-level API.

use viadkim::*;

let header =
    "DKIM-Signature: v=1; d=example.com; s=selector; a=ed25519-sha256; c=relaxed;\r\n\
    \tt=1687435395; x=1687867395; h=Date:Subject:To:From; bh=1zGfaauQ3vmMhm21CGMC23\r\n\
    \taJE1JrOoKsgT/wvw9owzE=; b=neMHc/e6jrqSscL1pc/fTxOU/CjuvYzvnGbTABQvYkzlIvazqp3\r\n\
    \tiR7RXUZi0CbOAq13IEUZPc6S0/63cfAO4CA==\r\n\
    Received: from submit.example.com by mail.example.com\r\n\
    \twith ESMTPSA id A6DE7475; Thu, 22 Jun 2023 14:03:14 +0200\r\n\
    From: me@example.com\r\n\
    To: you@example.org\r\n\
    Subject: Re: Thursday 8pm\r\n\
    Date: Thu, 22 Jun 2023 14:03:12 +0200\r\n".parse()?;
let body = b"Hey,\r\n\
    \r\n\
    Ready for tonight? ;)\r\n";

// Note: Enable Cargo feature `hickory-resolver` to make an implementation
// of trait `LookupTxt` available for Hickory DNS’s `TokioAsyncResolver`.
let resolver /* = TokioAsyncResolver::tokio(...) */;

let config = Config::default();

let mut verifier = Verifier::verify_header(&resolver, &header, &config)
    .await
    .unwrap();

let _ = verifier.process_body_chunk(body);

let results = verifier.finish();

let signature = results.into_iter().next().unwrap();

assert_eq!(signature.status, VerificationStatus::Success);
assert_eq!(signature.status.to_dkim_result(), DkimResult::Pass);

See Signer for how the above example message was signed.

Implementations

impl Verifier

pub async fn verify_header<T>( resolver: &T, headers: &HeaderFields, config: &Config ) -> Option<Self>

where T: LookupTxt + Clone + 'static,

Initiates a message verification process by verifying the header of a message. Returns a verifier for all signatures in the given header, or None if the header contains no signatures.

The resolver parameter is a reference to a type that implements LookupTxt; the trait LookupTxt is an abstraction for DNS resolution. The parameter is also Clone, in order to share the resolver among concurrent key record lookup tasks.

pub fn process_body_chunk(&mut self, chunk: &[u8]) -> BodyHasherStance

Processes a chunk of the message body.

Clients should pass the message body either whole or in chunks of arbitrary size to this method in order to calculate the body hash (the bh= tag). The returned BodyHasherStance instructs the client how to proceed if more chunks are outstanding. Note that the given body chunk is canonicalised and hashed, but not otherwise retained in memory.

Remember that email message bodies generally use CRLF line endings; this is important for correct body hash calculation.

Examples

let _ = verifier.process_body_chunk(b"\
Hello friend!\r
\r
How are you?\r
");

pub fn finish(self) -> Vec<VerificationResult>

Finishes the verification process and returns the results.

The returned result vector is never empty.