After install, navigate to the courier/filters directory
where your zdkimfilter.conf has been installed. Edit it.
Options are documented in there.
Before install, the configuration file is in etc/zdkimfilter.conf.dist,
in the untarred directory.
You may also read the latest svn source of that file.
On upgrading, the existing configuration file, if any, is left intact, and a dist copy
is installed besides it. Compare the files to check for new parameters. You can also display the
values parsed from either configuration file as described below.
After modifying the configuration file, you need
to restart zdkimfilter for changes to take effect.
Use either
courierfilter
or filterctl for that.
Keys
You may want to change the domain_keys directory, otherwise create a keys subdirectory in the directory you just navigated to, and adjust its ownership and permissions.
Every now and then, you may want to change the selector used for signing.
| cd courier/filters/keys |
| opendkim-genkey -s march -t -d example.com |
| edit march.txt |
| rm march.txt |
| ln -s -n march.private example.com |
A chown command is implied for each file creation above, unless you are logged in as the mail user.
opendkim-genkey is smart enough to set proper permissions.
Courier settings
Courier may rewrite a mail file upon receiving it, before running global filters.
DKIM signatures are likely to break in such case.
If you have other global filters that may break DKIM signatures, you should probably run two dkimfilters, one for verification and one for signing. Please discuss this on
courier-users list.
To avoid rewritings by Courier, edit esmtpd in Courier's sysconfig directory.
Add
You may still want to allow some rewriting for outgoing messages.
It can be done for users submitting to port 587 by editing esmtpd-msa and override the value of MIME
NOTE: the MIME environment variable is documented in
submit(8), but does not have a prepared stanza in esmtpd or esmtpd-msa. Those files are sourced, thus one might as well write unexport MIME to reset it in esmtpd-msa; setting it to some, or other unrecognized value, has the same effect. Courier needs to be restarted for those settings to take effect.
ADSP
Since version 0.4, the default installed conf file disables ADSP behavior. This is ruled by the parameter no_author_domain. When upgrading from an earlier version, consider setting that variable to true so as to avoid possible message loss.
Signing
Once installed, zdkimfilter checks whether the message has been accepted with RELAYCLIENT permission. If so, and there is an authenticated user, a domain for signing is searched in the user's id. If not found there, the configured default_domain is used. If a private key can be found in the domain_keys directory, the filter will sign with it. The selector is found either reading the symbolic link or using defaults.
Verifying
If the message had no RELAYCLIENT setting, the filter will verify and write an Authentication-Results (A-R) field on top of the header. If the first Received-SPF fields found in the message have a "pass", that info will also be repeated in A-R. Only one DKIM signature is reported in A-R. In presence of multiple valid signatures, the filter chooses it in this order:
- Author's domain signature (after the From header field.)
- Sender's domain signature (after Received-SPF for
MAILFROM.)
- Other (possibly helo-related).
If the author's domain is invalid, or if its policy mandates a specific behavior for messages without a valid author's domain signature and none is found in the message, the filter honors that policy. This would be a relief for phishing, if ADSP worked: Phishing with bait service@paypal.com can be blocked this way, and it is reliable since PayPal reserved that domain for transactional mail. For other cases, senders can be whitelisted. Alternatively, the filter can be configured to never honor ADSP, but add a line for the dkim-adsp method in its A-R field inside the message. The latter alternative is recommended, and is the configuration distributed by default since version 0.4. In addition, the filter may add A-R methods x-dwl after looking up the signer in Spamhaus, and x-dkim-rep according to the configured dkim-reputation thresholds. Authentication-Results should be checked by mail clients, enabled as specified by RFC 5451.
Use in scripting
Command line usage has been conceived for debugging and testing, so it is not very user-friendly.
The directory it gets installed to is usually not in PATH.
However, using zdkimfilter, it is possible to prepare scripts that
sign and/or verify a mail file offline.
The final order of header fields will differ, according to the sequence of events.
zdkimfilter command line args:
-f config-filename override the default zdkimfilter.conf
--help print this stuff and exit
--version print version string and exit
-tN file... scan rest of args as N ctl and mail file(s)
--batch-test enter batch test mode
Basically, you need to create a dummy ctlfile and an input file containing four lines:
- the name of a mail file, header and body,
- the name of the ctlfile,
- an empty line, and
- the keyword exit.
Control File Format is documented in the relevant section of Courier
Mail Queue.
We only need three record types:
- u (msgsource),
- if this is not
authsmtp then the message is verified, rather than signed;
- i (authname),
- needed for signing, the signing domain is either after the '@' in this address or in the
conf file;
- M (msgid),
- this is only used for logging (to
stderr).
Recall that the record identifier is case sensitive, and don't name ctl and mail files like
test*, sig*, sleep, and exit*, as that may conflict with batch mode keywords. Given a mail.eml file and a key.private, you can filter mail before sending like so:
#! /bin/sh
# link domain to selector, if needed
ln -n -s key.private example.com
# custom conf file, if needed
printf 'domain_keys = .\n' > conf
# sign mail.eml using postmaster@example.com as the login id
printf 'uauthsmtp\nipostmaster@example.com\nMtestsigning\n' > ctlfile
printf 'mail.eml\nctlfile\n\nexit' | /your/path/to/zdkimfilter -f conf --batch-test > /dev/null 2>log
# verify signature, if needed
# Received field is needed: its "by localhost with" provides the authserv-id
printf 'Received: from localhost by localhost with local\n' > mail2.eml
cat mail.eml >> mail2.eml
printf 'usmtp\nMtestverifying\n' > ctlfile
printf 'mail2.eml\nctlfile\n\nexit' | /your/path/to/zdkimfilter -f conf --batch-test > /dev/null 2>>log
# send it
cat mail2.eml | sendmail
A parsed printout of a conf file can be obtained like so:
$ echo test1 | /your/path/to/zdkimfilter -f conf --batch-test
The remaining batch mode keywords are only useful for testing and are not documented; their usage can be deduced from the testsuite, if needed. Likewise, I don't document the similar option -tN file..., which is only useful for attaching the gdb debugger to the forked working copy of the filter.
Statistics (since OpenDKIM v2.2.0 and zdkimfilter v0.5)
OpenDKIM.org keeps data about DKIM verifications. You may contribute to that data by submitting statistics files generated by zdkimfilter. You may feed your data to your own database, reusing their schema, if you have OpenDBX. You may extract daily statistics from those plain text stats files, e.g. to learn whether it's safe to enable ADSP.
To enable writing the stats file, set the stats_file parameter. The filter will write a tab-separated line for each verified message, except in a few cases, e.g. when the message's From is invalid; and one line for each DKIM signature. The format of the file is compatible with that used by opendkim-stats, so you can use that command for a human-readable version of its content.
Two utilities come with zdkimfilter for managing that file.
zdkimstats-wait signals (USR1) zdkimfilter to reopen stats
files and then waits until it can acquire a write lock on
the renamed file; for use in postrotate clauses.
Command line args:
[-f] filename renamed file to wait for
-t seconds timeout (default: wait forever)
--help print this stuff and exit
--version print version string and exit
zdkimstats-anon reads stdin assuming that it is in the
OpenDKIM stats format, checks it, optionally appends counts
and/or ADSP failures to the respective files, and rewrites
data to stdout, possibly anonymized; for use before mailing
data to OpenDKIM (see http://www.opendkim.org/.)
Command line args:
[-p] prefix secret string for MD5 digests
-x domain ... don't anonymize data about messages
signed by these domains
-a adsp-track append a line for each adsp domain
-c count-file append there one line with totals
--help print this stuff and exit
--version print version string and exit
At the time, etc/logrotate.example showed their usage. zdkimstats-anon may provide additional daily statistics, but its main role it to massage the stat file in order to get rid of minor format differences that may exist, anonymizing as needed.
The format of the stats file and the schema are described in the stats directory of the OpenDKIM distribution. The one-time setup required is as follows:
MySQL:
--as root user, create database and user
CREATE DATABASE opendkim;
CREATE USER 'opendkim'@'localhost' IDENTIFIED BY 'password';
GRANT ALL ON opendkim.* TO 'opendkim'@'localhost';
--as opendkim user,
mysql -u opendkim -ppassword opendkim < mkdb.mysql
The database can then be populated from rotated stats files like so:
zdkimstats-anon < /var/log/zdkimstats/stats.0 | opendkim-importstats -ppassword
