538 lines
17 KiB
Perl
538 lines
17 KiB
Perl
#!perl -w
|
|
|
|
=head1 NAME
|
|
|
|
dkim: validate DomainKeys and (DKIM) Domain Keys Indentified Messages
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
Validate the DKIM and Domainkeys signatures of a message, enforce DKIM
|
|
sending policies, and DKIM sign outgoing messages.
|
|
|
|
=head1 CONFIGURATION
|
|
|
|
=head2 reject [ 0 | 1 | naughty ]
|
|
|
|
dkim [ reject 0 ]
|
|
|
|
0 - do not reject
|
|
1 - reject messages that fail DKIM policy
|
|
naughty - defer rejection to the B<naughty> plugin
|
|
|
|
Default: 1
|
|
|
|
=head2 reject_type
|
|
|
|
dkim reject_type [ temp | perm ]
|
|
|
|
Default: perm
|
|
|
|
=head1 HOW TO SIGN
|
|
|
|
=head2 generate DKIM keys
|
|
|
|
=head3 the easy way
|
|
|
|
cd ~smtpd/config/dkim; ./dkim_key_gen.sh example.org
|
|
|
|
=head3 the manual way
|
|
|
|
mkdir -p ~smtpd/config/dkim/example.org
|
|
cd ~smtpd/config/dkim/example.org
|
|
echo 'may2013' > selector
|
|
openssl genrsa -out private 2048
|
|
chmod 400 private
|
|
openssl rsa -in private -out public -pubout
|
|
chown -R smtpd:smtpd ../example.org
|
|
|
|
After generating the keys, there will be three files in the example.org directory: selector, private, and public.
|
|
|
|
=head3 selector
|
|
|
|
The selector can be any value that is a valid DNS label.
|
|
|
|
=head3 key length
|
|
|
|
The minimum recommended key length for short duration keys (ones that will be replaced within a few months) is 1024. If you are unlikely to rotate your keys frequently, choose 2048, at the expense of a bit more CPU.
|
|
|
|
=head2 publish public key in DNS
|
|
|
|
If the DKIM keys were generated the easy way, there will be a fourth file named I<dns>. The contents contain the DNS formatted record of the public key, as well as suggestions for DKIM, SPF, and DMARC policy records. The records are ready to be copy/pasted into a BIND zone file, or better yet, NicTool. If you created your keys manually, look in the dkim_key_gen.sh script to see the commands used to format the DKIM public key.
|
|
|
|
The combination of the three example DKIM, SPF, and DMARC policy records in the I<dns> file tell other mail servers that if a sender claims to be from example.org, but the message is not DKIM nor SPF aligned, then the message should be rejected. Many email servers, including the largest email providers (Gmail, Yahoo, Outlook/Live/Hotmail) will refuse to accept such messages, greatly reducing the harm caused by miscreants who forge your domain(s) in the From header of their spam.
|
|
|
|
The DKIM record will look like this:
|
|
|
|
may2013._domainkey TXT "v=DKIM1;p=[public key stripped of whitespace];"
|
|
|
|
And the values in the address have the following meaning:
|
|
|
|
hash: h=[ sha1 | sha256 ]
|
|
test; t=[ s | s:y ]
|
|
granularity: g=[ ]
|
|
notes: n=[ ]
|
|
services: s=[email]
|
|
keytypes: [ rsa ]
|
|
|
|
=head2 testing
|
|
|
|
After confirming that the DKIM public key can be fetched with DNS (dig TXT may2013._domainkey.example.org. @ns1.example.org.), send test messages. You can testing DKIM by sending an email to:
|
|
|
|
* a Gmail address and inspect the Authentication-Results header.
|
|
* check-auth@verifier.port25.com
|
|
* checkmyauth@auth.returnpath.net
|
|
|
|
The two DKIM relays provide a nice email report with additional debugging information.
|
|
|
|
=head2 publish DKIM policy in DNS
|
|
|
|
_domainkey TXT "o=~; t=y; r=postmaster@example.org"
|
|
|
|
o=- - all are signed
|
|
o=~ - some are signed
|
|
t=y - test mode
|
|
r=[email] - responsible email address
|
|
n=[notes]
|
|
|
|
After DKIM and SPF are tested and working, update the policy, changing o=~ to o=-, so that other mail servers reject unsigned messages claiming to be from your domain.
|
|
|
|
As of this writing, most mail servers do not reject messages that fail DKIM policy, unless they also fail SPF, and no DMARC policy is published. The same holds true for SPF. There are technical reasons for this. See DMARC for more information, how you can control change that behavior, as well as receiving feedback from remote servers about messages they have accepted and rejected from senders claiming the identity of your domain(s).
|
|
|
|
=head2 Sign for others
|
|
|
|
Following the directions above will configure QP to DKIM sign messages from authenticated senders of example.org. Suppose you host client.com and would like to DKIM sign their messages too? Do that as follows:
|
|
|
|
cd ~smtpd/config/dkim
|
|
ln -s example.org client.com
|
|
|
|
QP will follow the symlink target and sign client.com emails with the example.org DKIM key.
|
|
|
|
This is B<not> necessary for hosts or subdomains. If the DKIM key for host.example.com does not exist, and a key for example.com does exist, the parent DKIM key will be used to sign the message. So long as your DKIM and DMARC policies are set to relaxed alignment, these signed messages for subdomains will pass.
|
|
|
|
CAUTION: just because you can sign for other domains, doesn't mean you should. Even with a relaxed DKIM policy, if the other domain doesn't have a suitable DMARC record for client.com, they may encounter deliverability problems. It is better to have keys generated and published for each domain.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
http://www.dkim.org/
|
|
|
|
http://tools.ietf.org/html/rfc6376 - DKIM Signatures
|
|
|
|
http://tools.ietf.org/html/rfc5863 - DKIM Development, Deployment, & Operations
|
|
|
|
http://tools.ietf.org/html/rfc5617 - DKIM ADSP (Author Domain Signing Practices)
|
|
|
|
http://tools.ietf.org/html/rfc5585 - DKIM Service Overview
|
|
|
|
http://tools.ietf.org/html/rfc5016 - DKIM Signing Practices Protocol
|
|
|
|
http://tools.ietf.org/html/rfc4871 - DKIM Signatures
|
|
|
|
http://tools.ietf.org/html/rfc4870 - DomainKeys
|
|
|
|
http://dkimcore.org/tools/
|
|
|
|
http://www.protodave.com/tools/dkim-key-checker/
|
|
|
|
=head1 AUTHORS
|
|
|
|
2013 - Matt Simerson - added DKIM signing and key creation script
|
|
|
|
2012 - Matt Simerson - initial plugin
|
|
|
|
=head1 ACKNOWLEDGEMENTS
|
|
|
|
David Summers - http://www.nntp.perl.org/group/perl.qpsmtpd/2010/08/msg9417.html
|
|
|
|
Matthew Harrell - http://alecto.bittwiddlers.com/files/qpsmtpd/dkimcheck
|
|
|
|
I first attempted to fix the dkimcheck plugin, but soon scrapped that effort and wrote this one. Why?
|
|
|
|
=over 4
|
|
|
|
The use of $dkim->fetch_author_policy, which is deprecated by Mail::DKIM.
|
|
|
|
The paradim of a single policy, when DKIM supports 0 or many.
|
|
|
|
The OBF programming style, which is nigh impossible to test.
|
|
|
|
The nine 'if' brackets with 19 conditionals, and my inability to easily determine which of the 15 possible permutations (5 signature validation results x 3 possible policy results) were covered.
|
|
|
|
=back
|
|
|
|
=cut
|
|
|
|
use strict;
|
|
use warnings;
|
|
|
|
use Qpsmtpd::Constants;
|
|
|
|
# use Mail::DKIM::Verifier; # eval'ed in register()
|
|
# use Mail::DKIM::Signer;
|
|
use Socket qw(:DEFAULT :crlf);
|
|
|
|
sub init {
|
|
my ($self, $qp) = (shift, shift);
|
|
$self->{_args} = {@_};
|
|
$self->{_args}{reject} = 1 if !defined $self->{_args}{reject};
|
|
$self->{_args}{reject_type} ||= 'perm';
|
|
}
|
|
|
|
sub register {
|
|
my $self = shift;
|
|
|
|
# Mail::DKIM::TextWrap - nice idea, clients get mangled headers though
|
|
foreach my $mod (qw/ Mail::DKIM::Verifier Mail::DKIM::Signer /) {
|
|
eval "use $mod";
|
|
if ($@) {
|
|
warn "error, plugin disabled, could not load $mod\n";
|
|
$self->log(LOGERROR,
|
|
"skip, plugin disabled, is Mail::DKIM installed?");
|
|
return;
|
|
}
|
|
}
|
|
|
|
$self->register_hook('data_post_headers', 'data_post_handler');
|
|
}
|
|
|
|
sub data_post_handler {
|
|
my ($self, $transaction) = @_;
|
|
|
|
if ($self->qp->connection->relay_client()) {
|
|
|
|
# this is an authenticated user sending a message.
|
|
return $self->sign_it($transaction);
|
|
}
|
|
|
|
return DECLINED if $self->is_immune();
|
|
|
|
return $self->validate_it($transaction);
|
|
}
|
|
|
|
sub validate_it {
|
|
my ($self, $transaction) = @_;
|
|
|
|
# Incoming message, perform DKIM validation
|
|
my $dkim = Mail::DKIM::Verifier->new() or do {
|
|
$self->log(LOGERROR,
|
|
"error, could not instantiate a new Mail::DKIM::Verifier");
|
|
return DECLINED;
|
|
};
|
|
|
|
$self->send_message_to_dkim($dkim, $transaction);
|
|
my $result = $dkim->result;
|
|
my $mess = $self->get_details($dkim);
|
|
$self->connection->notes('dkim_result', $result);
|
|
$self->connection->notes('dkim_verifier', $dkim);
|
|
|
|
my $auth_str = "dkim=" .$dkim->result_detail;
|
|
if ( $dkim->signature && $dkim->signature->domain ) {
|
|
$auth_str .= " header.i=@" . $dkim->signature->domain;
|
|
};
|
|
$self->store_auth_results( $auth_str );
|
|
|
|
foreach my $t (qw/ pass fail invalid temperror none /) {
|
|
next if $t ne $result;
|
|
my $handler = 'handle_sig_' . $t;
|
|
$self->log(LOGDEBUG, "dispatching $result to $handler");
|
|
return $self->$handler($dkim, $mess);
|
|
}
|
|
|
|
$self->log(LOGERROR, "error, unknown result: $result, $mess");
|
|
return DECLINED;
|
|
}
|
|
|
|
sub sign_it {
|
|
my ($self, $transaction) = @_;
|
|
|
|
my ($domain, $keydir) = $self->get_keydir($transaction) or return DECLINED;
|
|
my $selector = $self->get_selector($keydir);
|
|
|
|
my $dkim = Mail::DKIM::Signer->new(
|
|
Algorithm => "rsa-sha256",
|
|
Method => "relaxed",
|
|
Domain => $domain,
|
|
Selector => $selector,
|
|
KeyFile => "$keydir/private",
|
|
);
|
|
|
|
$self->send_message_to_dkim($dkim, $transaction);
|
|
|
|
my $signature = $dkim->signature; # what is the signature result?
|
|
$self->qp->transaction->header->add('DKIM-Signature',
|
|
$signature->as_string, 0);
|
|
|
|
$self->log(LOGINFO, "pass, we signed the message");
|
|
return DECLINED;
|
|
}
|
|
|
|
sub get_details {
|
|
my ($self, $dkim) = @_;
|
|
|
|
my @data;
|
|
my $string;
|
|
push @data, "domain: " . $dkim->signature->domain if $dkim->signature;
|
|
push @data, "selector: " . $dkim->signature->selector if $dkim->signature;
|
|
push @data, "result: " . $dkim->result_detail if $dkim->result_detail;
|
|
|
|
foreach my $policy ($dkim->policies) {
|
|
next if !$policy;
|
|
push @data, "policy: " . $policy->as_string;
|
|
push @data, "name: " . $policy->name;
|
|
push @data, "policy_location: " . $policy->location
|
|
if $policy->location;
|
|
|
|
my $policy_result;
|
|
$policy_result = $policy->apply($dkim);
|
|
$policy_result or next;
|
|
push @data, "policy_result: " . $policy_result if $policy_result;
|
|
}
|
|
|
|
return join(', ', @data);
|
|
}
|
|
|
|
sub handle_sig_fail {
|
|
my ($self, $dkim, $mess) = @_;
|
|
|
|
$self->adjust_karma(-1);
|
|
return $self->get_reject("signature invalid: " . $dkim->result_detail,
|
|
$mess);
|
|
}
|
|
|
|
sub handle_sig_temperror {
|
|
my ($self, $dkim, $mess) = @_;
|
|
|
|
$self->log(LOGINFO, "error, $mess");
|
|
return DENYSOFT, "Please try again later - $dkim->result_detail";
|
|
}
|
|
|
|
sub handle_sig_invalid {
|
|
my ($self, $dkim, $mess) = @_;
|
|
|
|
my ($prs, $policies) = $self->get_policy_results($dkim);
|
|
|
|
foreach my $policy (@$policies) {
|
|
if ($policy->signall && !$policy->is_implied_default_policy) {
|
|
$self->log(LOGINFO, $mess);
|
|
return
|
|
$self->get_reject("invalid DKIM signature with sign-all policy",
|
|
"invalid signature, sign-all policy");
|
|
}
|
|
}
|
|
|
|
$self->adjust_karma(-1);
|
|
$self->log(LOGINFO, $mess);
|
|
|
|
if ($prs->{accept}) {
|
|
$self->log(LOGERROR, "error, invalid signature but accept policy!?");
|
|
return DECLINED;
|
|
}
|
|
elsif ($prs->{neutral}) {
|
|
$self->log(LOGERROR, "error, invalid signature but neutral policy?!");
|
|
return DECLINED;
|
|
}
|
|
elsif ($prs->{reject}) {
|
|
return
|
|
$self->get_reject("invalid DKIM signature: " . $dkim->result_detail,
|
|
"fail, invalid signature, reject policy");
|
|
}
|
|
|
|
# this should never happen
|
|
$self->log(LOGINFO, "error, invalid signature, unhandled");
|
|
return DECLINED;
|
|
}
|
|
|
|
sub handle_sig_pass {
|
|
my ($self, $dkim, $mess) = @_;
|
|
|
|
$self->save_signatures_to_note($dkim);
|
|
|
|
my ($prs) = $self->get_policy_results($dkim);
|
|
|
|
if ($prs->{accept}) {
|
|
$self->add_header($mess);
|
|
$self->log(LOGINFO, "pass, valid signature, accept policy");
|
|
$self->adjust_karma(1);
|
|
return DECLINED;
|
|
}
|
|
elsif ($prs->{neutral}) {
|
|
$self->add_header($mess);
|
|
$self->log(LOGINFO, "pass, valid signature, neutral policy");
|
|
$self->log(LOGDEBUG, $mess);
|
|
return DECLINED;
|
|
}
|
|
elsif ($prs->{reject}) {
|
|
$self->log(LOGINFO, $mess);
|
|
$self->adjust_karma(-1);
|
|
return
|
|
$self->get_reject("DKIM signature valid but fails policy, $mess",
|
|
"fail, valid sig, reject policy");
|
|
}
|
|
|
|
# this should never happen,
|
|
$self->add_header($mess);
|
|
$self->log(LOGERROR, "pass, valid sig, no policy results");
|
|
$self->log(LOGINFO, $mess);
|
|
return DECLINED;
|
|
}
|
|
|
|
sub handle_sig_none {
|
|
my ($self, $dkim, $mess) = @_;
|
|
|
|
my ($prs, $policies) = $self->get_policy_results($dkim);
|
|
|
|
foreach my $policy (@$policies) {
|
|
if ($policy->signall && !$policy->is_implied_default_policy) {
|
|
$self->log(LOGINFO, $mess);
|
|
return
|
|
$self->get_reject("no DKIM signature with sign-all policy",
|
|
"no signature, sign-all policy");
|
|
}
|
|
}
|
|
|
|
if ($prs->{accept}) {
|
|
$self->log(LOGINFO, "pass, no signature, accept policy");
|
|
return DECLINED;
|
|
}
|
|
elsif ($prs->{neutral}) {
|
|
$self->log(LOGINFO, "pass, no signature, neutral policy");
|
|
return DECLINED;
|
|
}
|
|
elsif ($prs->{reject}) {
|
|
$self->log(LOGINFO, $mess);
|
|
$self->get_reject(
|
|
"no DKIM signature, policy says reject: " . $dkim->result_detail,
|
|
"no signature, reject policy");
|
|
}
|
|
|
|
# should never happen
|
|
$self->log(LOGINFO, "error, no signature, no policy");
|
|
$self->log(LOGINFO, $mess);
|
|
return DECLINED;
|
|
}
|
|
|
|
sub get_keydir {
|
|
my ($self, $transaction) = @_;
|
|
|
|
my $domain = $transaction->sender->host;
|
|
my $dir = "config/dkim/$domain";
|
|
|
|
if (!-e $dir) { # the dkim key dir doesn't exist
|
|
my @labels = split /\./, $domain; # split the domain into labels
|
|
while (@labels > 1) {
|
|
shift @labels; # remove the first label (ie: www)
|
|
my $zone = join '.', @labels; # reassemble the labels
|
|
if (-e "config/dkim/$zone") { # if the directory exists
|
|
$domain = $zone; # the DKIM signing domain
|
|
$dir = "config/dkim/$zone"; # use the parent domain's key
|
|
$self->log(LOGINFO, "info, using $zone key for $domain");
|
|
}
|
|
}
|
|
}
|
|
|
|
if (-l $dir) {
|
|
$dir = readlink($dir);
|
|
$dir = "config/dkim/$dir" if $dir !~ /\//; # no /, relative path
|
|
($domain) = (split /\//, $dir)[-1];
|
|
}
|
|
|
|
if (!-d $dir) {
|
|
$self->log(LOGINFO, "skip, DKIM not configured for $domain");
|
|
return;
|
|
}
|
|
if (!-r $dir) {
|
|
$self->log(LOGINFO, "error, unable to read key from $dir");
|
|
return;
|
|
}
|
|
if (!-r "$dir/private") {
|
|
$self->log(LOGINFO, "error, unable to read dkim key from $dir/private");
|
|
return;
|
|
}
|
|
return $domain, $dir;
|
|
}
|
|
|
|
sub save_signatures_to_note {
|
|
my ($self, $dkim) = @_;
|
|
|
|
my %domains;
|
|
foreach my $sig ($dkim->signatures) {
|
|
next if $sig->result ne 'pass';
|
|
$domains{$sig->domain} = 1;
|
|
}
|
|
return if 0 == scalar keys %domains;
|
|
|
|
my $doms = $self->connection->notes('dkim_pass_domains') || [];
|
|
push @$doms, keys %domains;
|
|
$self->log(LOGDEBUG, "info, signed by: ". join(',', keys %domains) );
|
|
$self->connection->notes('dkim_pass_domains', $doms);
|
|
}
|
|
|
|
sub send_message_to_dkim {
|
|
my ($self, $dkim, $transaction) = @_;
|
|
|
|
foreach (split(/\n/s, $transaction->header->as_string)) {
|
|
$_ =~ s/\r?$//s;
|
|
eval { $dkim->PRINT($_ . CRLF); };
|
|
$self->log(LOGERROR, $@) if $@;
|
|
}
|
|
|
|
$transaction->body_resetpos;
|
|
while (my $line = $transaction->body_getline) {
|
|
chomp $line;
|
|
$line =~ s/\015$//;
|
|
eval { $dkim->PRINT($line . CRLF); };
|
|
$self->log(LOGERROR, $@) if $@;
|
|
}
|
|
|
|
eval { $dkim->CLOSE; };
|
|
$self->log(LOGERROR, $@) if $@;
|
|
}
|
|
|
|
sub get_policies {
|
|
my ($self, $dkim) = @_;
|
|
|
|
my @policies;
|
|
eval { @policies = $dkim->policies };
|
|
$self->log(LOGERROR, $@) if $@;
|
|
return @policies;
|
|
}
|
|
|
|
sub get_policy_results {
|
|
my ($self, $dkim) = @_;
|
|
|
|
my %prs;
|
|
my @policies = $self->get_policies($dkim);
|
|
|
|
foreach my $policy (@policies) {
|
|
my $policy_result;
|
|
eval { $policy_result = $policy->apply($dkim); }; # accept, reject, neutral
|
|
if ($@) {
|
|
$self->log(LOGERROR, $@);
|
|
}
|
|
$prs{$policy_result}++ if $policy_result;
|
|
}
|
|
|
|
return \%prs, \@policies;
|
|
}
|
|
|
|
sub get_selector {
|
|
my ($self, $keydir) = @_;
|
|
|
|
open my $SFH, '<', "$keydir/selector" or do {
|
|
$self->log(LOGINFO,
|
|
"error, unable to read selector from $keydir/selector");
|
|
return DECLINED;
|
|
};
|
|
my $selector = <$SFH>;
|
|
chomp $selector;
|
|
close $SFH;
|
|
$self->log(LOGDEBUG, "info, selector: $selector");
|
|
return $selector;
|
|
}
|
|
|
|
sub add_header {
|
|
my $self = shift;
|
|
my $header = shift or return;
|
|
$self->qp->transaction->header->add('X-DKIM-Authentication', $header, 0);
|
|
}
|
|
|