git » chasquid » main » tree

[main] / docs / dkim.md

DKIM integration

chasquid supports verifying and generating DKIM signatures since version 1.14.

All incoming email is verified, and authenticated emails for domains which have a private DKIM key set up will be signed.

In versions older than 1.13, support is possible via the hooks mechanism. In particular, the example hook included support for some command-line implementations. That continues to be an option, especially if customization is needed.

Easy setup

It is highly recommended that you use a DKIM checker (like Learn DMARC) to confirm that your setup is fully functional.

Advanced setup

You need to place the PEM-encoded private key in the domain config directory, with a name like dkim:SELECTOR.pem, where SELECTOR is the selector string.

It needs to be either RSA or Ed25519.

Key rotation

To rotate a key, you can remove the old key file, and generate a new one as per the previous step.

It is important to remove the old key from the directory, because chasquid will use all the keys in it.

You should use a different selector each time. If you don't specify a selector when using chasquid-util dkim-keygen, the current date will be used, which is a safe default to prevent accidental reuse.

Multiple keys

Advanced users may want to sign outgoing mail with multiple keys (e.g. to support multiple signing algorithms).

This is well supported: chasquid will sign email with all keys it find that match dkim:*.pem in a domain directory.

Verification

chasquid will verify all DKIM signatures of incoming mail, and record the results in an [Authentication-Results:] header, as per RFC 8601.

Note that emails will not be rejected even if they fail verification, as this is not recommended (source 1, source 2).

Other implementations

chasquid also supports DKIM via the hooks mechanism. This can be useful if more customization is needed.

Implementations that have been tried: