Mail::Send::DKIM
Name
Mail::Send::DKIM - sign a message with DKIM and hand it to sendmail
Version
0.001.0
Synopsis
use Mail::Send::DKIM;
my $dkim = Mail::Send::DKIM->new(
domains => ['example.org'],
keydir => "$ENV{HOME}/dkim",
);
my $signed = $dkim->sign($message);
$message = $signed if(defined($signed));
exit($dkim->send($message, '-t', '-f', 'alerts@example.org'));
Description
Signs a message with DKIM when its From: domain is one this host signs for,
and hands it to sendmail with whatever arguments sendmail should have. The
signed form is rsa-sha256 with relaxed canonicalization, which is the
shape receiving sites expect.
The signature covers the message in the form DKIM defines, where every line ends CRLF. What is handed to sendmail is the local form instead: LF line endings, and no carriage return anywhere, whatever arrived. A CR would be data to the MTA that keeps the message - Postfix and Exim both write the CRLF of SMTP themselves - so a message that had travelled with CRLF in it would reach the receiver with the CRs doubled and fail the signature it had just been given.
Nothing here dies because a key is missing: signing either produces a signed message or produces nothing and says why on standard error, so a caller can always fall back to sending the message as it is.
Platforms
Windows is not supported. Mail::DKIM needs Crypt::OpenSSL::RSA, and that
module and its prerequisites, Crypt::OpenSSL::Random and
Crypt::OpenSSL::Bignum, do not link on Windows: Strawberry Perl's static
OpenSSL needs the crypt32 library, which their Makefile.PL files do not
ask for. Makefile.PL stops with OS unsupported there, rather than failing
part-way through the install.
Environment
DKIM_DOMAINS, DKIM_KEYDIR, DKIM_SELECTOR, DKIM_KEYFILE and SENDMAIL are read by new when the corresponding option is not given, so the command line programs needs no configuration of its own.
Programs
The distribution is named after this module and installs four programs with
it, each with a page of its own: perldoc bin/mail-dkim,
perldoc bin/dmarc-report.pl, perldoc bin/dmarc-check-mail.pl and
perldoc bin/dmarc-weekly.sh in a checkout, and the same pages as manual
pages once installed.
-
The front end to this module: a message on standard input is signed when its
From:domain is one named inDKIM_DOMAINS, and handed to sendmail(1) with the arguments it was given. Put it where a script or a crontab calls sendmail and the mail is signed without the script being changed. Its page has the environment variables, the key layout and the exit status. -
Reads a directory of DMARC aggregate reports and says who sent mail for each domain, marking every source that is not an expected one (
DMARC_EXPECTED), every expected one whose mail did not authenticate, and every message that was quarantined or rejected by policy despite passing. The exit status is non-zero when anything needs looking at. Its page has the options. -
The cron wrapper around it: silent when the week is clean, a mail with the full output when it is not, and the reports moved aside to an archive afterwards.
DRY_RUN=1rehearses a run and--crontabprints the line to paste into a crontab; see "A CRONTAB ENTRY" below. -
Sends one message, signed with this module, to a mailbox that can be read, so that the
Authentication-Resultsheader at the far end shows what receivers make of this host's mail before the DMARC policy is tightened.--plainsends the same message unsigned, which is what a cron job without the module looks like.
The three DMARC programs are the reason the module exists: they report on the mail it signs, and the weekly one sends its own report through it.
Methods
New %Options
-
domainsThe domains to sign for, either an array reference or a string of them separated by commas or spaces. Defaults to
$ENV{DKIM_DOMAINS}. A message from any other domain is left alone. -
keydirWhere the private keys are. Defaults to
$ENV{DKIM_KEYDIR}, or~/dkim. -
selectorThe selector the key is published under, which names the key file
<keydir>/<selector>.private. Defaults to$ENV{DKIM_SELECTOR}; with neither set, the key file's own name is the selector when keyfile is given, and otherwise the only*.privatefile in keydir is used and its name is the selector. -
keyfileThe private key to sign with, when it does not live at
<keydir>/<selector>.private- a tester given one key to try, for instance. Defaults to$ENV{DKIM_KEYFILE}. It is used as it stands, and the selector comes from its name unless one is given. -
sendmailThe program send hands the message to. Defaults to
$ENV{SENDMAIL}, or/usr/sbin/sendmail.
Sign $Message
Returns the message with a DKIM-Signature header added, or undef when
there is nothing to do or nothing that can be done: the domain is not one of
domains, there is no From: header, no key can be found or read, or the
signer failed. The reasons are warnings on standard error; the message itself
is never altered in the undef case, so the caller sends it unchanged.
Carriage returns are folded to LF on the way, so what comes back is in the
local form.
Send $Message, @Arguments
Pipes the message to sendmail with the arguments given - -t, -f and
the rest are sendmail's own - and returns 0 when sendmail accepted the
message, sendmail's exit status when it did not, and 1 when sendmail cannot
be run at all. The message is normalised to LF first, so nothing that arrived
with CRLF - signed or passed through unsigned - carries a carriage return to
the MTA.
From_Domain $Message
The domain of the address in the first From: header, in lower case, or
undef when there is no such header. Folded headers and display names are
understood.
Selector
The selector the message will be signed under: the one given to new or read
from DKIM_SELECTOR, otherwise the name of the keyfile when one is given,
otherwise the name of the only *.private file in keydir. undef when it
cannot be decided - no key, or several keys and no name - and the reason is a
warning on standard error. sign asks this before doing anything else.
A Crontab Entry
A job that sends mail from cron is where an unsigned message is least likely to
be noticed, so that is usually where this module earns its keep: the program
that ships with it, mail-dkim, is put where the job would have called
sendmail(1), and the job itself is not changed.
The weekly summary in this distribution is such a job, and its mail goes out
through mail-dkim. A crontab line for it looks like this, with the values of
the machine it runs on:
0 6 * * 1 DMARC_EXPECTED=192.0.2.10 MAIL_TO=alerts@example.org \
PERL=/usr/bin/perl /usr/local/bin/dmarc-weekly.sh
The three settings are not optional, because cron starts a job with almost no
environment. DMARC_EXPECTED is what makes a sender nobody expected a
finding, and the run stops with a usage error without it, since guessing would
excuse every sender. MAIL_TO is where a week that needs looking at is
mailed, and is also the address the alert is sent as unless MAIL_FROM says
otherwise. PERL has to be an absolute path to a perl that has
XML::PP, as cron's PATH usually holds only the system one; --crontab
fills it in with the first perl on the machine that can load the module.
DMARC_DIR and DMARC_ARCHIVE_DIR are left out of the line because they
default to ~/Downloads and ~/dmarc-archive.
dmarc-weekly.sh --crontab prints that line with the path and the perl filled
in for the machine it runs on, which is more use than an example carrying
somebody else's values; for that reason no example crontab file is shipped or
installed. A job of your own takes the same shape with mail-dkim in place of
the wrapper: DKIM_DOMAINS and DKIM_KEYDIR say what to sign for, and the
arguments given to it are passed to sendmail(1) as they are.
See Also
Mail::DKIM::Signer, which does the signing underneath, and "PROGRAMS" above for the programs this distribution installs beside the module.
Author
Nigel Horne, <njh at nigelhorne.com>
Licence and Copyright
Copyright 2026 Nigel Horne.
Usage is subject to the GPL2 licence terms. If you use it, please let me know.