NAME
Mail::DKIM2::Common - Constants, chain numbering and the any/all groups shared by the DKIM2 modules
SYNOPSIS
use Mail::DKIM2::Common qw(DKIM2_DRAFT MAX_CHAIN_LENGTH chain_number_error);
# Everything that was here before 0.31 can still be imported from here:
use Mail::DKIM2::Common qw(fold_header load_private_key relaxed_domain_match);
DESCRIPTION
What the other modules share and none of them owns: the protocol's constants and this implementation's limits, the numbering of Message-Instance and DKIM2-Signature fields (and the PERMERROR strings for fields that cannot be numbered), and the "any of these groups, all of each" combination that h= and s= both use. Nothing is exported by default.
Until 0.31 this module also held the functions that are now in
- Mail::DKIM2::Canon
-
header canonicalization, the fields that are not hashed, the signing input;
- Mail::DKIM2::Fold
-
fold_header; - Mail::DKIM2::Address
-
envelope paths, domains, the relaxed domain match, the Authentic From check;
- Mail::DKIM2::Key
-
private keys, key records, Domain Policy Records, signing algorithms;
- Mail::DKIM2::RecipeJSON
-
the base64 JSON of an
r=tag.
Every one of them is still importable from here, and callable as Mail::DKIM2::Common::NAME, so existing callers need no change; they are documented where they now live.
This module implements draft-ietf-dkim-dkim2-spec-09; 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.
CONSTANTS
DKIM2_DRAFT, DKIM2_REPO, DKIM2_DATE
The spec revision implemented (ietf-dkim-dkim2-spec-09), where the code lives, and the date this implementation's DKIM2 behaviour last changed. Emitted in X-DKIM2-Info debug headers (draft-gondwana-dkim2-debug-header).
MAX_CHAIN_LENGTH
32: a message carrying more Message-Instance or DKIM2-Signature fields than this, or an i= or m= naming a larger number, is a PERMERROR, found before any key is fetched. Local policy, not spec.
MAX_CHAIN_NUMBER
99: the largest number an i= or m= may be written as (at most two digits). See "chain_number_error($field, $tag, $n)".
MAX_SIGNATURE_ITEMS
8: the most items one DKIM2-Signature's s= may carry. Local policy: -08 sets no limit, and each item may cost a key lookup and a signature check. The Verifier refuses a field with more, before fetching any key, as "has more than 8 signatures". New in 0.28.
CHAIN NUMBERS
mi_version_tag($header_value)
The raw m= value of a Message-Instance value with whitespace removed, or undef when there is none. Pass it to "chain_number_error($field, $tag, $n)" before trusting it.
extract_mi_version($header_value)
The m= number of a Message-Instance value, as a number (so 01 is 1), or undef when there is no m= or it is not all ASCII digits. Accepts a string, a scalar ref, or an arrayref (first element).
strip_mi_versions($message, @m)
Removes the Message-Instance fields with the given m= numbers from a CRLF message string and returns the result.
valid_sequence($i)
True when $i (a DKIM2-Signature i= value) is a positive integer written in ASCII digits. A signature whose i= is not is one no verifier can place in the chain or key: Mail::DKIM2::Verifier reports it as "UNKEYABLE_SIGNATURE_ERROR".
chain_number_error($field, $tag, $n, $ident)
The PERMERROR string for an i= or m= value that is not a chain number, or undef (also for an undefined $n, which is left to the caller). The field is named by its own number as written, $ident (default $n): a DKIM2-Signature by i=, a Message-Instance by m=. A value that is not 1*DIGIT in ASCII, or is zero, is "PERMERROR: $field i=$ident syntax error" (m= for a Message-Instance; -09 section 14.2). More than two digits or above "MAX_CHAIN_NUMBER" is "PERMERROR: DKIM2-Signature i=$ident exceeds the maximum chain number of 99", with " m=$n" after $ident for a signature's m=. Above "MAX_CHAIN_LENGTH", likewise "... exceeds the maximum chain length of 32": every i= and m= names one hop, so none can be larger than the chain. 01 and 001 are 1.
duplicate_number_error($field, $tag, @numbers)
The PERMERROR string for the first number that appears twice, or undef.
chain_length_error($msg_or_counts)
The PERMERROR string for a message over "MAX_CHAIN_LENGTH", or undef. Takes an Email::MIME or a hashref of field counts keyed by lowercased name.
UNKEYABLE_SIGNATURE_ERROR
The PERMERROR string for a DKIM2-Signature with no i= tag, or one that does not parse: "PERMERROR: DKIM2-Signature i= tag=i missing".
MI_MISSING_M_ERROR
The PERMERROR string for a Message-Instance with no m= tag: "PERMERROR: Message-Instance m= tag=m missing". New in 0.25.
unkeyable_signature_error($value)
The PERMERROR string for a DKIM2-Signature header value whose i= is missing ("UNKEYABLE_SIGNATURE_ERROR") or not a positive integer ("PERMERROR: DKIM2-Signature i=<as written> syntax error"). New in 0.23.
GROUPS
split_any_all($value)
The groups of an h= or s= value (-09 sections 9.3 and 10.9): an arrayref of |-separated groups, each an arrayref of its ,-separated members, untrimmed. Undef if any member is empty (a leading, trailing or doubled | or ,), which is a syntax error.
combine_sets(\@groups, $none_passed)
The overall ($state, $text) of an h= or s= value from its members' results (-09 sections 14.6 and 14.7). @groups holds one arrayref per | group, of [$state, $text] per member, $state being pass, fail, temperror or permerror. A group passes if every member does; is a temperror if every member that does not pass is one; else fails if any member fails; else is a permerror. The value passes if any group does; else is a temperror, fail or permerror if any group is, in that order. $text is the first member's (in value order) with the overall state, or $none_passed when several groups give a fail. A pass has no text.
PARSING
parse_mime($raw)
Parse $raw into an Email::MIME for the library's own use (raw header fields, raw body), with Email::MIME::ContentType's parameter check relaxed for the duration of the parse. DKIM2 never reads a MIME parameter, so a sender's broken Content-Type must not stop a message from being verified or make every verification warn. The package variable is restored afterwards.
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.