mirror/docker-mailserver.docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2025-08-04 01:55:29 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

scripts: add DKIM helper script for Rspamd (#3286)

Browse source 
Co-authored-by: Casper <casperklein@users.noreply.github.com>
This commit is contained in:
Georg Lauterbach 2023-05-03 08:30:49 +02:00 • committed by GitHub
parent 423188176f
commit bba72daedf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 600 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

77
docs/content/config/best-practices/dkim_dmarc_spf.md
View file

@ -40,6 +40,10 @@ You should have:
- At least one [email account setup][docs-accounts-add]
- Attached a [volume for config][docs-volumes-config] to persist the generated files to local storage
!!! warning "RSA Key Sizes >= 4096 Bit"
Keys of 4096 bits could be denied by some mail servers. According to [RFC 6376][rfc-6376], keys are [preferably between 512 and 2048 bits][github-issue-dkimlength].
DKIM is currently supported by either OpenDKIM or Rspamd:
=== "OpenDKIM"
@ -48,7 +52,7 @@ DKIM is currently supported by either OpenDKIM or Rspamd:
The command `docker exec <CONTAINER NAME> setup config dkim help` details supported config options, along with some examples.
!!! example "Create a DKIM key"
!!! example "Creating a DKIM key"
Generate the DKIM files with:
@ -74,6 +78,12 @@ DKIM is currently supported by either OpenDKIM or Rspamd:
setup config dkim keysize 2048
```
!!! info "Restart required"
After restarting DMS, outgoing mail will now be signed with your new DKIM key(s) :tada:
You'll need to repeat this process if you add any new domains.
=== "Rspamd"
Opt-in via [`ENABLE_RSPAMD=1`][docs-env-rspamd] (_and disable the default OpenDKIM: `ENABLE_OPENDKIM=0`_).
@ -83,31 +93,33 @@ DKIM is currently supported by either OpenDKIM or Rspamd:
1. [Verifying DKIM signatures from inbound mail][rspamd-docs-dkim-checks] is enabled by default.
2. [Signing outbound mail with your DKIM key][rspamd-docs-dkim-signing] needs additional setup (key + dns + config).
!!! example "Create a DKIM key"
!!! example "Creating DKIM Keys"
Presently only OpenDKIM is supported with `setup config dkim`. To generate your DKIM key and DNS files you'll need to specify:
You can simply run
- `-s` The DKIM selector (_eg: `mail`, it can be anything you like_)
- `-d` The sender address domain (_everything after `@` from the email address_)
```bash
docker exec -ti <CONTAINER NAME> setup config dkim help
```
See `rspamadm dkim_keygen -h` for an overview of the supported options.
which provides you with an overview of what the script can do. Just running
```bash
docker exec -ti <CONTAINER NAME> setup config dkim
```
will execute the helper script with default parameters.
!!! info "About the Helper Script"
The script will persist the keys in `/tmp/docker-mailserver/rspamd/dkim/`. Hence, if you are already using the default volume mounts, the keys are persisted in a volume. The script also restarts Rspamd directly, so changes take effect without restarting DMS.
The script provides you with log messages along the way of creating keys. In case you want to read the complete log, use `-v` (verbose) or `-vv` (very verbose).
---
1. Go inside the container with `docker exec -ti <CONTAINER NAME> bash`
2. Add `rspamd/dkim/` folder to your config volume and switch to it: `cd /tmp/docker-mailserver/rspamd/dkim`
3. Run: `rspamadm dkim_keygen -s mail -b 2048 -d example.com -k mail.private > mail.txt` (_change `-d` to your domain-part_)
4. Presently you must ensure Rspamd can read the `<selector>.private` file, run:
-`chgrp _rspamd mail.private`
-`chmod g+r mail.private`
In case you have not already provided a default DKIM signing configuration, the script will create one and write it to `/etc/rspamd/override.d/dkim_signing.conf`. If this file already exist, it will not be overwritten. When you're already using [the `rspamd/override.d/` directory][docs-rspamd-override-d], the file is created inside your volume and therefore persisted correctly. If you are not using `rspamd/override.d/`, you will need to persist the file yourself (otherwise it is lost on container restart).
---
!!! bug inline end "DMS config volume support is not ready for Rspamd"
Presently you'll need to [explicitly mount `rspamd/modules/override.d/`][docs-rspamd-config-dropin] as an additional volume; do not use [`rspamd-modules.conf`][docs-rspamd-config-declarative] for this purpose.
Create a configuration file for the DKIM signing module at `rspamd/modules/override.d/dkim_signing.conf` and populate it with config as shown in the example below:
An example of what a default configuration file for DKIM signing looks like can be found by expanding the example below.
??? example "DKIM Signing Module Configuration Examples"
@ -124,6 +136,7 @@ DKIM is currently supported by either OpenDKIM or Rspamd:
use_domain = "header";
use_redis = false; # don't change unless Redis also provides the DKIM keys
use_esld = true;
check_pubkey = true; # you wan't to use this in the beginning
domain {
@ -134,7 +147,7 @@ DKIM is currently supported by either OpenDKIM or Rspamd:
}
```
As shown next, you can:
As shown next:
- You can add more domains into the `domain { ... }` section.
- A domain can also be configured with multiple selectors and keys within a `selectors [ ... ]` array.
@ -170,27 +183,19 @@ DKIM is currently supported by either OpenDKIM or Rspamd:
}
```
!!! warning "Support for DKIM keys using Ed25519"
??? warning "Support for DKIM Keys using ED25519"
This modern elliptic curve is supported by Rspamd, but support by third-parties for [verifying Ed25519 DKIM signatures is unreliable][dkim-ed25519-support].
This modern elliptic curve is supported by Rspamd, but support by third-parties for [verifying Ed25519 DKIM signatures is unreliable][dkim-ed25519-support].
If you sign your mail with this key type, you should include RSA as a fallback, like shown in the above example.
If you sign your mail with this key type, you should include RSA as a fallback, like shown in the above example.
!!! tip "DKIM Signing config: `check_pubkey = true;`"
??? tip "Let Rspamd Check Your Keys"
This setting will have Rspamd query the DNS record for each DKIM selector, verifying each public key matches the private key configured.
When `check_pubkey = true;` is set, Rspamd will query the DNS record for each DKIM selector, verifying each public key matches the private key configured.
If there is a mismatch, a warning will be omitted to the Rspamd log (`/var/log/supervisor/rspamd.log`).
If there is a mismatch, a warning will be omitted to the Rspamd log `/var/log/supervisor/rspamd.log`.
!!! info "Restart required"
After restarting DMS, outgoing mail will now be signed with your new DKIM key(s) :tada:
You'll need to repeat this process if you add any new domains.
!!! warning "RSA Key Sizes >= 4096 Bit"
Keys of 4096 bits could denied by some mail servers. According to [RFC 6376][rfc-6376] keys are [preferably between 512 and 2048 bits][github-issue-dkimlength].
[docs-rspamd-override-d]: ../security/rspamd.md#manually
### DNS Record { #dkim-dns }
@ -211,6 +216,8 @@ When mail signed with your DKIM key is sent from your mail server, the receiver
| TTL | Use the default (_otherwise [3600 seconds is appropriate][dns::digicert-ttl]_) |
| Data | File content within `( ... )` (_formatted as advised below_) |
When using Rspamd, the helper script has already provided you with the contents (the "Data" field) of the DNS record you need to create - you can just copy-paste this text.
=== "DNS Zone file"
`<selector>.txt` is already formatted as a snippet for adding to your [DNS Zone file][dns::wikipedia-zonefile].