mail-auth

mail-auth is a Rust library for authenticating and reporting on email messages, implementing the full stack of anti-spoofing protocols: DKIM (both the established RFC 6376 v1 and the emerging DKIM2 successor draft), SPF, DMARC, and the now-historic ARC. It signs outgoing mail and verifies incoming signatures, evaluates SPF and DMARC policy, and parses or generates the aggregate/failure reports (DMARC, ARF, SMTP TLS Reporting) that mail servers exchange to monitor authentication health across the ecosystem.

The crate is built for embedding inside a mail transfer agent: crypto and DNS backends are selected at compile time via Cargo features, so the same protocol code runs against aws-lc-rs, ring, or a pure-Rust crypto stack, and against a native hickory-resolver DNS client or a DNS-over-HTTPS resolver for WebAssembly targets. It underpins the email-authentication engine in Stalwart Mail Server, and is fuzzed, feature-matrix tested, and covered by clippy/fmt CI checks.

What You Get

• DKIM1 and DKIM2 signing/verification with RSA-SHA256, RSA-SHA1, and ED25519-SHA256, including DKIM2’s multi-selector “algorithmic dexterity” and SMTP-envelope binding
• SPF policy evaluation for HELO and MAIL FROM identities, plus SPF failure reporting in Abuse Reporting Format
• DMARC policy evaluation, aggregate report parsing/generation, and A-label-aware identifier alignment
• ARC chain verification and sealing, gated behind an opt-in feature since the protocol was reclassified as historic
• MTA-STS and SMTP TLS Reporting policy/report parsing
• A pluggable crypto backend (aws-lc-rs, ring, or pure-Rust) and DNS resolver (native hickory-resolver or DNS-over-HTTPS), including WebAssembly support

Common Use Cases

• Signing outbound mail with DKIM or DKIM2 before handoff to an MTA
• Verifying inbound DKIM/DKIM2 signatures, SPF, and DMARC alignment to score a message’s authenticity
• Generating and parsing DMARC aggregate reports for a domain’s authentication-monitoring dashboard
• Sealing and verifying ARC chains when relaying mail through intermediaries that modify messages
• Running email authentication checks inside a WASM-compiled edge function or browser extension

Under The Hood

Architecture Protocol logic is organized one module per standard (dkim, dkim2, arc, dmarc, spf, mta_sts, report), each split into parse/verify/sign/canonicalize/builder files, sitting on top of a shared common/ layer that abstracts crypto (common/crypto), DNS resolution and caching (common/resolver, common/cache), and header parsing. The public entry point composes verify_dkim/verify_dkim2/verify_spf/verify_dmarc/verify_arc calls against a MessageAuthenticator, which is built against a selected DNS backend. Protocol code depends on trait abstractions (a signing-key trait in common/crypto, a resolver abstraction in common/resolver) rather than concrete implementations, so swapping the crypto or DNS backend never touches protocol logic; lib.rs enforces the DNS choice at compile time with mutually exclusive compile_error! guards. This is a clear, modular, layered design well suited to embedding inside a larger mail server without pulling in unwanted dependencies.

Tech Stack Rust (2024 edition), published on crates.io. Core dependencies include mail-parser and mail-builder for MIME handling, idna for internationalized domain conversion, and rustls-pki-types. Crypto is selectable among aws-lc-rs (default), ring, or a pure-Rust rsa/ed25519-dalek/sha1/sha2 stack for WASM targets. DNS is selectable between hickory-resolver (native UDP/TCP/TLS with DNSSEC) and a reqwest-based DNS-over-HTTPS resolver for WebAssembly/edge runtimes. DMARC/TLS-RPT report handling uses quick-xml and zip (flate2-backed). Dev-dependencies bring in tokio, testcontainers, and tempfile for integration tests. CI runs cargo fmt —check and clippy -D warnings across two feature-flag matrices, then cargo test for both.

Code Quality Dozens of unit and async tests are spread across the protocol modules, backed by a dedicated fuzz target (cargo-fuzz) and a live-network integration test. Errors are explicit and typed per protocol (dedicated DkimError/Dkim2Error enums, the latter including a ChainTooLong variant) rather than swallowed with unwrap in library code. Naming mirrors RFC terminology closely (DkimSigner, ArcSealer, SpfParameters), and recent changelog entries show active security hardening — bounding decompressed report sizes and capping DKIM2 chain length against malicious input. Lint and formatting are enforced in CI, not just recommended.

What Makes It Unique mail-auth is one of the few Rust crates implementing the entire email-authentication stack — DKIM, the not-yet-finalized DKIM2 successor draft, SPF, DMARC, ARC, MTA-STS/TLS-RPT, and ARF abuse reporting — in a single library, and it appears to be an early reference implementation of DKIM2’s multi-algorithm “algorithmic dexterity” and SMTP-envelope-bound chain verification. It also compiles to WebAssembly with a pure-Rust crypto backend and browser-Fetch-based DNS-over-HTTPS, letting authentication checks run in edge or browser runtimes where synchronous DNS and OpenSSL-linked crypto aren’t options.