NAME
Mail::DKIM2::Chain - The Message-Instance and DKIM2-Signature fields of a message, numbered
SYNOPSIS
use Mail::DKIM2::Chain;
my $chain = Mail::DKIM2::Chain->from_message($message);
if (my $error = $chain->structure_error) {
... # "PERMERROR: DKIM2-Signature i=2 missing"
}
my $top = $chain->top_signature; # a Mail::DKIM2::Signature
my ($mi, $why) = $chain->instance($chain->top_instance);
my @mine = $chain->unsigned_instances; # nobody has signed these yet
DESCRIPTION
What a message's DKIM2 fields say about themselves, before anything is checked against the content or a key: which Message-Instance and DKIM2-Signature fields there are, by number, whether those numbers form a chain, and how far up the signatures reach. Mail::DKIM2::Verifier, Mail::DKIM2::Signer and Mail::DKIM2::Gate all read a message's chain through one of these, so they agree on which fields count and name the same fault first. New in 0.31.
See "CONVENTIONS" in Mail::DKIM2 for the conventions every module follows.
CONSTRUCTORS
new()
An empty chain, to be filled with "add_field($name, $value, [$raw])".
from_fields(\@fields)
A chain from header fields given whole (name, value and any continuation lines), as Mail::DKIM2::HeaderParser keeps them in {headers}. Fields of other names are ignored.
from_message($text)
A chain from a message, or just its header block, as a string. Only the header fields are read, split as the Signer and the Verifier split them.
METHODS
add_field($name, $value, [$raw])
Adds one header field: its name, its value without the line break, and the field as it is in the message (used for the signing input; built from the other two if not given). Returns true if it was a Message-Instance or a DKIM2-Signature field. A field that cannot be numbered -- a DKIM2-Signature that does not parse or has no usable i= or m=, a Message-Instance without a usable m= -- is not skipped: it becomes the chain's "numbering_error(%options)". After 32 fields of either kind ("MAX_CHAIN_LENGTH" in Mail::DKIM2::Common) the rest are counted, not read.
count($field_name)
How many fields of that name the message had.
is_empty()
True when the message has neither kind of field.
instance_numbers(), signature_numbers()
The m= of every usable Message-Instance, and the i= of every usable DKIM2-Signature, ascending.
top_instance(), top_signature_number()
The highest of each, or undef.
instance_field($m), signature_field($i)
The field as it is in the message.
instance_fields(), signature_entries()
The whole of each map, as a hashref: m= to the field as it is in the message, and i= to { raw => $field, sig => $signature }. They are the chain's own; do not change them.
instance($m)
The parsed Mail::DKIM2::MessageInstance. In list context, ($instance) or (undef, $error), the error in the Verifier's words (PERMERROR: Message-Instance m=2 contains invalid JSON). Each instance is parsed once.
signature($i), signatures(), top_signature()
The parsed Mail::DKIM2::Signature objects: one, all in ascending i= order, or the highest (undef if none).
covered_m()
The highest m= any signature names, or 0: instances 1 to that are signed (-09 section 10.2).
unsigned_instances()
The m= of every instance above covered_m: those no signature covers yet, which the next signer answers for.
instances_changing($name, [$above], [$upto])
The m= of every instance above $above (default 0) and no higher than $upto (default the top) that has a header Recipe for the field named $name: the hops that say they changed it. m=1 never counts, and an instance that does not parse says nothing. The Signer and the Verifier use it to decide which signature answers for a From (-09 section 11).
numbering_error(%options)
The PERMERROR: ... string for a chain whose fields cannot be numbered, or undef: more than 32 fields of a kind, a field with no usable number, or a number given twice. Signatures => 0 leaves the DKIM2-Signature fields out of it, for a caller that has had them checked already.
structure_error(%options)
numbering_error, then (-09 section 14.2) a missing Message-Instance, an instance above every signature's m= ("is not signed"), and a missing DKIM2-Signature. AllowUnsigned => 1 permits the unsigned instance, for a signer that holds the one it is about to sign; Signatures => 0 checks the instances alone.
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.