← Documentation Index

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',
            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 certain headers such as Content-Type, Subject or From are altered, the signature will be incorrect. The reason is that header changes are made only once the Perl code has finished running and the C milter library functions are invoked; as such, the DKIM-signing code will not see the modified headers. If you are going to sign an outbound message, you should not make any changes to headers that might cause the signature to fail. Adding X-* headers is OK since these are not part of the DKIM signature.

Copyright © 2022 Skoll Software Consulting