haraka-plugin-dkim

INSTALL

cd /path/to/local/haraka
npm install haraka-plugin-dkim
echo "dkim" >> config/plugins
service haraka restart

Configuration

If the default configuration is not sufficient, copy the config file from the distribution into your haraka config dir and then modify it:

cp node_modules/haraka-plugin-dkim/config/dkim.ini config/dkim.ini
$EDITOR config/dkim.ini

SIGNING

This plugin implements the DKIM Core specification.

Getting Started

Generate a DKIM selector and keys for your domain:

cd /path/to/haraka/config/dkim
./dkim_key_gen.sh example.org

Within the config/dkim/${domain} directory will be 4 files:

ls config/dkim/example.org/
dns private public selector

The selector file contains the DNS label where the DKIM public key is published. The private and public files contain the DKIM keys.

The dns file contains a formatted record of the public key suitable for copy/pasting into your domains zone file. It also has suggestions for DKIM, SPF, and DMARC policy records.

The DKIM DNS record will look like this:

may2013._domainkey TXT "v=DKIM1;p=[public key stripped of whitespace];"

The values in the address have the following meaning:

hash: h=[ sha1 | sha256 ]
test; t=[ s | s:y ]
granularity: g=[ ]
notes: n=[ ]
services: s=[email]
keytypes: [ rsa ]

Key size

The default key size created by dkim_key_gen.sh is 2048. That is considered secure as of mid-2024.

What to sign

The DKIM signing key for messages from example.org should be signed with a DKIM key for example.org. Failing to do so will result in messages not having an aligned DKIM signature. For DMARC enabled domains, this will likely result in deliverability problems.

For correct alignment, Haraka signs each message with that domains DKIM key. For an alternative, see the legacy Single Domain Configuration below.

Configuration

DKIM signing is configured in the sign section of dkim.ini.

[sign]
enabled = [ 1 | true | yes ], default=false
headers = list, of; headers (REQUIRED)

; for single domain configuration
selector = name
domain = name

• headers: the list of headers that should be signed, separated by commas, colons or semi-colons. Signing prevents tampering with the specified headers. The 'From' header is required by the RFC and will be added if missing.

Single Domain Configuration

To sign all messages with a single DKIM key, you must set the selector and domain in dkim.ini. You must also save your DKIM private key in the file dkim.private.key in the Haraka config directory.

• selector - Set this to the selector name published in DNS under the _domainkey sub-domain of the domain referenced below.

• domain - Set this to the domain name that will be used to sign messages which don't match a per-domain DKIM key. The DNS TXT entry for:

  ._domainkey.

Test that your DKIM key is published properly with a DNS request like this:

drill TXT $SELECTOR._domainkey.$DOMAIN
dig TXT $SELECTOR._domainkey.$DOMAIN +short

Example DNS query

export SELECTOR=mar2013
export DOMAIN=simerson.net
$ dig TXT $SELECTOR._domainkey.$DOMAIN +short
"v=DKIM1;p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoyUzGOTSOmakY8BcxXgi0mN/nFegLBPs7aaGQUtjHfa8yUrt9T2j6GSXgdjLuG3R43WjePQv3RHzc+bwwOkdw0XDOXiztn5mhrlaflbVr5PMSTrv64/cpFQKLtgQx8Vgqp7Dh3jw13rLomRTqJFgMrMHdhIibZEa69gtuAfDqoeXo6QDSGk5JuBAeRHEH27FriHulg5ob" "4F4lmh7fMFVsDGkQEF6jaIVYqvRjDyyQed3R3aTJX3fpb3QrtRqvfn/LAf+3kzW58AjsERpsNCSTD2RquxbnyoR/1wdGKb8cUlD/EXvqtvpVnOzHeSeMEqex3kQI8HOGsEehWZlKd+GqwIDAQAB"

DKIM VERIFY

Verify DKIM signatures as defined by RFC 6376 and add an Authentication-Results header as appropriate.

Configuration

[verify]
; allowed_time_skew = (How far can we stretch on time matching, in secs. Useful when clock is skewed.)
; sigerror_log_level =

Testing

This plugin provides a command-line test tool that can be used to debug DKIM issues or to check results.

# dkimverify < message
identity="@gmail.com" domain="gmail.com" result=pass

You can add --debug to the option arguments to see a full trace of the processing.

Notes

This plugin and underlying library do not currently support DKIM body length limits (l=).