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 frommessage; empty when none were. - restart
-
True when
removedis every instance the message had andinstanceis the singlem=1that 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 getsm=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 inremoved).restart: seeOutbound. 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) andbad-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.
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.