NAME

Mail::Milter::Authentication::Handler::DKIM2Verify - Handler class for DKIM2 signature verification

DESCRIPTION

Verifies DKIM2 signatures and Chain of Custody on inbound email, adding Authentication-Results headers with the verification outcome.

This module implements draft-ietf-dkim-dkim2-spec-06; see "STATUS" in Mail::DKIM2 for what that means for the wire format and the API, and "CONVENTIONS" in Mail::DKIM2 for the option, input and error conventions every module here follows.

CONFIGURATION

"DKIM2Verify" : {
    "hide_none"            : 0,      | Hide auth line if result is 'none'
    "extra_properties"     : 0,      | Add extra properties to auth results
    "dns_overrides"        : null,   | Path to dns.json for testing
    "add_message_instance" : 1,      | Compute and add MI header on inbound
    "snapshot_directory"   : null     | Store message snapshots for egress diffing
}

When add_message_instance is enabled, the handler computes a Message-Instance header after successful DKIM2 verification and prepends it to the message.

When snapshot_directory is also set, the full message (with the new MI header) is stored to disk. The DKIM2Sign handler can later retrieve this snapshot to compute a diff-based MI when the message leaves the system, capturing any modifications made during local processing.

CALLBACKS

default_config()

Returns the default configuration hash for this handler.

register_metrics()

Returns the metrics hash for this handler (dkim2_verify_total).

envfrom_callback($env_from)

Resets per-message state and records the envelope sender.

header_callback($header, $value, $original)

Collects each header line and notes whether any DKIM2-Signature headers are present.

eoh_callback()

Called at end of headers. If DKIM2-Signature headers were seen, creates a Mail::DKIM2::Verifier, sets up the public key callback, and feeds the collected headers. If no signatures were found, adds a dkim2=none Authentication-Results header.

body_callback($body_chunk)

Feeds body data to the verifier, normalizing line endings to CRLF.

eom_callback()

Finalizes verification. Calls CLOSE() on the verifier, adds an Authentication-Results header with the outcome, and (if verification passed and configured) computes a Message-Instance header and stores a message snapshot.

close_callback()

Cleans up per-message state and destroys the verifier object.

AUTHOR

Bron Gondwana <brong@fastmailteam.com>

COPYRIGHT AND LICENSE

Copyright (c) 2025-2026 Fastmail Pty Ltd. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.