mirror of
https://blitiri.com.ar/repos/chasquid
synced 2026-10-29 15:02:30 +00:00
Alberto Bertogli
9a59bd77d1
This patch uses mdformat to auto-format markdown documentation. To support \ for line breaks (which is what mdformat uses), mkdocs now requires the pymdownx.escapeall extension. Because of incompatibilities between mdformat (which formats to CommonMark) and mkdocs (which expects Python-Markdown), there are now some limitations: no nested lists, multi-paragraph list items, or admonitions support. These limitations are acceptable for now, although some of the docs had to be adjusted to meet them.
83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# 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
|
|
|
|
- Run `chasquid-util dkim-keygen DOMAIN` to generate a DKIM private key for
|
|
your domain. The file will be in `/etc/chasquid/domains/DOMAIN/dkim:*.pem`.
|
|
- Publish the DKIM DNS record which was shown by the previous command (e.g. by
|
|
following [this guide](https://support.dnsimple.com/articles/dkim-record/)).
|
|
- Change the key file's permissions, to ensure it is readable by chasquid (and
|
|
nobody else).
|
|
- Restart chasquid.
|
|
|
|
It is highly recommended that you use a DKIM checker (like
|
|
[Learn DMARC](https://www.learndmarc.com/)) 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](https://tools.ietf.org/html/rfc6376#section-6.3),
|
|
[source 2](https://tools.ietf.org/html/rfc7601#section-2.7.1)).
|
|
|
|
## Other implementations
|
|
|
|
[chasquid] also supports [DKIM] via the [hooks] mechanism. This can be useful
|
|
if more customization is needed.
|
|
|
|
Implementations that have been tried:
|
|
|
|
- [driusan/dkim]
|
|
- [dkimpy]
|
|
|
|
[chasquid]: https://blitiri.com.ar/p/chasquid
|
|
[dkim]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail
|
|
[dkimpy]: https://launchpad.net/dkimpy/
|
|
[driusan/dkim]: https://github.com/driusan/dkim
|
|
[example hook]: https://blitiri.com.ar/git/r/chasquid/b/next/t/etc/chasquid/hooks/f=post-data.html
|
|
[hooks]: hooks.md
|
|
[rfc 8601]: https://datatracker.ietf.org/doc/html/rfc8601
|
|
[`authentication-results:`]: https://en.wikipedia.org/wiki/Email_authentication#Authentication-Results
|