/ 
Mail-DKIM2-0.14
/ Mail::DKIM2::Gate

NAME

Mail::DKIM2::Gate - decide whether a front end may sign a message

SYNOPSIS

my $g = Mail::DKIM2::Gate->check($message,
    PubkeyCallback => $cb, SkipTimestampCheck => 0,
    AllowNullBodyRecipe => 0);
unless ($g->{ok}) { warn "not signing: $g->{message}" }

DESCRIPTION

The gate shared by bin/dkim2sign and bin/dkim2-milter. Mail::DKIM2::Signer itself signs whatever it is given; a front end that extends a DKIM2 chain should first make sure the chain is worth extending.

check

Mail::DKIM2::Gate->check($message, %opts) takes the whole message as a string (CRLF line endings) and returns a hashref. Options: PubkeyCallback and SkipTimestampCheck are passed to the Verifier, AllowNullBodyRecipe permits a top Message-Instance whose body Recipe is null, SigningDomain is the d= the caller will sign with: when the top upstream signature carries nd= the gate passes only if it equals that domain (case-insensitive) and refuses otherwise ("top signature nd=X names another domain"); without it a top nd= is refused as before. VerifyResult supplies an already-computed verifier result so the upstream signatures are not verified again.

The upstream DKIM2-Signatures are verified with a Verifier that allows an unsigned Message-Instance above the top signature (the one the caller is about to sign), and the Message-Instance chain must match the content and undo cleanly down to m=1, including the header history below a null body Recipe.

The result has ok (true to sign), verify_result (none without a DKIM2-Signature), has_chain, top_null and, when refusing, reason (upstream-chain, broken-mi-chain or null-body-recipe) and a human-readable message.