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.