Configuring DKIM for qmail

February 6, 2024 by Roberto Puzzanghera 293 comments

Index

Changelog
Acknowlegments
Creating the domainkey signature for your outgoing emails
Configuring qmail-remote for signing and qmail-smtpd for verification
Configuring qmail-smtpd for signing outgoing messages
Signing with multiple keys. Customizing the selector
- Testing

This note concerns the DKIM patch embedded in my combo (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.48
Download: from SourceForge - local copy
Changelog
Mirko Buffoni did a slight modification here to allow to sign messages sent by authenticated users, and to verify all non authenticated ones.

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

Feb 12, 2024
- v. 1.48: fixed minor bug using filterargs for local deliveries (commit)
Feb 6, 2024
-DKIM patch upgraded to v. 1.47
* fixed a bug which was preventing filterargs' wildcards to work properly on sender domain
Jan 22, 2024
- the documentation of the section Signing with multiple keys. Customizing the selector has been corrected to be relevant to the latest patch version. Configuration is now based on filterargs instead of dkimkeys. If you prefer to stick with dkimkeys you are invited to have a look at the man pages.
Jan 11, 2024
- version 1.46. If signing at qmail-remote level, before upgrading, you have to review the configuration as explained below.
* dk-filter.sh has been dropped
* The variables USE_FROM, USE_SENDER and DKIMDOMAIN have been dropped
* when signing at qmail-remote level qmail-dkim now has to be called directly by spawn-filter in the rc file. man spawn-filter for more info
* In case of bounces the signature will be automatically based on the from: field. This will solve issues of DMARC reject by google in case of sieve/vacation bounces.
* In case of ordinary bounces (mailbox not found, for instance) the bounce domain will be taken from control/bouncehost or, if doesn't exist, from control/me
Nov 20, 2023
-patch upgraded to v. 1.43
* The patch now by default excludes X-Arc-Authentication-Results
* dkim can additionally use the environment variable EXCLUDE_DKIMSIGN to include colon separated list of headers to be excluded from signing (just like qmail-dkim). If -X option is used with dk-filter, it overrides the value of EXCLUDE_DKIMSIGN.
Feb 19, 2023 (v. 1.37 upgrade)
- ed25519 support (RFC 8463)
- multiple signatures/selectors via the enhanced control/dkimkeys or DKIMSIGN / DKIMSIGNEXTRA / DKIMSIGNOPTIONS DKIMSIGNOPTIONSEXTRA variables
- domainkey script replaced by dknewkey in order to create ed25519 keys and rsa keys with 1024/2048/4096 bit
- dropped yahoo's domainkeys support (no longer need the libdomainkeys.a library)
- man pages revised and enhanced
- domainkeys directory moved to /var/qmail/control/domainkeys
- the documentation in this page has been revised. You can find how to sign with the rsa key together with the ed25519 key below.

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 the outgoing messages and qmail-smtpd to verify the 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.

Starting from version 1.37 we'll no longer use the domainkey script to create the domainkey. The dknewkey shipped by the dkim patch itself will be used instead, as it can manage both rsa and ed25519 keys.

Create the folder which will store all the domainkeys and assign write priviledges to qmailr:qmail if you are going to sign at qmail-remote level as suggested here, vpopmail:vchkpw if you are going to sign at qmail-smtpd level. In the latter case you have to adjust the priviledges of the keys files modifing the /var/qmail/bin/dknewkey script.

mkdir /var/qmail/control/domainkeys
chown -R qmailr:qmail /var/qmail/control/domainkeys

`dknewkey` usage

Usage: dknewkey [options] keyfile 
options 
      [-p | --print]          : print DKIM public keys 
      [-r | --remove]         : remove DKIM keys 
      [-d | --domain domain]  : domain name 
      [-b | --bits   size]    : DKIM private key size 
      [-t | --type   type]    : Key type (RSA or ED25519) 
      [-e | --enforce]        : Key is not in testing 
      [-f]                    : force DKIM private key creation

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

keyfile is the name of the "descriptor", which binds the private/public key pair that we are going to generate; it is also the name of the file which holds the private key, while the public key will be saved to keyfile.pub. The TXT record in the DNS, which holds the public key, is also linked to the chosen descriptor; here is an example:

keyfile._domainkey.domain.tld. IN TXT ("v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArscx1X+i6VEViYZpf9C6Bnd6ME15AxQ5U1T3O7Ts1BS8Z3tZBdda68Lg+wlc5B+FQaozqeoiQsOWReyD8JDwZ5WTxom4/Ey1XJX7jADUZ0oad/F4a7OT96JaiCKAKX8otBXTwWdQZxk0J7lFxiBpZYA38YB+B3BYdig04MZiDvFe5lCeBpOHPCICZfjY")

If not sure about what to choose for the descriptor name, use default as in the example below. If you want to use a descriptor of your choice, or you want to sign with the new ed25519 signature, read below.

When you create a key for domain.tld it will be stored in the /var/qmail/control/domainkeys/domain.tld folder.

# dknewkey -d domain.tld -t rsa -b 2048 default 
Generating rsa DKIM private key keysize=2048, file /var/qmail/control/domainkeys/domain.tld/default 
Generating rsa DKIM public  key for default.domainkey.domain.tld, file /var/qmail/control/domainkeys/domain.tld/default.pub, keysize=2048 
DKIM Private key for domain.tld file /var/qmail/control/domainkeys/domain.tld/default 
-----BEGIN RSA PRIVATE KEY----- 
MIIEpAIBAAKCAQEArscx1X+i6VEViYZpf9C6Bnd6ME15AxQ5U1T3O7Ts1BS8Z3tZ 
Bdda68Lg+wlc5B+FQaozqeoiQsOWReyD8JDwZ5WTxom4/Ey1XJX7jADUZ0oad/F4 
xxxxxxxxxxx very long xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
14SQHokCgYAkIUAHxYjuRkvzatWdEhI1buuBDWl2ZwpHnQSWxUKqeQdwygGAS78s 
ZMbHhuoW2Xt/Jjbwx7t1faA0TsJkER+P0WP61AbwTKA32SVkhc9yhPizdN7WZDjW 
scC2+bToOgxQK/6+1sfHrqXSEPFscwx/dYTlHyUtbLaYnFMJfSw4Cg== 
-----END RSA PRIVATE KEY----- 
-rw-r----- 1 root qmail 1679 Feb 19 13:12 /var/qmail/control/domainkeys/domain.tld/default 
------------------------------------------------------ 
DKIM TXT record for domain.tld with selector=default file /var/qmail/control/domainkeys/domain.tld/default.pub 
default._domainkey.domain.tld. IN TXT ("v=DKIM1; k=rsa; t=y; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArscx1X+i6VEViYZpf9C6Bnd6ME15AxQ5U1T3O7Ts1BS8Z3tZBdda68Lg+wlc5B+FQaozqeoiQsOWReyD8JDwZ5WTxom4/Ey1XJX7jADUZ0oad/F4a7OT96JaiCKAKX8otBXTwWdQZxk0J7lFxiBpZYA38YB+B3BYdig04MZiDvFe5lCeBpOHPCICZfjY"
       "G/rO9K9LRoMwXG3Raz7lY2XLhhnHrNxjXjUKmvSXySeedkZl/TbJbjO4vQ8+bIrTjvReEF4YXBqAIWQ4XIFy04S1SdhOFIp1kIXR7x8kKpc1vrjUsMg6Pth76FttlLGk0J2g5UYXPxrGVP1YyRHTiNTYPQIDAQAB") 
-rw-r--r-- 1 root qmail 461 Feb 19 13:12 /var/qmail/control/domainkeys/domain.tld/default.pub 
------------------------------------------------------

Create a TXT record with the part in bold text above in your DNS server.

If you decide to use the same key for all your domains, you have to use dknewkey with no domain. The key will be saved to /var/qmail/control/domainkeys. The hostname of the server "domain.tld" will be used in the example and you have to replace it with the real domain.

# dknewkey -t rsa -b 1024 default
Generating rsa DKIM private key keysize=1024, file /var/qmail/control/domainkeys/default
Generating rsa DKIM public  key for default.domainkey.domain.tld, file /var/qmail/control/domainkeys/default.pub, keysize=1024
DKIM Private key for sagredo.eu file /var/qmail/control/domainkeys/default
-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDHZT/CSiZXwbPIzCmZOWrBV4PR4XV/lPOL3f1GJjRVH5NMZwrr
hTxZ3R6JJN91dIlRbcDGQyEdpQDzjHVZgWfm45fGcVTBpF2JcdCycIXtXxX5N3GM
IUgxtrOI8ZyceMvDnu+wpuI/qhQS/zHi90+Ueth9t7S1cL1QX6ESoNu2awIDAQAB
AoGANAqwDnSt9z+ePe1TeiNrQpUl2ZSfxzHIMxw4a6OzCviXyFwolHoM22OEAcV2
8T/+Sxt7MgP5U7RqQCbLxhWpWTrLvUcSQAy6DJbjLUaf0bdvpIGxa+q7zlB5PAzi
uUWGL9s6HFJzp65heNIoDRTBgmQE9l4nXd3ua1JLSUhMCGECQQDrIX0/xeX8Tuvf
m9BWe7JuYTZ0hmSfwjUoNI5AzbtGCsLNor+lqJ8Q6depseXLwHsrt37SGznd7wcx
eNBCjEYbAkEA2RfNUdUnQISmkR4WQzYIICTnnltVTP7atqSB0gHHKwJqYl7F7FFB
3E1Hr9LxrcmhVKVtbABr0wmIs7F2YgCV8QJBALKWeBwlAn61rt/i58WYJDlEKuks
XmcdSeSkrls4J4KWj8lCUM/RGCfvhLdGAGTWaHcW4wNQXI5di5gezAePpXsCQHG3
NxSre7EfCwUu5mh0cBMuYakgnHEFell7mIkB52sPC9zVWgWslrwoOunNrEzlNj3Z
nZSaL+DOuK2vwpwZRHECQQCtgpPrGGnzO6cAuZi5NmBemii4+RYkNTUaXX2DlSpu
JxPpOSA3nf6OsmMatGdT857I3PNzIq/l8P0vSk3lHWlK
-----END RSA PRIVATE KEY-----
-rw-r----- 1 root qmail 887 Mar  8 19:05 /var/qmail/control/domainkeys/default
------------------------------------------------------
DKIM TXT record for domain.tld with selector=default file /var/qmail/control/domainkeys/default.pub
default._domainkey.domain.tld. IN TXT ("v=DKIM1; k=rsa; t=y; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHZT/CSiZXwbPIzCmZOWrBV4PR4XV/lPOL3f1GJjRVH5NMZwrrhTxZ3R6JJN91dIlRbcDGQyEdpQDzjHVZgWfm45fGcVTBpF2JcdCycIXtXxX5N3GMIUgxtrOI8ZyceMvDnu+wpuI/qhQS/zHi90+Ueth9t7S1cL1QX6ESoNu2awIDAQAB")
-rw-r--r-- 1 root qmail 282 Mar  8 19:05 /var/qmail/control/domainkeys/default.pub
------------------------------------------------------

If you are having problems to add such a long key in your DNS, because you use a kind of control panel that doesn't manage two lines long keys, use a 1024 bit rsa key, which goes in one single line. Also you don't have to use the option DKIMSIGNOPTIONS="-z 2" in this case.

Remember to delete the testing tag (t=y) from the dns record once your tests are fine. dknewkey used in combination with the -e option will show the DNS record without the testing tag.

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

References:

man spawn-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 with RSA 2048 bit long:

#!/bin/sh 

QMAILDIR=/var/qmail 

# Comment out DKIM_ON=1 to disable dkim sign at qmail-remote level 
# You have to define your variables in control/filterargs (DKIM page for more info)
# echo "*:remote:/var/qmail/bin/qmail-dkim:DKIMQUEUE=/bin/cat,DKIMSIGN=/var/qmail/control/domainkeys/%/default,DKIMSIGNOPTIONS=-z 2" > /var/qmail/control/filterargs
DKIM_ON=1 

if [ -r $QMAILDIR/control/filterargs ] && [ -n "$DKIM_ON" ]; then 
  # DKIM sign at qmail-remote level
  exec env - PATH="$QMAILDIR/bin:$PATH" \
  QMAILREMOTE=$QMAILDIR/bin/spawn-filter \
  qmail-start "`cat $QMAILDIR/control/defaultdelivery`" 
else 
  # Use this if you are signing at qmail-smtpd level or you don't want to sign at all 
  exec env - PATH="$QMAILDIR/bin:$PATH" \
  qmail-start "`cat $QMAILDIR/control/defaultdelivery`" 
fi

Create the file control/filterargs, which serves to instruct spawn-filter on what program need to be launched and which parameters to use:

echo "*:remote:/var/qmail/bin/qmail-dkim:DKIMQUEUE=/bin/cat,DKIMSIGN=/var/qmail/control/domainkeys/%/default,DKIMSIGNOPTIONS=-z 2" > /var/qmail/control/filterargs

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 or by the control file filterargs (man spawn-filter) as in this case to improve individual domain level control. You can use QMAILLOCAL to sign local deliveries as well. The program that needs to be launced in filterargs is qmail-dkim.

qmail-dkim 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 customize the selector or the domainkey refer to man spawn-filter for an advanced use of control/filterargs or control/domainkeys.

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

Signing test

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

We have to set the env variable DKIMSIGN or DKIMKEY. Then set the env variable DKIMQUEUE=/bin/cat so that the result is displayed on screen.

DOMAIN=domain.tld 
RSA2048_SELECTOR=default
MSG=/tmp/mail.txt

( 
echo "From: postmaster@${DOMAIN}" 
echo "To: postmaster@${DOMAIN}" 
echo "Subject: Test" 
echo "Date: $(date -R)" 
echo 
echo "Test message" 
) > ${MSG}

sudo -u qmailr env - \
  CONTROLDIR=/tmp/control \
  DKIMSIGN=/var/qmail/control/domainkeys/%/${RSA2048_SELECTOR} \
  DKIMSIGNOPTIONS="-z 2" \
  DKIMQUEUE=/bin/cat \
  /var/qmail/bin/qmail-dkim < ${MSG}

Output:

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; 
       d=domain.tld; s=default; x=1677431613; h=From:To:Subject:Date; 
       bh=PkbvdhgKiEAAhc+GiwM2ZnxMu+StJ76lWGj3Y9phfFA=; b=tqvFwKgs7EspI 
       F3W9kHvSE/FL1cfkE8kDaZkBd2d8R8+aTUEFt9nLk8bQkxWr1A+BUfB80CxAS4CI 
       U7MK+bF5fyQk/xuvyyjQdmEvuL1mQRJq4gshRh43Fs+4CXcJ0WLM6HrQfzFWrRLM 
       hhBrB3ahgDyLCM0cFyzGpyyeuZcxThCtNZmD+XWwk87ONKcNIeJw3pZXqW4I0RuA 
       yOu1rubotq/Q+jgCBmwFiVnBCV8XUsGIUiqB8Rd6Fm+xuY+GZOrUAZksB+G9tyrW 
       vIjuCVbac+nuivJN30Sny9BDjPqRlacg9lFw3GRJgMK5ggqDU9mEJdAvjNtII+qg 
       asw0lc4VQ== 
From: postmaster@domain.tld 
To: postmaster@domain.tld
Subject: Test 
Date: Sun, 19 Feb 2023 18:13:33 +0100 

Test message

In the example above CONTROLDIR=/tmp/control assures that anything defined in control/dkimkeys will interfere in the test.

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

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; 
      d=domain.tld; s=default; h=From:To:Subject:Date; bh=PkbvdhgKiEAA 
       hc+GiwM2ZnxMu+StJ76lWGj3Y9phfFA=; b=W1M3ZoTi+qcb/WwfJK7RIbf3ad0N 
       dBFTEBBDCqcWWnWVptuuILY4uTqq5bAfVEZZGb2O+6f1wuLvwXGbmM2jWvKwXQjJ 
       sFx7EkM+sJ5OtkwIHa/Lu3B91enXHF0bdXwSxkLcqU92UftFzIxArce4XBNBZ9gK 
       QujGix2TkuCOzwGwv3fytt4gizA6yFg+7lbih3m5pAi+MH77yWywpHEA1Ffl1pqh 
       JHbX5eM+THXovWFyOCY2tcijFSjMV53SUnckDHZd3sEZHbrM2iv7SUni2Wb/9Yvz 
      /4vGqRqJ0ZAzVqqfdL1kN+SBRV117ZyzNcS2jl+0sMnuDADy/hRD54n46A==

Verification test

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

DOMAIN=domain.tld
MSG=/tmp/mail.txt

( 
echo "From: postmaster@${DOMAIN}" 
echo "To: postmaster@${DOMAIN}" 
echo "Subject: Test" 
echo "Date: $(date -R)" 
echo 
echo "Test message" 
) > ${MSG}

sudo -u vpopmail env - \
DKIMQUEUE=/bin/cat \
/var/qmail/bin/qmail-dkim < ${MSG}

Output:

DKIM-Status: no signatures 
From: postmaster@domain.tld 
To: postmaster@domain.tld 
Subject: Test 
Date: Sun, 19 Feb 2023 19:58:22 +0100 

Test message

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

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

First of all, be aware that the DKIMDOMAIN variable is 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.

Insert the 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 /var/qmail/control/domainkeys/default

Testing

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.

DOMAIN=domain.tld
MSG=/tmp/mail.txt

( 
echo "From: postmaster@${DOMAIN}" 
echo "To: postmaster@${DOMAIN}" 
echo "Subject: Test" 
echo "Date: $(date -R)" 
echo 
echo "Test message" 
) > ${MSG}

sudo -u vpopmail env - \
   DKIMQUEUE=/bin/cat \
   DKIMKEY=/var/qmail/control/domainkeys/%/default
   RELAYCLIENT=""
   /var/qmail/bin/qmail-dkim < ${MSG}

Output:

DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed;
        d=domain.tld; s=default; x=1298483339; h=To:From:Subject;
        bh=6rJdFs2WVS8T72i61KhaAvC6O6s=; b=ffnXBB98Gg6iZFEIL6alk8c5davso
        ozyrunXM3C8qaejIrJOwYhnlWQwSdrV599WErmJcDYyMjFjVgLzRQ9OTeYHjEnHT
        X/aiIkvjcxRuOaTK7PcwrcJGdtF0c6LWoK9RgiPctCw7DMcHGmUcSyXWc6ayzHgX
        A7nopQYuHzTuIU=
From: postmaster@domain.tld 
To: postmaster@domain.tld 
Subject: Test 
Date: Sun, 19 Feb 2023 19:58:22 +0100

Test message

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

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

Signing with multiple keys. Customizing the selector

man dkim, man spawn-filter for more info

Starting from version 1.37 of the dkim patch, we have the ed25519 support, a new cryptographic signature algorithm for DKIM added by the RFC 8463. Currently no one is verifing the signature with this algorithm, so (Transition Considerations of the RFC 8463)

For backward compatibility, signers can add multiple signatures that use old and new signing algorithms. Since there can only be a single key record in the DNS for each selector, the signatures have to use different selectors, although they can use the same d= and i= identifiers.

In other words, if we want to play with ed25519, we can have two signatures for the same domain: one for rsa and one for ed25519.

Assuming that we have already created the rsa key, here is how to generate the ed25519 one with dknewkey:

# dknewkey -d domain.tld -t ED25519 ed25519 
Generating ed25519 DKIM private key keysize=2048, file /var/qmail/control/domainkeys/domain.tld/ed25519 
Generating ed25519 DKIM public  key for ed25519.domainkey.domain.tld, file /var/qmail/control/domainkeys/domain.tld/ed25519.pub 
DKIM Private key for domain.tld file /var/qmail/control/domainkeys/domain.tld/ed25519 
-----BEGIN PRIVATE KEY----- 
MC4CAQAwBQYDK2VwBCIEIBdgashw5uHx2zxoDCRyIUvPp7Le0d0ljtKiwFreQo58 
-----END PRIVATE KEY----- 
-rw-r----- 1 root qmail 119 Feb 19 13:52 /var/qmail/control/domainkeys/domain.tld/ed25519 
------------------------------------------------------ 
DKIM TXT record for domain.tld with selector=ed25519 file /var/qmail/control/domainkeys/domain.tld/ed25519.pub 
ed25519._domainkey.domain.tld. IN TXT ("v=DKIM1; k=ed25519; t=y; p=l+ZydrxSK4GvFEQvVTKaFxY3+LUh4cCxktsLy8Y2Gl8=") 
-rw-r--r-- 1 root qmail 114 Feb 19 13:52 /var/qmail/control/domainkeys/domain.tld/ed25519.pub 
------------------------------------------------------

In this example "ed25519" is the name of the selector for the ed25519 key.

Now let's see how to manage multiple keys and customize the selector name by using control/filterargs (man spawn-filter). The filterargs control file format can have wildcards or regular expressions.

In the filterargs example below, the first line is for example.* domains. One rsa and another ed25519 keys are declared.

The second line matches all other domains, which will be signed with an rsa key.

example.*:remote:/var/qmail/bin/qmail-dkim:DKIMQUEUE=/bin/cat,DKIMSIGN=/var/qmail/control/domainkeys/%/default,DKIMSIGNOPTIONS=-z 2,DKIMSIGNEXTRA=/var/qmail/control/domainkeys/%/ed25519,DKIMSIGNOPTIONSEXTRA=-z 4
*:remote:/var/qmail/bin/qmail-dkim:DKIMQUEUE=/bin/cat,DKIMSIGN=/var/qmail/control/domainkeys/%/default,DKIMSIGNOPTIONS=-z 2

Note the DKIMQUEUE=/bin/cat variable which has to be passed to qmail-dkim.

The DKIMSIGN and DKIMSIGNOPTIONS variables belong to the the first key, which have the default selector. DKIMSIGNOPTIONS=-z 2 specifies that the hash for that key will be rsa-sha256 (rsa with 2048 bits).

DKIMSIGNEXTRA and DKIMSIGNOPTIONSEXTRA in the first line refers to the second key declared, which has ed25519 as selector. DKIMSIGNOPTIONSEXTRA=-z 4 means that it will have the ed25519 hash.

NOTE: use DKIMSIGNOPTIONSEXTRA=-z 4 and not DKIMSIGNOPTIONSEXTRA="-z 4" syntax in this file.

`filterargs` format

The format of the filterargs file is of the form domain:args for both local and remote mails. domain:remote:args for remote mails and domain:local:args for local mails:

domain:remote:/var/qmail/bin/qmail-dkim:DKIMQUEUE=/bin/cat[,OPTION1=1,OPTION2=2,OPTION3=3 ...]

NOTE: domain can be a regular expression understood by egrep, e.g. sagr*.* will match sagredo.eu, sagredo.com. etc.

You can have multiple lines in the control file filterargs. If there are multiple matches, then the first match will be used.

As always, the basename of the private key file will be used as the selector.

When DKIMSIGN or DKIMKEY has '%' character, it is replaced by domain.tld. If after the replacement the private key is not found, the '%' character will be removed.

e.g. if DKIMSIGN=/var/qmail/control/domainkeys/%/private and the file /var/qmail/control/domainkeys/domain.tld/private is not found, then qmail-dkim will use /var/qmail/control/domainkeys/private as the private key file.

Testing

To test the double signature just repeat the example test shown above but adding the DKIMSIGNEXTRA and DKIMSIGNOPTIONSEXTRA for the ed25519 signature.

DOMAIN=domain.tld
RSA2048_SELECTOR=default 
ED25519_SELECTOR=ed25519
MSG=/tmp/mail.txt

( 
echo "From: postmaster@${DOMAIN}" 
echo "To: postmaster@${DOMAIN}" 
echo "Subject: Test" 
echo "Date: $(date -R)" 
echo 
echo "Test message" 
) > ${MSG} 

sudo -u qmailr env - \
  CONTROLDIR=/tmp/control \
  DKIMQUEUE=/bin/cat \
  DKIMSIGN=/var/qmail/control/domainkeys/%/${RSA2048_SELECTOR} \
  DKIMSIGNOPTIONS="-z 2" \
  DKIMSIGNEXTRA=/var/qmail/control/domainkeys/%/${ED25519_SELECTOR} \
  DKIMSIGNOPTIONSEXTRA="-z 4" \
  /var/qmail/bin/qmail-dkim < ${MSG}

Output:

DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; 
       d=domain.tld; s=default; h=From:To:Subject:Date; bh=PkbvdhgKiEAA 
       hc+GiwM2ZnxMu+StJ76lWGj3Y9phfFA=; b=W1M3ZoTi+qcb/WwfJK7RIbf3ad0N 
       dBFTEBBDCqcWWnWVptuuILY4uTqq5bAfVEZZGb2O+6f1wuLvwXGbmM2jWvKwXQjJ 
       sFx7EkM+sJ5OtkwIHa/Lu3B91enXHF0bdXwSxkLcqU92UftFzIxArce4XBNBZ9gK 
       QujGix2TkuCOzwGwv3fytt4gizA6yFg+7lbih3m5pAi+MH77yWywpHEA1Ffl1pqh 
       JHbX5eM+THXovWFyOCY2tcijFSjMV53SUnckDHZd3sEZHbrM2iv7SUni2Wb/9Yvz 
       /4vGqRqJ0ZAzVqqfdL1kN+SBRV117ZyzNcS2jl+0sMnuDADy/hRD54n46A== 
DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; 
       d=domain.tld; s=ed25519; h=From:To:Subject:Date; bh=PkbvdhgKiEAA 
       hc+GiwM2ZnxMu+StJ76lWGj3Y9phfFA=; b=JzENCy7Xmtp/BW+xRPdHJuao+gTu 
       q182WxDSu+YDAyBEbEJw3fFDWcDEWuKFETV0f3HMdtn6G4Gt+0+w4WrkDA== 
From: postmaster@domain.tld
To: postmaster@domain.tld
Subject: Test 
Date: Sun, 19 Feb 2023 18:01:34 +0100 

Test message

CONTROLDIR=/tmp/control assures that the program will not read anything in the qmail/control directory.

add a comment

Comments

Some "\" at the end of the line are having spaces after ...

idollar March 19, 2024 22:05 CET

Hello Roberto,

Thanks for the guide !!!

I have noticed that in some of the scripts, the commands are split across various lines with "\"

Unfortunatelly, in some cases there are spaces after ... I mean "\ " is written, which does not allows to directly copy and paste. One has to remove the extra " " after the "\".

You can find an example under the "/var/qmail/rc" script.

Regards

SPF:	PASS with IP 1.1.1.1 Learn more
DKIM:	'FAIL' with domain domain1.com Learn more
DMARC:	'FAIL' Learn more

Configuring DKIM for qmail

Index

Changelog

Acknowlegments

Creating the domainkey signature for your outgoing emails

dknewkey 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

Configuring qmail-smtpd for signing outgoing messages

qmail-smtpd run script

Testing

Making qmail-dkim and simscan live together in peace

Choosing between DKIMSIGN and DKIMKEY

Signing with multiple keys. Customizing the selector

filterargs format

Testing

Comments

`dknewkey` usage

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

Making `qmail-dkim` and `simscan` live together in peace

Choosing between `DKIMSIGN` and `DKIMKEY`

`filterargs` format