NAME

Mail::DKIM2::Hop - What a hop adds to a message's Message-Instance fields before it signs

SYNOPSIS

use Mail::DKIM2::Hop;

my $next = Mail::DKIM2::Hop->next_instance($message,
    Snapshot => $as_it_arrived,    # if this host kept one
    Outbound => 1,                 # this hop is about to sign
);
if (my $mi = $next->{instance}) {
    $message = $mi->as_header . "\r\n" . $next->{message};
}
# ... then Mail::DKIM2::Gate->check and Mail::DKIM2::Signer

DESCRIPTION

A hop that signs a message first has to say what it is signing: a Message-Instance for the message as it now is, with Recipes back to what it was. Whether one is needed, which m= it gets and what it is a change from depend on what the message already carries and on what this host remembers of it. This module makes that decision in one place, for bin/dkim2-milter, Mail::Milter::Authentication::Handler::DKIM2Sign and bin/dkim2sign. It changes nothing: it returns the instance to add and the message to add it to. New in 0.31.

See "CONVENTIONS" in Mail::DKIM2 for the conventions every module follows.

CLASS METHODS

next_instance($message, %options)

$message is the whole message as a string with CRLF line endings. Options:

Snapshot

The message as this host last vouched for it -- as it arrived, typically -- as a string. It must be a snapshot of this very message: its Message-Instance fields have to be the message's own lower ones. Without one, a message whose top instance no longer matches gets no instance: only this host's own record can say what this hop changed.

Outbound

True for the hop that is about to sign. A message with instances and no DKIM2-Signature then leaves with a single m=1 (-09 section 12.1): every instance it carries is this host's own and unsigned, so they are replaced by one whose Recipes go back to the message as it was before the first of them.

IgnorePrefixes, MaxRecipeLiterals, Algs

As for "calculate($msg, [$previous], %options)" in Mail::DKIM2::MessageInstance.

Returns a hashref:

instance

The Mail::DKIM2::MessageInstance to add, or undef when none is needed or none can be justified.

message

The message the instance describes and is to be added to: $message, less any Message-Instance fields that have to go (removed).

removed

An arrayref of the m= numbers of the Message-Instance fields removed from message; empty when none were.

restart

True when removed is every instance the message had and instance is the single m=1 that replaces them.

matched

True when the top instance already described the message.

reason, detail

Why, as a word and as a sentence for a log. first: the message had no instance, and gets m=1. unchanged: the top instance describes the message; nothing to add. changed: the message differs from the snapshot; the instance has the Recipes back to it (and if the message had instances above the snapshot's, they were wrong and are in removed). restart: see Outbound. And with no instance: no-snapshot (the top instance does not match and there is no snapshot to explain it), foreign-snapshot (the snapshot is of another message) and bad-chain (the instances cannot be numbered, or do not undo). A message left without an instance for one of those is one Mail::DKIM2::Gate refuses.

Dies, as calculate does, if the instance cannot be computed.

snapshot_vouches

my ($ok, $why) = Mail::DKIM2::Hop->snapshot_vouches($message, $snapshot);

Is $snapshot a snapshot of this very message? True when the message has exactly the snapshot's DKIM2-Signature fields, and the Message-Instance fields those signatures cover, each the same apart from white space. Instances above the signatures are not compared: they are this host's own, and next_instance and Mail::DKIM2::Gate judge them.

A host that took the snapshot only of a message whose chain verified can then take the message's signatures as verified, and pass VerifyResult => 'pass' to the Gate. When it is false, $why says which field differs; such a message is not one to sign.

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.