NAME

mail-dkim - sign a message on stdin with DKIM, then send it with sendmail

SYNOPSIS

mail-dkim [-t] [-f address] [sendmail options...] < message

# the way a CGI script or a crontab calls it
DKIM_DOMAINS=example.org DKIM_KEYDIR=~/dkim \
	/usr/local/bin/mail-dkim -t -f webmaster@example.org

DESCRIPTION

Reads a complete message, headers and body, from standard input. If the domain in its From: header is one of the domains this host signs for, a DKIM-Signature header is added and the signed message is written to sendmail. Otherwise the message is written to sendmail unsigned. Either way it is written in the local form, with LF line endings and no carriage returns, so an MTA that writes the CRLF of SMTP itself cannot double them.

It is meant to be put in place of a direct call to sendmail(1), so that mail sent by a script or a cron job is signed without the script being changed: a copy forwarded by a mailing list or a colleague otherwise arrives with no signature at all, which is indistinguishable from a forgery, and that is what makes a DMARC policy at p=quarantine or p=reject expensive.

Every argument is passed to sendmail as it was given, so -t, -f and -odq keep working, and the exit status is sendmail's own.

The signing itself - which domains, which key, the canonicalization, and the line endings handed to sendmail - is Mail::Send::DKIM, which can be used directly and is tested without running this programme.

ENVIRONMENT

DKIM_DOMAINS

A comma or space separated list of the domains to sign for, for example example.org,example.net. A message whose From: domain is not in the list is passed through unsigned. When this is empty or unset nothing is signed, which is the safe state before the keys are in place.

The comparison is case insensitive, and the domain comes from the address, not from a display name: From: "Nigel" <alerts@example.org> is example.org.

DKIM_KEYDIR

The directory holding the private keys. Defaults to ~/dkim.

DKIM_SELECTOR

The selector the key is published under, which names the key file: $DKIM_KEYDIR/$DKIM_SELECTOR.private. When it is unset the only *.private file in DKIM_KEYDIR is used and its name is the selector, so a host with one key needs no configuration beyond DKIM_DOMAINS.

DKIM_KEYFILE

The key file itself, used as it stands, for a key that is not kept under DKIM_KEYDIR in the naming convention above - a host given one key to try, for instance. When DKIM_SELECTOR is not set the selector is the name of this file, without the .private, so setting this is an alternative to setting both of those rather than a third thing to set with them.

SENDMAIL

The program to hand the message to. Defaults to /usr/sbin/sendmail.

HOME

The home directory the default DKIM_KEYDIR of ~/dkim is taken from. When it is unset the home directory in the password file entry is used instead.

BEHAVIOUR WHEN IT CANNOT SIGN

Signing never stands between a message and its recipient. A missing or unreadable key, several keys and no selector to choose between them, or a key that will not load each produce a warning on standard error and the message is delivered unsigned.

EXIT STATUS

The exit status of sendmail, so 0 when the message was accepted. 1 when sendmail cannot be run at all, and a warning on standard error. Signing problems do not change the exit status: the mail is still delivered.

SEE ALSO

Mail::Send::DKIM, which does the signing, and dmarc-report.pl, which is what makes the reports worth signing for.

LICENCE

GNU General Public License, version 2, as in the LICENSE file.