DKIM configuration
Use this configuration when your rules change incoming mail and you want the DKIM signatures of that mail to keep counting. For example:
- a rule tags the subject of mail from outside, such as
[EXTERNAL], - a rule adds a disclaimer or a note to the body of incoming mail.
Any change to the subject or the body breaks a DKIM signature. Without this configuration Zimbra checks the signature after the change, takes the sender's valid signature for a broken one, and can put legitimate mail into Junk. With it, Zimbra uses the result DKIM verification got before the rules changed anything, so DKIM verification must be on.
If your rules do not change incoming mail, skip this page. A message banner or a sender tag does not change the subject or the body, so it does not need this configuration either.
This page is for a single server installation. In a multi-server installation, see DKIM configuration for the MTA servers.
Why the signature breaks
With DKIM verification on, the milter verifies the DKIM signatures of every incoming message before any rule changes it, and writes the result to an Authentication-Results header. Amavis and SpamAssassin run after the milter on Zimbra and verify the signatures again. A rule that changed the message, for example one that tags the subject or adds a disclaimer, broke the signature by then, so they see a failed signature instead of a valid one.
That costs points mainly through Zimbra's DMARC rules. Mail from a domain with the DMARC policy p=quarantine or p=reject whose signature fails, and whose SPF does not pass either, gets DMARC_FAIL_QUAR (6 points) or DMARC_FAIL_REJECT (9 points) and ends up in Junk. In a test, a message of a bank with p=quarantine whose subject a rule tagged scored 6.6 and went to Junk; with this configuration it scored 0.3 and reached the Inbox.
The configuration has two parts:
- Turn off the DKIM verification of Amavis, so it keeps the result of the milter.
- Add a SpamAssassin rules file, so SpamAssassin takes the result of the milter as a valid signature.
Before you start
Turn on DKIM verification on the DKIM Verification page of the administrator panel, and note the Server name in the result header, for example mail.example.com. The milter writes its result under this name, and SpamAssassin trusts only results under it.
Turn off the DKIM verification of Amavis
While it is on, Amavis removes the header of the milter and adds its own, with the result it got after the rules changed the message:
sudo su - zimbra -c 'zmprov ms $(zmhostname) zimbraAmavisEnableDKIMVerification FALSE'
Zimbra writes the setting into the configuration of Amavis within a minute. Check it:
sudo grep enable_dkim_verification /opt/zimbra/conf/amavisd.conf
The line must start with $enable_dkim_verification = 0;.
This alone is not enough: when Amavis hands over no result, SpamAssassin verifies the signatures itself.
Add the SpamAssassin rules
Edit the file /opt/zimbra/data/spamassassin/localrules/zz-msh-dkim.cf and paste this content:
# DKIM result of MSH Zimbra Rules for SpamAssassin 4.0
loadplugin Mail::SpamAssassin::Plugin::AuthRes
authres_trusted_authserv __SERVER_NAME__
header MSH_DKIM_PASS eval:check_authres_result('dkim', 'pass')
header MSH_DKIM_PASS_AU Authentication-Results =~ /^__SERVER_NAME_ESCAPED__;[^\n]*\bdkim=pass \(aligned\)/m
score MSH_DKIM_PASS -0.1
score MSH_DKIM_PASS_AU -0.1
score DKIM_INVALID 0
meta __FORGED_SENDER (!SPF_PASS && !DKIM_VALID_AU && !MSH_DKIM_PASS_AU)
ifplugin Mail::SpamAssassin::Plugin::AskDNS
meta DMARC_FAIL_REJECT !(DKIM_VALID_AU || MSH_DKIM_PASS_AU || SPF_PASS) && __DMARC_POLICY_REJECT
meta DMARC_FAIL_QUAR !(DKIM_VALID_AU || MSH_DKIM_PASS_AU || SPF_PASS) && __DMARC_POLICY_QUAR
meta DMARC_FAIL_NONE !(DKIM_VALID_AU || MSH_DKIM_PASS_AU || SPF_PASS) && __DMARC_POLICY_NONE
meta DMARC_PASS_REJECT (DKIM_VALID_AU || MSH_DKIM_PASS_AU) && SPF_PASS && __DMARC_POLICY_REJECT
meta DMARC_PASS_QUAR (DKIM_VALID_AU || MSH_DKIM_PASS_AU) && SPF_PASS && __DMARC_POLICY_QUAR
meta DMARC_PASS_NONE (DKIM_VALID_AU || MSH_DKIM_PASS_AU) && SPF_PASS && __DMARC_POLICY_NONE
endif
Replace the two placeholders with the server name you noted:
| Placeholder | Replace with | Example |
|---|---|---|
__SERVER_NAME__ | The server name as it is | mail.example.com |
__SERVER_NAME_ESCAPED__ | The server name with a backslash before each dot | mail\.example\.com |
The backslashes matter: in the second place the name is a pattern, where a dot alone matches any character. Save the file.
Check that no placeholder is left. The command prints 0:
sudo grep -c __SERVER_NAME /opt/zimbra/data/spamassassin/localrules/zz-msh-dkim.cf
Give the file to the zimbra user:
sudo chown zimbra:zimbra /opt/zimbra/data/spamassassin/localrules/zz-msh-dkim.cf
Make it readable for SpamAssassin:
sudo chmod 644 /opt/zimbra/data/spamassassin/localrules/zz-msh-dkim.cf
The name of the file must sort after salocal.cf, Zimbra's own rules file in the same directory: the file replaces some of its rules, and the file read last wins. Keep the zz- at the start.
What the file does
| Lines | What they do |
|---|---|
loadplugin, authres_trusted_authserv | Load the AuthRes plugin of SpamAssassin, which reads Authentication-Results headers, and trust only the headers under the server name. Headers under other names are ignored. |
MSH_DKIM_PASS | Hits when the milter found a passing signature, of any domain. |
MSH_DKIM_PASS_AU | Hits when the milter found a passing signature of the From domain, marked (aligned) in its header. It stands for SpamAssassin's own DKIM_VALID_AU, which DMARC needs. |
score | The two new rules take 0.1 points off each, about as much as a valid signature does in SpamAssassin. DKIM_INVALID, which hits on every message a rule changed, gets 0 points. |
__FORGED_SENDER, DMARC_FAIL_*, DMARC_PASS_* | Zimbra's DMARC rules, with the result of the milter accepted as a valid signature of the From domain. Their points stay as Zimbra set them. |
The milter removes every Authentication-Results header under the server name that a message arrives with, before it adds its own. So a header under that name can only come from the milter, and a sender cannot fake a passing result.
A passing result means only that the signature was valid when the message arrived. It does not make the message good: spam signed by the spammer's own domain passes too, and is scored on everything else as before.
Check and restart Amavis
Check that SpamAssassin reads the file without errors:
sudo su - zimbra -c 'spamassassin -D config --lint 2>&1 | grep zz-msh-dkim'
The output shows two lines, read file and parsing file, with the path of the file. An error in the file is printed as well. The lint check also prints warnings of Zimbra's own setup, such as netset: cannot include 127.0.0.0/8; they are there without the file too.
Amavis reads the rules only when it starts. Restart it:
sudo su - zimbra -c 'zmamavisdctl restart'
In the headers of a message that passed, the X-Spam-Status header lists MSH_DKIM_PASS and MSH_DKIM_PASS_AU among the tests.
What the file does not cover
- SpamAssassin's DKIM welcome lists.
welcomelist_from_dkim,welcomelist_authand the default list of well-known senders still use SpamAssassin's own verification. - SpamAssassin's own DMARC plugin. Zimbra loads it, but it stays off because a Perl module it needs,
Mail::DMARC, is not installed. If you install the module, its rules use SpamAssassin's own verification. - Other SpamAssassin versions. The file is written for SpamAssassin 4.0, as Zimbra 10.1 ships it.
After a Zimbra upgrade, check that the file is still there and run the check again.
Removing the configuration
Remove the file and restart Amavis:
sudo rm /opt/zimbra/data/spamassassin/localrules/zz-msh-dkim.cf
sudo su - zimbra -c 'zmamavisdctl restart'
If you turn DKIM verification off, also turn the DKIM verification of Amavis on again. Setting the attribute to an empty value removes it from the server entry, so Zimbra falls back to its default, on:
sudo su - zimbra -c 'zmprov ms $(zmhostname) zimbraAmavisEnableDKIMVerification ""'
Additional resources
- DKIM verification - the settings of the verification in the milter
- DKIM result - the condition that tests the result in rules