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 multi-server installation. On a single server, see DKIM configuration.
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.
Amavis and SpamAssassin run on every MTA server, next to the milter, so the configuration is done on every MTA server. It 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.
List the MTA servers:
sudo su - zimbra -c 'zmprov gas mta'
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. It is one name for all servers: the milter on every MTA server writes its result under it, and SpamAssassin on every MTA server trusts only results under it. So the rules file is the same on every MTA server.
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. Run this on every MTA server; $(zmhostname) is the server you run it on:
sudo su - zimbra -c 'zmprov ms $(zmhostname) zimbraAmavisEnableDKIMVerification FALSE'
Zimbra writes the setting into the configuration of Amavis within a minute. Check it on every MTA server:
sudo grep enable_dkim_verification /opt/zimbra/conf/amavisd.conf
The line must start with $enable_dkim_verification = 0;.
To see the setting of all MTA servers at once, run this on any Zimbra server. Every MTA server must show FALSE:
sudo su - zimbra -c 'for s in $(zmprov gas mta); do zmprov gs $s zimbraAmavisEnableDKIMVerification; done'
This alone is not enough: when Amavis hands over no result, SpamAssassin verifies the signatures itself.
Add the SpamAssassin rules
Do this on every MTA server.
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. Use the same name on every MTA server, also on those whose host name is different:
| 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
Do this on every MTA server.
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.
A new MTA server
When you add an MTA server later, do both parts on it as well: turn off the DKIM verification of its Amavis and add the same rules file. Until then, mail that the new server receives and a rule changes is scored by the broken signature.
Mail through more than one MTA server
The configuration works for mail that passes one MTA server on its way in, as on Zimbra by default: the MTA server that receives a message delivers it to the mailbox server.
If one MTA server relays incoming mail to another, for example a gateway in front of the other MTA servers, the milter on the second one verifies the message again, after the rules of the first changed it, and replaces the result with a failed one.
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 on every MTA server that the file is still there and run the check again.
Removing the configuration
On every MTA server, 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, on every MTA server. 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
- Milters configuration - the MTA servers and their milters