DKIM and DomainKeys for qmail
DomainKeys and its successor DomainKeys Identified Mail (DKIM) are technologies that allow organizations to take responsibility for a message. This is done by cryptographically signing an email as it leaves an organization in route to its destination. The signature can be verified using the DNS system to establish trust. In theory the technologies help cut down on spam by proving a message originated from the domain it says it does.
Support for DomainKeys in qmail has existed for a while thanks to a patch by Russel Nelson. Kyle Wheeler created a set of wrapper scripts that can be used to provide support for DKIM and DomainKeys. Mihai Secasiu has some wrapper scripts similar to Kyle’s that provide support for DKIM via the libdkim library instead of Perl’s Mail::DKIM module.
The current methods take different approaches to implement DKIM and DomainKeys. The DomainKeys patch creates a single program,
qmail-dk that is called before
qmail-queue. This program signs or verifies all incoming messages (that may later become outbound) based on the existence of the
DKVERIFY variables. The DKIM wrapper scripts wrap
qmail-remote to sign messages and wrap
qmail-dk) to verify incoming messages. This can be easier understood by looking at the qmail big picture.
I tend to agree with separate programs for signing outbound messages and verifying inbound messages as this allows signing all outbound messages, even those (such as NDRs) that never pass through
qmail-queue. I also prefer patching qmail as it tends to be a little easier and requires less configuration after qmail is installed.
In this post I will show you how to patch qmail to support DKIM as well as DomainKeys. My qmail DKIM/DomainKeys patch uses neither Russel Nelson’s DomainKeys patch nor Kyle Wheeler’s DKIM/DomainKey wrappers, but borrows ideas from both. My patch uses the libdomainkeys and libdkim libraries to do the actual signing and verifying. Rather than creating two new programs, I patch
qmail-smtpd (for verifying) and
qmail-remote (for signing) directly.
I’ll do my best to provide step by step instructions for patching and installing for you non-Gentoo users, but in my next post I’ll share my ebuild which does it all for you.
1. Install libdomainkeys
libdomainkeys library is used to sign and verify DomainKeys signatures.
$ tar -xzf libdomainkeys-0.69.tar.gz
$ cd libdomainkeys-0.69
(If you get errors during
make, edit the Makefile and add
-lresolvto the end of the
$ sudo install -m 644 libdomainkeys.a /usr/local/lib
$ sudo install -m 644 domainkeys.h dktrace.h /usr/local/include
$ sudo install -m 755 dknewkey /usr/local/bin
$ cd ..
2. Install libdkim
libdkim library is used to sign and verify DKIM signatures. You’ll need g++ to compile this on your system. The library claims to be portable, but I needed to patch it to get it to compile on my Gentoo box. I’ve also included a (slightly modified) patch from Mihai Secasiu that makes working with libdkimtest much easier.
$ wget http://www.bltweb.net/qmail/libdkim-1.0.19-linux.patch
$ wget http://www.bltweb.net/qmail/libdkim-1.0.19-extra-options.patch
$ unzip libdkim-1.0.19.zip
$ cd libdkim/src
$ patch -p2 < ../../libdkim-1.0.19-linux.patch
$ patch -p2 < ../../libdkim-1.0.19-extra-options.patch
$ sudo make install
$ cd ../..
3. Patch and install qmail
I’m currently using John Simpson’s qmail Combined Patch Set for my qmail installation. The instructions below highlight how to apply my DKIM/DomainKeys patch on top of John’s combined patch. I’d highly recommend checking out John’s combined patch as it is about as close as you can get to an actively maintained qmail.
I’m not attempting to describe or document John’s patch in anyway in this post, as John runs an excellent site about qmail (qmail.jms1.net) that contains far more information than is contained here. Do not attempt to proceed without reading through John’s documentation as well as the rest of this post.
$ wget http://qmail.jms1.net/patches/qmail-1.03-jms1.7.08.patch
$ wget http://www.bltweb.net/qmail/qmail-1.03-jms1.7.08-dkim-r1.patch
$ tar -xzf qmail-1.03.tar.gz
$ mv qmail-1.03 qmail-1.03-jms1.7.08
$ cd qmail-1.03-jms1.7.08
$ patch < ../qmail-1.03-jms1.7.08.patch
$ patch -p1 < ../qmail-1.03-jms1.7.08-dkim-r1.patch
$ sed -ie '1s/$/ -DDKIM/' conf-cc
$ make man
$ sudo make setup check
$ cd ..
4. Configure DKIM/DomainKeys signing
Signing is done by
qmail-remote and is controlled by the
dksign control file. Signatures are created using a private key on your system, and verified by a public key stored in the DNS for the email domain.
Before you can sign an email, you must create at least one public/private key pair. You should create key pairs for every domain you wish to sign. To create keys for
# cd /etc/domainkeys/example.com
# dknewkey default 1024 > default.pub
# chown -R root:root /etc/domainkeys
# chmod 640 /etc/domainkeys/example.com/default
# chown root:qmail /etc/domainkeys/example.com/default
It is very important that the default file be readable only by
root and the group which
qmail-remote user) belongs to. This is the private key used for signing messages and, if compromised, would allow others to sign messages as your domain.
Now add a
TXT entry to the DNS for
default._domainkey.example.com containing the quoted part in the
/etc/domainkeys/example.com/default.pub. NOTE: You normally want to include the quotes!
Configure control files
Create a file
/var/qmail/control/dksign containing one line:
% will be replaced with the domain name in the
From: header (or the
Sender: header if it exists). If no file exists for the given domain, parent domains will be tried. For example if the message is from
/etc/domainkeys/bar.example.com/default will be tested first. If the file does not exist,
/etc/domainkeys/example.com/default will be tested. If no key can be found, the message will not be signed. If a key exists, but cannot be read or contains invalid data, the message will not be sent and will remain in the queue until the problem is fixed.
If you do not create the
/var/qmail/control/dksign file, no messages will be signed.
Test outbound signing
Now that DKIM/DomainKeys signing is configured, you can test it by sending an email to
sa-test (at) sendmail dot net. This reflector will reply (within seconds) to the envelope sender with a status of the DomainKeys and DKIM signatures.
If you experience problems, consult the
qmail-remote man page or post a comment below and I’ll try to help.
5. Configure DKIM/DomainKeys verification
Verification is performed by
qmail-smtpd and is controlled by the
DKVERIFY environment variable. Messages are only verified if
DKVERIFY is set and RELAYCLIENT is not set. You may control which IP addresses are verified using the tcpserver access file (sometimes stored in
When verifying a message, the contents of
DKVERIFY are checked against the status of the DomainKeys and DKIM results. Each test result is represented by a letter.
DKVERIFY should contain a series of letters for DomainKeys results, a comma, and then a series of letters for the DKIM results. If the letter is uppercase, the message will be rejected (hard error). If the letter is lowercase, the message will be deferred (soft error). The
DKVERIFY variable can be set but empty, in which case messages will be verified and an
Authentication-Results: header will be added but all messages will be accepted regardless of status.
The letters for DomainKeys results are:
|A||OK||The message contained a signature which correctly matched the contents of the message.|
|B||BADSIG||The message contained a signature which DID NOT correctly match the contents of the message. The signature may be forged, or the content may have been changed after the original server applied the signature.|
|C||NOSIG||The message did not contain a
|D||NOKEY||The public key needed to verify the signature does not exist (i.e. the authoritative DNS server for the domain says that the TXT record which should contain the key does not exist.)|
|E||BADKEY||The public key which was found in DNS is not usable.|
|F||CANTVRFY||The public key needed to verify the signature cannot be found, because the DNS server which should have the key is not responding, or returned a temporary error condition. The domainkeys specification says that the server SHOULD treat this as a soft error, telling the client to try their delivery again at some point in the future.|
|G||SYNTAX||The message is not in the proper format. This could be an improperly formatted email address, a duplicate “From:” header in the message, or any number of things which “confuse” the program.|
|H||NORESOURCE||Out of memory. The domainkeys specification says that the server SHOULD treat this as a soft error, telling the client to try their delivery again at some point in the future.|
|I||ARGS||Arguments are not usable|
|J||REVOKED||The key which was used to generate the signature has been revoked.|
|K||INTERNAL||There was an internal error in the libdomainkeys library|
The letters for the DKIM results are:
|A||OK||The message contained a signature which correctly matched the contents of the message.|
|B||FAIL||The message failed verification|
|D||SIG BAD||RSA verify failed|
|E||SIG BAD (testing)||RSA verify failed but testing|
|F||SIG EXPIRED||Signature is expired (x= is old)|
|G||SELECTOR INVALID||Selector doesn’t parse or contains invalid values|
|H||SELECTOR MISMATCH||Selector granularity doesn’t match|
|I||SELECTOR REVOKED||The selector was revoked (p= is empty)|
|J||DOMAIN TOO LONG||The domain name is too long to request|
|K||DNS TEMP FAIL||Temporary DNS error requesting public key|
|L||DNS PERM FAIL||Permanent DNS error requestion public key|
|M||PUBLIC KEY INVALID||Public key isn’t valid or can’t be parsed|
|N||NO SIG||The message contains no DKIM signatures|
|O||NO VALID SIG||The message contains no valid signatures|
|P||BAD BODY HASH||The message body doesn’t verify|
|Q||ALGORITHM MISMATCH||The selector (h=) doesn’t match signature (a=)|
|R||STAT INCOMPAT||Incompatible v=|
I recommend a
DKVERIFY value of
DEGIJKfh,CGHIJMQRkl. This will only reject improperly formatted messages. Messages that don’t verify will still be allowed. I would advise against rejecting messages that don’t verify as there are still some problems with DomainKeys and DKIM (such as mailing lists). Rather than rejecting bad signatures, incorporate the
Authentication-Results header into your broader spam prevention strategy.
All messages received by
DKVERIFY is set will add an
Authentication-Results header to the incoming message. This header conforms to the IETF internet draft. Here’s an example from one of my emails:
Authentication-Results: bltweb.net; domainkeys=pass (ok); dkim=pass (ok)
Here are some examples to help you configure your box. Anything that normally should be private is made up.
For my bltweb.net domain name, here’s what my keys look like (these are not the actual keys installed on my system, those are private):
-rw-r----- 1 root qmail 887 Mar 4 18:49 default
-rw-r--r-- 1 root root 254 Mar 4 18:49 default.pub
$ cat /etc/domainkeys/bltweb.net/default.pub
default._domainkey IN TXT “k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDbFnVeFZdlud6/xvLoMt2/g9qrQzZjg6mopp4IYgPwNxRfQTsvYJo4dxP/aIt5UcL1YWtEnOm6/VL+wzj33WvVGL8GWdJDcUWGpCOysWuKasH/sXCaxoZSFMNM02K5pOgzaIVinWZNLIv+yaDSnBC3zb35HoQOnU4KLySECWPRuQIDAQAB”
$ sudo cat /etc/domainkeys/bltweb.net/default
—–BEGIN RSA PRIVATE KEY—–
—–END RSA PRIVATE KEY—–
To sign emails for all domains for which I have a key in
/etc/domainkeys, I set the
control/dksign configuration file:
-rw-r--r-- 1 root root 31 Mar 17 14:02 /var/qmail/control/dksign
$ cat /var/qmail/control/dksign
Here’s an example of my
/etc/tcprules.d/tcp.qmail-smtp file. Make sure you regenerate the cdb file after editing your
# Everyone else can’t relay unless they auth
# All signed mail is allowed, even if it’s bad, but still prepend the
# Authentication-Results header
# Or if I want to use the recommend DKIM settings, comment out the line
# above and use
That’s it. You should now have a qmail installation capable of signing and verifying messages. More information is contained in the
qmail-remote man pages.
If you have any comments or find any bugs, please feel free to post a comment below.