diff --git a/docs/administration/rspamadm/dkim-management.md b/docs/administration/rspamadm/dkim-management.md index 5ae2cb1e9..a37c6cdad 100644 --- a/docs/administration/rspamadm/dkim-management.md +++ b/docs/administration/rspamadm/dkim-management.md @@ -58,11 +58,14 @@ default._domainkey.example.com. IN TXT ( "v=DKIM1; k=rsa; " ### Options ``` --d, --domain Domain name --s, --selector DKIM selector (default: "default") --k, --privkey Save private key to file --b, --bits Key length in bits (default: 1024) --t, --type Key type (default: rsa) +-d, --domain Domain name +-s, --selector DKIM selector (default: mail) +-k, --privkey Save private key to file +-b, --bits Key length in bits (default: 1024) +-t, --type Key type (default: rsa) +-o, --output Public key output format (default: dns) + --priv-output Private key output format, RSA only (default: pem) +-f, --force Force overwrite of existing files ``` ### Key Type Recommendations diff --git a/docs/modules/dkim_signing.md b/docs/modules/dkim_signing.md index 1a2414339..e87e10d20 100644 --- a/docs/modules/dkim_signing.md +++ b/docs/modules/dkim_signing.md @@ -6,7 +6,7 @@ title: DKIM signing module # DKIM signing module -The Rspamd 1.5 version has introduced a convenient method of configuring DKIM signing through the addition of the DKIM signing module. A more customizable option is available in the DKIM module through the [sign_condition](/modules/dkim#dkim-signatures). +The Rspamd 1.5 version has introduced a convenient method of configuring DKIM signing through the addition of the DKIM signing module. For more advanced control, signing can be driven by a custom `sign_condition` Lua function, supported by both this module and the [DKIM module](/modules/dkim). DKIM signing currently works with Milter based MTAs (Sendmail, Postfix), Haraka & Communigate. For DKIM signing to work, you must [scan outbound mail with rspamd](/tutorials/scanning_outbound). diff --git a/docs/tutorials/dkim_signing_guide.md b/docs/tutorials/dkim_signing_guide.md index 112543a76..7f9c16c6a 100644 --- a/docs/tutorials/dkim_signing_guide.md +++ b/docs/tutorials/dkim_signing_guide.md @@ -103,8 +103,14 @@ sudo rspamadm configtest # Restart Rspamd sudo systemctl restart rspamd -# Test DKIM signing -echo "Test message" | rspamc -d example.com -f test@example.com +# Test DKIM signing. The From: header domain must match the authenticated user. +rspamc -u test@example.com <<'EOF' | grep "DKIM_SIGNED" +From: test@example.com +To: rcpt@example.net +Subject: DKIM test + +Test message +EOF ``` ## Advanced Configurations @@ -701,7 +707,7 @@ test.example.com ```bash # /etc/systemd/system/rspamd.service.d/vault.conf [Service] -Environment="VAULT_DKIM_TOKEN=s.AhTThjWhKZAf97VowxG6blyu" +Environment="RSPAMD_VAULT_DKIM_TOKEN=s.AhTThjWhKZAf97VowxG6blyu" Environment="VAULT_ADDR=http://127.0.0.1:8200" ``` @@ -793,10 +799,10 @@ check_dns_records() { check_rspamd_signing() { log "INFO: Testing DKIM signing..." - # Test signing with a sample message - local test_result=$(echo "Test message" | rspamc -d example.com -f test@example.com 2>&1) + # Test signing with a sample message (From: header domain must match the auth user) + local test_result=$(printf 'From: test@example.com\nTo: rcpt@example.net\nSubject: DKIM test\nMessage-Id: \n\nTest message\n' | rspamc -u test@example.com 2>&1) - if echo "$test_result" | grep -q "DKIM-Signature:"; then + if echo "$test_result" | grep -q "DKIM_SIGNED"; then log "INFO: DKIM signing test passed" else log "ERROR: DKIM signing test failed: $test_result" @@ -851,8 +857,14 @@ rspamadm configtest # Check Vault connectivity from Rspamd rspamc stat -# Test DKIM signing -echo "Test message" | rspamc -d example.com -f test@example.com +# Test DKIM signing (From: header domain must match the authenticated user) +rspamc -u test@example.com <<'EOF' | grep "DKIM_SIGNED" +From: test@example.com +To: rcpt@example.net +Subject: DKIM test + +Test message +EOF ``` **6.3 Monitor Logs** @@ -954,14 +966,14 @@ Implement regular key rotation for security: ```hcl # /etc/rspamd/local.d/dkim_signing.conf +# Map of domains to selectors (supports rotation across multiple selectors) +selector_map = "/etc/rspamd/dkim_selectors.map"; + domain { example.com { # Current key selector = "2024a"; path = "/etc/rspamd/dkim/example.com/2024a.key"; - - # Alternative selectors for rotation - selector_map = "/etc/rspamd/dkim_selectors.map"; } } ``` @@ -1145,18 +1157,35 @@ domain { path = "/shared/dkim/example.com/shared.key"; } } +``` -# Server-specific keys -server_keys = "/etc/rspamd/local_dkim_keys.map"; +Alternatively, when each mail server must sign with its own key, configure a +per-host selector and key on each server individually. Rspamd has no single +runtime option to map hostnames to keys, so this is done per host: + +```hcl +# /etc/rspamd/local.d/dkim_signing.conf (on mx1.example.com) +domain { + example.com { + selector = "mx1"; + path = "/etc/rspamd/dkim/example.com/mx1.key"; + } +} ``` -```bash -# /etc/rspamd/local_dkim_keys.map -# server-specific keys for different mail servers -mx1.example.com mx1 /etc/rspamd/dkim/mx1.key -mx2.example.com mx2 /etc/rspamd/dkim/mx2.key +```hcl +# /etc/rspamd/local.d/dkim_signing.conf (on mx2.example.com) +domain { + example.com { + selector = "mx2"; + path = "/etc/rspamd/dkim/example.com/mx2.key"; + } +} ``` +Each selector (`mx1._domainkey.example.com`, `mx2._domainkey.example.com`) +must be published as its own DNS TXT record. + ### Cloud Provider Setup Configuration for cloud email services: @@ -1230,25 +1259,13 @@ sign_networks = [ 2. **DNS testing**: ```bash - # Test DNS propagation - dig TXT mail._domainkey.example.com - - # Test DKIM validation - rspamadm dkim_keygen -t -s mail -d example.com + # Verify the published public key resolves + dig TXT mail._domainkey.example.com +short ``` ### Performance Optimization -1. **Key caching**: - ```hcl - # /etc/rspamd/local.d/dkim_signing.conf - - # Cache keys in memory - cache_key = true; - cache_expiry = 3600; - ``` - -2. **Selective signing**: +1. **Selective signing**: ```hcl # Only sign necessary mail sign_authenticated = true; # Sign authenticated mail @@ -1288,19 +1305,35 @@ sign_networks = [ # Check logs tail -f /var/log/rspamd/rspamd.log | grep -i dkim - # Test manually - echo "test" | rspamc -d example.com -f test@example.com + # Test manually (From: header domain must match the authenticated user) + rspamc -u test@example.com <<'EOF' + From: test@example.com + To: rcpt@example.net + Subject: DKIM test + + Test message + EOF ``` ### Testing DKIM 1. **Manual testing**: ```bash - # Test signing with rspamc - rspamc -d example.com -f sender@example.com -r recipient@test.com < test_message.eml - - # Check for DKIM-Signature header + # Scan a message as an authenticated user. Its From: header domain must match + # the user (e.g. From: sender@example.com). + rspamc -u sender@example.com <<'EOF' + From: sender@example.com + To: recipient@example.net + Subject: DKIM test + + Test message + EOF ``` + A signed message reports the `DKIM_SIGNED` symbol and a (folded, multi-line) + `DKIM-Signature:` header. To print the whole signature, add `-j` and pipe the + JSON through `jq -r '."dkim-signature"'`. + (`-F`/`--from` sets the SMTP envelope sender, not the From: header that DKIM + signs, so it cannot replace the `From:` above with `use_domain = "header"`.) 2. **External validation**: ```bash @@ -1310,29 +1343,6 @@ sign_networks = [ # - dkimvalidator.com ``` -3. **Automated testing**: - ```bash - #!/bin/bash - # dkim_test.sh - - DOMAIN="example.com" - SELECTOR="mail" - - # Test key generation - if rspamadm dkim_keygen -t -s $SELECTOR -d $DOMAIN; then - echo "DKIM validation: PASS" - else - echo "DKIM validation: FAIL" - fi - - # Test signing - if echo "test" | rspamc -d $DOMAIN | grep -q "DKIM-Signature"; then - echo "DKIM signing: PASS" - else - echo "DKIM signing: FAIL" - fi - ``` - ## Monitoring and Maintenance ### Monitoring Scripts