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.20
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).

Changelog

2017-05-14
-DKIM 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) which we'll use to create the keys and print the DNS record.

cd /usr/local/bin
wget http://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

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

exec env - PATH="/var/qmail/bin:$PATH" \
QMAILREMOTE=/var/qmail/bin/spawn-filter  \
FILTERARGS=/var/qmail/bin/dk-filter \
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/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="FGHKLMNOQRTVWjpu"
# This is to avoid verification of outgoing messages
export RELAYCLIENT_NODKIMVERIFY=1

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 _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=domain.net; 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

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.

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

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

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

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=/usr/local/etc/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

tcprules

SURBL

add a comment

Comments

mails do not have a signature via php

Chava2b September 20, 2017 18:00

Hi,

I have in the file /var/qmail/supervise/qmail-smtpd/run

export QMAILQUEUE=/var/qmail/bin/qmail-dkim
export DKIMKEY=/etc/domainkeys/my_domain/default

The dkim signature is present if I use outlook for example (relay) but is not present if I send a mail by a php script from the mail server.

Have I forgotten anything? Thank you for your help

regards

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

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

qmail notes

Other contents

Recent comments

Recent posts

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