# Mail::Send::DKIM

## Name

Mail::Send::DKIM - sign a message with DKIM and hand it to sendmail

## Version

0.001.0

## Synopsis

```perl
    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](https://metacpan.org/pod/Mail%3A%3ADKIM) needs [Crypt::OpenSSL::RSA](https://metacpan.org/pod/Crypt%3A%3AOpenSSL%3A%3ARSA), and that
module and its prerequisites, [Crypt::OpenSSL::Random](https://metacpan.org/pod/Crypt%3A%3AOpenSSL%3A%3ARandom) and
[Crypt::OpenSSL::Bignum](https://metacpan.org/pod/Crypt%3A%3AOpenSSL%3A%3ABignum), 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.

- [mail-dkim](https://github.com/nigelhorne/Mail-Send-DKIM/blob/master/bin/mail-dkim)

    The front end to this module: a message on standard input is signed when its
    `From:` domain is one named in `DKIM_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.

- [dmarc-report](https://github.com/nigelhorne/Mail-Send-DKIM/blob/master/bin/dmarc-report.pl)

    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.

- [dmarc-weekly.sh](https://github.com/nigelhorne/Mail-Send-DKIM/blob/master/bin/dmarc-weekly.sh)

    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=1` rehearses a run and `--crontab` prints the line to paste into a
    crontab; see ["A CRONTAB ENTRY"](#a-crontab-entry) below.

- [dmarc-check-mail.pl](https://github.com/nigelhorne/Mail-Send-DKIM/blob/master/bin/dmarc-check-mail.pl)

    Sends one message, signed with this module, to a mailbox that can be read, so
    that the `Authentication-Results` header at the far end shows what receivers
    make of this host's mail before the DMARC policy is tightened.  `--plain`
    sends 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

- `domains`

    The 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.

- `keydir`

    Where the private keys are.  Defaults to `$ENV{DKIM_KEYDIR}`, or `~/dkim`.

- `selector`

    The 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 `*.private` file in **keydir** is used and its name is
    the selector.

- `keyfile`

    The 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.

- `sendmail`

    The 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

- [Configure an Object at Runtime](https://metacpan.org/pod/Object%3A%3AConfigure)
- [Test Dashboard](https://nigelhorne.github.io/Mail-Send-DKIM/coverage/)

[Mail::DKIM::Signer](https://metacpan.org/pod/Mail%3A%3ADKIM%3A%3ASigner), which does the signing underneath, and ["PROGRAMS"](#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.
