Configuring DKIM for qmail

This note concerns the DKIM patch embedded in my combined patch (more info here). This topic is advanced and you can skip it at the beginning.

Info: http://www.dkim.org/ - http://en.wikipedia.org/wiki/DomainKeys_Identified_Mail
Author: Manvendra Bhangui
Patch's version: 1.28
Download: from SourceForge - local copy

DKIM provides a method for validating a domain name identity that is associated with a message through cryptographic authentication. The validation technique is based on public-key cryptography: Responsibility is claimed by the signer by adding a domain name to the message and then also affixing a digital signature of it and the message. The value is placed in the DKIM-Signature: header field. The verifier recovers the signer's public key using the DNS, and then verifies the signature.

You are invited to take a look to the man pages starting from dkim(8) and spawn-filter(8).

Mirko Buffoni did a slight modification here which allows to sign messages sent by authenticated users, and to verify all non authenticated ones.

Changelog

2020.04.10
-DKIM patch updated to v. 1.28
- outgoing messages from null sender ("<>") will be signed as well with the domain in env variable DKIMDOMAIN
- declaring NODK env variable disables old domainkeys signature, while defining NODKIM disables DKIM.
2020.03.31
- added UNSIGNED_SUBJECT variable to the run file, which can be useful if one wants to allow messages without the sign of the subject
2019.12.08
- the domainkey script now can sign both 2048 and 1024 bit (thanks Tatsuya Yokota)
2019.06.19
- DKIM patch updated to v. 1.26
* BUG - honor body length tag in verification
2019.05.23
- SIGSEGV - when the txt data for domainkeys is very large exposed a bug in the way realloc() was used incorrectly.
- On 32 bit systems, variable defined as time_t overflows. Now qmail-dkim will skip expiry check in such conditions.
2019.04-27
- added a note concerning the signing with a 2048 long key here
2019.02.27
patch updated to v. 1.24
* bug fix: restored signaturedomains/nosignaturedomains functionalities.
2018.08.25
-patch updated to v. 1.23
* fixed a bug where including round brackets in the From: field ouside the double quotes (From: "Name Surname (My Company)" <name.surname@company.com>) results in a DKIMContext structure invalid error (tx Mirko Buffoni).
* qmail-dkim and dkim were issuing a failure for emails which had multiple signature with at least one good signature. Now qmail-dkim and dkim will issue a success if at least one good signature is found.
2018-04-03
-patch updated to v. 1.22
* openssl 1.1.0 port
* various improvements, bug fixes
2017-05-14
-patch updated to v. 1.20
It now manages long TXT records, avoiding the rejection of some hotmail.com messages.
2016-03-09
Upgraded to v. 1.19: verification will not fail when a dkim signature does not include the subject provided that the UNSIGNED_SUBJECT environment variable is declared. More info here

Acknowlegments

I would like to address a special thank to Manvendra Bhangui, the author of the DKIM patch, for kindly assisting me during all the configuration.

I will show how to configure qmail-remote to sign your outgoing messages and qmail-smtpd to verify your incoming messages. Eventually, as an alternative, you can decide to set qmail-smtpd to do both things; this configuration is presented towards the bottom of this page.

In any case you have to create the domainkey signature.

Creating the domainkey signature for your outgoing emails

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 may want to create key pairs for every domain you wish to sign, or use one single signature for all your hosted domains.

First of all download the script (thanks to Joerg Backschues and to Tatsuya Yokota for the 2048 bit key support) which we'll use to create the keys and print the DNS record.

cd /usr/local/bin
wget https://notes.sagredo.eu/files/qmail/domainkey
chmod +x domainkey

Now create the folder which will store all the domainkeys.

mkdir /usr/local/etc/domainkeys

Usage

Usage: /usr/local/bin/domainkey [-p] domain [selector]
       Create domainkey
       Print domainkey with -p

The script can create the key or print the existing key if used with the -p option.

When you create a key for a domain.net it will be stored in the /usr/local/etc/domainkeys/domain.net folder. The folder will be owned by qmailr (the user running qmail-remote) if you sign at qmail-remote level or vpopmail, which is the user who runs qmail-smtpd, if you decide to sign at qmail-smtpd level. My script changes the owner to qmailr by default

> domainkey domain.net

Generating RSA private key, 1024 bit long modulus
......................++++++
........++++++
e is 65537 (0x10001)
writing RSA key

TXT record for BIND:
default._domainkey.domain.net. IN TXT "v=DKIM1\; k=rsa\; t=y\; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCyzJujXz9EiMat2eDzzLjWuSJ6g4i20FXGluNOmruuCFnVJP1OxurKdt57JZm+6QP2h9IOP0owBMmecXI9qx3CkFrlGSMbJsOEGqXwiTSSttgGmSTPZeNAureyo79spwPc44Ol2ZK2U9gBoDpSQEQdLdtXUreRvs/HyTkzalue2wIDAQAB"

You have to create a TXT record like that in your DNS server. If your Name Server is not bind, google is your friend.

Configuring `qmail-remote` for signing and `qmail-smtpd` for verification

References:

man spawn-filter
man dk-filter
Writing filters (by Manvendra Bhangui)

`rc` script

First of all, let's save in the dkimdomain control file the domain to be used to sign the system messages belonging to the null sender ("<>"). These messages are bounces from our own MTA which have to be signed to avoid rejections because of a missing DKIM signature and/or a DMARC filter.

echo "yourdomain.tld" > /var/qmail/control/dkimdomain

Here is how to modify your /var/qmail/rc script so that qmail-remote will sign your outgoing messages:

#!/bin/sh

# Using stdout for logging
# Using control/defaultdelivery from qmail-local to deliver messages by default

# default domain for null ("<>") sender msg
DKIMDOMAIN=`cat /var/qmail/control/dkimdomain`

# declaring NODK disables domainkey
# declaring NODKIM disables DKIM

# DKIM 2048 key sign
exec env - PATH="/var/qmail/bin:$PATH" \
QMAILREMOTE=/var/qmail/bin/spawn-filter \
DKIMSIGNOPTIONS="-z 2" \
DKIMDOMAIN="$DKIMDOMAIN" \
NODK=1 \
FILTERARGS=/var/qmail/bin/dk-filter \
qmail-start "`cat /var/qmail/control/defaultdelivery`"

# DKIM 1024 key sign
#exec env - PATH="/var/qmail/bin:$PATH" \
#QMAILREMOTE=/var/qmail/bin/spawn-filter \
#DKIMDOMAIN="$DKIMDOMAIN" \
#NODK=1 \
#FILTERARGS=/var/qmail/bin/dk-filter \
#qmail-start "`cat /var/qmail/control/defaultdelivery`"

# Use this if you don't want to sign or you're signing at qmail-smtpd level
#exec env - PATH="/var/qmail/bin:$PATH" \
#qmail-start "`cat /var/qmail/control/defaultdelivery`"

The variable QMAILREMOTE makes qmail to call spawn-filter before the message gets queued, which in turn will execute a filter of your choice declared by FILTERARGS. For individual domain level control it is best using the control file filterargs (man spawn-filter). You can use QMAILLOCAL to sign local deliveries as well.

dk-filter uses /var/qmail/control/domainkeys/%/default as the location of the key. The '%' symbol is automatically replaced with the sender's domain. Of course you can decide to sign all your domains with one single signature located in /var/qmail/control/domainkeys/default.

If you need to store your domainkey elsewhere, define DKIMSIGN as follows (before the last qmail-start command):

DKIMSIGN=/usr/local/etc/domainkeys/example.net/your_keyname

`qmail-smtpd/run` script

Insert the two following environment variables in your /var/qmail/supervise/qmail-smtpd/run script:

export QMAILQUEUE=/var/qmail/bin/qmail-dkim
export DKIMVERIFY="FGHKLMNOQRTVWp"
# This is to allow msg without "subject" in the h= list
# export UNSIGNED_SUBJECT=1
# This is to avoid verification of outgoing messages
export RELAYCLIENT_NODKIMVERIFY=1

Declaring UNSIGNED_SUBJECT solve rare cases of email from providers which doesn't sign the subject (more info here). This would allow spammers to modify the subject without affecting the DKIM signature, so use at your own risk (I have it enabled since libero.it, a big provider here in Italy, would be blocked otherwise).

Declaring RELAYCLIENT_NODKIMVERIFY avoids that qmail-dkim will verify outgoing messages.

You are invited to read the qmail-dkim man page in order to choose the best configuration for you.

Testing

Create a test message to be used in the tests below (it's important to exit with ctrl+d and that the first line is not empty):

# cat > /tmp/testmail.txt
To: someone@somewhere.xy
From: postmaster@yourdomain.xy
Subject: DKIM Test Message

Test message FOLLOWING A BLANK LINE

cntrl-D

Signing test

We'll do the test as qmailr, the user who runs qmail-remote and which owns the domainkey.

# su qmailr                                         
# declare -x QMAILREMOTE=/var/qmail/bin/spawn-filter
# declare -x DKIMSIGNOPTIONS="-z 2" # only if 2048 key sign
# declare -x _SENDER=postmaster@yourdomain.xy
# /var/qmail/bin/dk-filter < /tmp/testmail.txt
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d=yourdomain.xy;
        s=default; h=To:From:Subject; bh=lrIChgTwMnmPKfGEgElIyJgL9jk=;
        b=LQPayl6VbbITdGjVC6vx2+bYF27jAjAkR6qm967GMd1L+0hb7szwP9cDfvy738
        Y05llEnOqMrc1QbGGE9uLxqGQrkOAPhl0q+Hxt8yQz1B4BsVk8vED812K/178pIe
        f+4oGrnodNCCJwg97TLXJmVdecGbrmOVPiBfm51kl4nSI=
To: someone@somewhere.xy
From: postmaster@yourdomain.xy
Subject: DKIM Test Tessage

Test message FOLLOWING A BLANK LINE

Send to yourself a message and look for the DKIM signature in the header:

DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed;
    d=yourdomain.xy; s=private; x=1298156019; h=to:from:subject;
    bh=tVrwKZaEzYO4qmI9mPfR04ZvZik=; b=r2VH/6rQdY6xcPjyg55ULnf7U+DEs
    +apecicwvygIZVvQwxU4NqiqAQGTF3Qkft2eBDu42TBzX4nV7FTs8wzn40iGkfhB
    mMZhQdcyOseg7DyOFKUK5D8Ji3ueF/xgYFUnffrxPdZUMpGN9+dA9fY0wkonp5ML
    dDSaNje9mmd34I=

Verification test

I assume that vpopmail is the user who runs qmail-smtpd.

# su vpopmail
# declare -x DKIMQUEUE=/bin/cat
# unset RELAYCLIENT
# /var/qmail/bin/qmail-dkim < /tmp/testmail.txt
DKIM-Status: no signatures
To: someone@somewhere.net
From: postmaster@yourdomain.xy
Subject: DKIM Test Message

Test message FOLLOWING A BLANK LINE

Send a message to yourself from a gmail.com account (which is DKIM signed) and check the header. The message has been verified if you get a header like this:

DKIM-Status: good

This is how to test the signature of a mail that was prevently saved to disk as email.txt (do not cut&paste to avoid to alter the body with white spaces, just save it to disk):

> /var/qmail/bin/dkim -vS < /path/to/email.txt
DKIM-Status: good

Testing the DNS record

Finally, send an email to check-auth@verifier.port25.com with "test" as subject. They will send you back a reply with the test results and you will know if your DNS configuration is ok.

You can also check the validation of your dns record (not the signature verification) here https://mxtoolbox.com/dkim.aspx.

Making qmail-dkim and simscan live together in peace

[If you didn't install simscan yet skip this and come here later. qmail won't work with this directive without simscan installed.]

As you probably know, also simscan needs to call qmail-queue and must be included in the QMAILQUEUE environment variable, just as qmail-dkim. The same should happen with other qmail scanners.

The work around is to assign qmail-dkim to QMAILQUEUE and assing simscan to the DKIMQUEUE variable. In this case qmail-dkim will call simscan when it has finished its work.

You have to modify like this your /var/qmail/supervise/qmail-smtpd/run script (and /var/qmail/supervise/qmail-submission/run as well)

export QMAILQUEUE=/var/qmail/bin/qmail-dkim
export DKIMQUEUE=/var/qmail/bin/simscan

Configuring `qmail-smtpd` for signing outgoing messages

You can skip this paragraph if you have already decided to sign at qmail-remote level.

`qmail-smtpd` run script

echo "yourdomain.tld" > /var/qmail/control/dkimdomain

Insert the following environment variables in your /var/qmail/supervise/qmail-smtpd/run script:

DKIMDOMAIN=`cat /var/qmail/control/dkimdomain`

export QMAILQUEUE=/var/qmail/bin/qmail-dkim
export DKIMKEY=/usr/local/etc/domainkeys/%/default
export DKIMDOMAIN="$DKIMDOMAIN"

# declaring NODK disables domainkey
# declaring NODKIM disables DKIM
export NODK=1

qmail-dkim will sign your messages if the variable RELAYCLIENT is set (take a look at your tcp.smtp) and will verify all messages from IPs where RELAYCLIENT is not set.

DKIMKEY is the location of the key. The '%' symbol is automatically replaced with the sender's domain. Of course you can decide to sign all your domains with one single signature located in /usr/local/etc/domainkeys/default

Testing

# cat > /tmp/testmail.txt
To: someone@somewhere.xyz
From: postmaster@yourdomain.xyz
Subject: Test Message

Test message FOLLOWING A BLANK LINE THAT YOU DON'T HAVE TO FORGET

cntrl-D

In this test qmail-dkim assumes that the domainkey is stored in the /var/qmail/control/domainkeys folder, so if your domainkeys are stored elsewhere create a symbolic link.

# su vpopmail
# declare -x DKIMQUEUE=/bin/cat
# declare -x DKIMKEY=/var/qmail/control/domainkeys/%/default
# declare -x RELAYCLIENT=""
# /var/qmail/bin/qmail-dkim < /tmp/testmail.txt
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed;
        d=yourdomain.xyz; s=default; x=1298483339; h=To:From:Subject;
        bh=6rJdFs2WVS8T72i61KhaAvC6O6s=; b=ffnXBB98Gg6iZFEIL6alk8c5davso
        ozyrunXM3C8qaejIrJOwYhnlWQwSdrV599WErmJcDYyMjFjVgLzRQ9OTeYHjEnHT
        X/aiIkvjcxRuOaTK7PcwrcJGdtF0c6LWoK9RgiPctCw7DMcHGmUcSyXWc6ayzHgX
        A7nopQYuHzTuIU=
To: someone@somewhere.xyz
From: postmaster@yourdomain.xyz
Subject: Test Message

Test message FOLLOWING A BLANK LINE THAT YOU DON'T HAVE TO FORGET

Choosing between `DKIMSIGN` and `DKIMKEY`

man qmail-dkim(8) for more info

Here is the logic behind as explained to me by the author of the patch himself:

If RELAYCLIENT is defined and both DKIMSIGN and DKIMVERIFY are not defined then qmail-dkim looks for DKIMKEY for the private key to sign. If DKIMKEY is not defined, then control/domainkeys/%/default is used
If RELAYCLIENT is not defined, then qmail-dkim uses DKIMSIGN for the key
If RELAYCLIENT is not defined and both DKIMSIGN and DKIMVERIFY is defined, then qmail-dkim ignores DKIMVERIFY
If the key has % in the filename, then it is replaced with the domain name from the From/Sender header. After substituting %, if the private key is not found, the qmail-dkim removes the % and again checks for the key. e.g. strace shows this
```
access("control/domainkeys/mydomain.org/default", F_OK) = -1 ENOENT (No such file or directory)
open("control/domainkeys/default", O_RDONLY|O_NONBLOCK) = 5
```
If the key has % in the filename and the private key does not exists, then qmail-dkim exits without signing and without any failure. Hence messages will pass through. The reason for this behaviour is i have many clients who run multiple domains on a server and they need DKIM only for few domains.
If the key does not have % sign and the private key does not exist, then qmail-dkim exits with 32 resulting in permanent failure
```
"Private key file does not exist (#5.3.5)"
```
If none of the variables RELAYCLIENT, DKIMSIGN, DKIMVERIFY are defined, qmail-dkim does verification

SPF

SURBL

add a comment

Comments

DKIMVERIFY documentation

Gabriel Torres June 6, 2020 01:22

The letters present in the DKIMVERIFY variable indicate which tests must be considered to reject an email, as follows:

A - DKIM_SUCCESS - Function executed successfully
B - DKIM_FINISHED_BODY - process result: no more message body is needed
C - DKIM_PARTIAL_SUCCESS - verify result: at least one but not all signatures verified
D - DKIM_NEUTRAL - verify result: no signatures verified but message is not suspicious
E - DKIM_SUCCESS_BUT_EXTRA - signature result: signature verified but it did not include all of the body
F - DKIM_3PS_SIGNATURE - 3rd-party signature
G - DKIM_FAIL - Function failed to execute
H - DKIM_BAD_SYNTAX - signature error: DKIM-Signature could not parse or has bad tags/values
I - DKIM_SIGNATURE_BAD - signature error: RSA verify failed
J - DKIM_SIGNATURE_BAD_BUT_TESTING - signature error: RSA verify failed but testing
K - DKIM_SIGNATURE_EXPIRED - signature error: x= is old
L - DKIM_SELECTOR_INVALID - signature error: selector doesn't parse or contains invalid values
M - DKIM_SELECTOR_GRANULARITY_MISMATCH - signature error: selector g= doesn't match i=
N - DKIM_SELECTOR_KEY_REVOKED - signature error: selector p= empty
O - DKIM_SELECTOR_DOMAIN_NAME_TOO_LONG - signature error: selector domain name too long to request
P - DKIM_SELECTOR_DNS_TEMP_FAILURE - signature error: temporary dns failure requesting selector
Q - DKIM_SELECTOR_DNS_PERM_FAILURE - signature error: permanent dns failure requesting selector
R - DKIM_SELECTOR_PUBLIC_KEY_INVALID - signature error: selector p= value invalid or wrong format
S - DKIM_NO_SIGNATURES - no signatures
T - DKIM_NO_VALID_SIGNATURES - no valid signatures
U - DKIM_BODY_HASH_MISMATCH - sigature verify error: message body does not hash to bh value
V - DKIM_SELECTOR_ALGORITHM_MISMATCH - signature error: selector h= doesn't match signature a=
W - DKIM_STAT_INCOMPAT - signature error: incompatible v=
X - DKIM_UNSIGNED_FROM - signature error: not all message's From headers in signature

For example, if you want to permanently reject messages that have a signature that is expired, include the letter 'K' in the DKIMVERIFY environment variable.

A conservative set of letters is FGHIKLMNOQRTUVWjp. Reject permanently 3PS, FAILURE, SYNTAX, SIGNATURE_BAD, SIGNATURE_EXPIRED, SELECTOR_INVALID, GRANULARITY_MISMATCH, SELECTOR_KEY_REVOKED, DOMAIN_NAME_TOO_LONG, SELECTOR_PUBLIC_KEY_INVALID, NO_VALID_SIGNATURES and BODY_HASH_MISMATCH errors, and temporarily SIGNATURE_BAD_BUT_TESTING and DNS_TEMP_FAILURE.

Add in S if you want to reject messages that do not have a DKIM signature. You can use the control files signaturedomains and nosignature domains (See Below) to further fine tune the action to be taken when a mail arrives with no DKIM signature. Note that qmail-dkim always inserts the DKIM-Status header, so that messages can be rejected later at delivery time, or in the mail reader. In that case you may set DKIMVERIFY to an empty string. If you want to check all message's From header in signature set the UNSIGNED_FROM environment variable to an empty string. If you want to check messages without signed subject header, set UNSIGNED_SUBJECT environment variable. If you want to honor body lengh tag (l=), set HONOR_BODYLENGTHTAG environment variable.

Configuring DKIM for qmail

Changelog

Acknowlegments

Creating the domainkey signature for your outgoing emails

Usage

Configuring qmail-remote for signing and qmail-smtpd for verification

rc script

qmail-smtpd/run script

Testing

Signing test

Verification test

Testing the DNS record

Making qmail-dkim and simscan live together in peace

Configuring qmail-smtpd for signing outgoing messages

qmail-smtpd run script

Testing

Choosing between DKIMSIGN and DKIMKEY

Comments

Configuring `qmail-remote` for signing and `qmail-smtpd` for verification

`rc` script

`qmail-smtpd/run` script

Configuring `qmail-smtpd` for signing outgoing messages

`qmail-smtpd` run script

Choosing between `DKIMSIGN` and `DKIMKEY`