Struct AuthenticatedMessage 

pub struct AuthenticatedMessage<'x> { /* private fields */ }

An RFC 5322 message prepared for DKIM, DKIM2, ARC and DMARC verification.

The message borrows the raw bytes it was parsed from. Parsing records the position of every header, the From addresses (used for DMARC, RFC 9989), the number of Received headers and the presence of Date and Message-ID. Authentication headers that fail to parse do not abort parsing: they are recorded in errors and flagged by has_dkim_errors, has_dkim2_errors and has_arc_errors.

Example

use mail_auth::AuthenticatedMessage;

let raw = b"From: jdoe@example.org\r\nSubject: Hi\r\n\r\nHello\r\n";
let message = AuthenticatedMessage::parse(raw).unwrap();
assert_eq!(message.first_from_address(), "jdoe@example.org");
assert_eq!(message.raw_body(), b"Hello\r\n");

Implementations

impl<'x> AuthenticatedMessage<'x>

pub fn canonicalized_dkim_headers(&self) -> Option<Vec<u8>>

Returns the canonicalized signed header fields of the first DKIM-Signature whose x= tag is absent or later than its t= tag.

The output is the header hash input of RFC 6376, Section 3.7: the headers listed in h=, followed by the DKIM-Signature header itself with an empty b= value, canonicalized with the signature’s header canonicalization. The current time is not checked. Returns None when the message has no such signature.

impl AuthenticatedMessage<'_>

pub fn dkim2_return_path(&self) -> Option<&str>

Returns the address a DSN about this message must be sent to.

This is the mf= (MAIL FROM) of the signature with the highest i=, including angle brackets. Returns None if the message has no DKIM2 signature, if that signature uses nd=, or if its MAIL FROM is the null reverse-path <>. Signatures that failed to parse are not considered, so when has_dkim2_errors is true the address may come from an older hop.

pub fn dkim2_dsn_domains(&self) -> impl Iterator<Item = &str>

Returns the domains that may sign a DSN about this message (§16.2).

pub fn dkim2_dsn_aligned(&self, domain: &str) -> bool

Returns true if domain may sign a DSN about this message (§16.2).

pub fn dkim2_arrival_headers(&self, hops: usize) -> Vec<u8>

Returns the header block as it was before the last hops DKIM2 signers handled it, for the returned part of a DSN (§16.3).

impl<'x> AuthenticatedMessage<'x>

pub fn parse(raw_message: &'x [u8]) -> Option<Self>

Parses a raw RFC 5322 message in strict mode.

Equivalent to parse_with_opts(raw_message, None, true). Returns None when no header could be parsed.

pub fn from_parsed<'y>( parsed: &'y Message<'x>, raw_message: &'x [u8], strict: bool, ) -> Self

Builds an AuthenticatedMessage from a message already parsed by mail_parser, reusing its header offsets instead of parsing again.

raw_message must be the exact bytes parsed was parsed from. Only the headers of the root part are read. strict has the same meaning as in parse_with_opts.

pub fn parse_with_opts( raw_message: &'x [u8], prepend_headers: Option<&'x [u8]>, strict: bool, ) -> Option<Self>

Parses a raw RFC 5322 message.

prepend_headers, when set, holds header lines that are parsed as if they appeared before the headers of raw_message (for example, headers added by the receiving MTA but not yet written to the message).

When strict is true, DKIM-Signature and ARC-Message-Signature headers that carry a body length tag (l=) are rejected and recorded as errors (DkimError::BodyLengthTag for DKIM, ArcError::BodyLengthTag for ARC), because a length limit lets an attacker append content to a signed body (RFC 6376 Section 8.2). When false, such signatures are kept.

Returns None when no header could be parsed.

pub fn received_headers_count(&self) -> usize

Returns the number of Received headers in the message.

pub fn has_message_id_header(&self) -> bool

Returns true if the message has a Message-ID header.

pub fn has_date_header(&self) -> bool

Returns true if the message has a Date header.

pub fn raw_message(&self) -> &[u8]

Returns the raw message bytes, headers and body.

pub fn raw_headers(&self) -> &[u8]

Returns the raw header section of the message, including the blank line that separates it from the body when one is present. Prepended headers are not included.

pub fn headers(&self) -> &[(&'x [u8], &'x [u8])]

Returns every header as a (name, value) pair of raw bytes, in message order. Prepended headers come first. The name excludes the colon; the value keeps its folding and the trailing line ending.

pub fn raw_body(&self) -> &[u8]

Returns the raw message body. Empty when the message has no body.

pub fn body_offset(&self) -> usize

Returns the byte offset of the body within raw_message.

pub fn from_addresses(&self) -> &[String]

Returns the lowercased addresses found in the From header, including the members of address groups.

pub fn first_from_address(&self) -> &str

Returns the first From address, or an empty string if there is none. This is the author address used for DMARC (RFC 9989).

pub fn dkim_signatures(&self) -> &[Header<'x, Signature>]

Returns the DKIM-Signature headers (RFC 6376) that parsed successfully, in message order.

pub fn dkim2_signatures(&self) -> &[Header<'x, Signature>]

Returns the DKIM2-Signature headers that parsed successfully, sorted by signature sequence number (i= tag).

pub fn dkim2_instances(&self) -> &[Header<'x, MessageInstance>]

Returns the Message-Instance headers that parsed successfully, sorted by revision number (m= tag).

pub fn errors(&self) -> &[Header<'x, Error>]

Returns the authentication headers that could not be parsed or were rejected, each paired with the reason.

pub fn has_dkim_errors(&self) -> bool

Returns true if a DKIM-Signature header failed to parse or was rejected (including by retain_dkim_signatures).

pub fn has_dkim2_errors(&self) -> bool

Returns true if a DKIM2-Signature or Message-Instance header failed to parse.

pub fn retain_dkim_signatures( &mut self, accept: impl FnMut(&Signature) -> Result<(), DkimError>, )

Keeps only the DKIM signatures accepted by accept.

accept is called once for every parsed DKIM-Signature. Signatures for which it returns Err are removed from dkim_signatures; the error is added to errors as Error::Dkim and has_dkim_errors becomes true, so verify_dkim reports each rejected signature as neutral with that error. Use it to apply a local policy, such as rejecting rsa-sha1 signatures, before verification.

Trait Implementations

impl<'x> AsRef<AuthenticatedMessage<'x>> for AuthenticatedMessage<'x>

fn as_ref(&self) -> &AuthenticatedMessage<'x>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'x> Clone for AuthenticatedMessage<'x>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'x> Debug for AuthenticatedMessage<'x>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'x> Default for AuthenticatedMessage<'x>

fn default() -> Self

Returns the “default value” for a type.

impl<'x> Eq for AuthenticatedMessage<'x>

impl<'x> From<&'x AuthenticatedMessage<'x>> for Parameters<'x, &'x AuthenticatedMessage<'x>, NoCache>

fn from(params: &'x AuthenticatedMessage<'x>) -> Self

Converts to this type from the input type.

impl<'x> PartialEq for AuthenticatedMessage<'x>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'x> StructuralPartialEq for AuthenticatedMessage<'x>

impl<'x> TryFrom<&'x Vec<u8>> for AuthenticatedMessage<'x>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &'x Vec<u8>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'x> TryFrom<&'x [u8]> for AuthenticatedMessage<'x>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &'x [u8]) -> Result<Self, Self::Error>

Performs the conversion.