NAME

Mailmunge::Action::DKIMSigner - Add a DKIM-Signature: header to a message

ABSTRACT

This class implements a method that adds a DKIM signature to a message.

SYNOPSIS

package MyFilter;
use base qw(Mailmunge::Filter);
use Mail::DKIM::Signer;
use Mail::DKIM::TextWrap;
use Mailmunge::Action::DKIMSigner;

sub filter_wrapup {
    my ($self, $ctx) = @_;
    my $signer = Mail::DKIM::Signer->new(
        Algorithm => 'rsa-sha256',
        Method    => 'relaxed/relaxed',
        Domain    => 'example.org',
        Selector  => 'my_selector',
        Key       => Mail::DKIM::PrivateKey->load(Data => get_my_key()));

    my $action = Mailmunge::Action::DKIMSigner->new($self);
    $action->add_dkim_signature($ctx, $signer);
}

METHODS

add_dkim_signature($ctx, $signer)

Given a Mail::DKIM::Signer instance (that the caller must create with appropriate settings), this method adds a DKIM-Signature: header to the current message. It should be called from filter_wrapup.

INBOUND vs OUTBOUND MAIL

Generally, we only want to sign outbound mail, so the question becomes: How do we distinguish "outbound" from "inbound" mail? There's no easy answer to this because it's really a policy decision. There are three types of email:

Inbound mail: Mail that originates from an external machine and is destined for either the local host or a downstream SMTP server that we control.
Outbound mail: Mail that originates from the local host or an internal machine that we control and is destined for an SMTP server that we do not control.
Local mail: Mail that both originates on and is destined for the localhost or a machine that we control.

One clear sign of outbound mail is mail sent from an authenticated session. You can detect this by looking at $ctx->mta_macro('auth_authen'); if this is defined and non-blank, then the SMTP session is authenticated.

Otherwise, you can obtain the connecting SMTP client address from $ctx->connecting_ip, and for each recipient, you can examine the destination mailer with $ctx->get_recipient_mailer($rcpt). These should give you enough information to determine if the originating machine and destination machine(s) are local or off-site.

WARNING

Mailmunge::Action::DKIMSigner can correctly sign a message that has not been modified, or whose message body has been replaced without altering the MIME type. However, if you have modified headers that are part of the DKIM signature, you must use the "relaxed" canonicalization for the header hash. This is because the (new) headers that are passed to the DKIM signer might be folded differently from the headers that actually go out on the wire.

Obviously, if you modify any headers after signing the message, you may well break the signature. So adding the DKIM signature should generally be the very last thing you do in filter_wrapup.