First, rule out issues unrelated to the actual signature
- Check the A-R headers:
Authentication-Results: host; dkim=fail
means the signature failed, but Authentication-Results: host; dkim=permerror
might instead just mean the recipient was unable to grab your key.
- Check the topmost
Received:
header not related the the recipient, if that is not you, you are looking at forwarded mail.
Then, determine who caused the signature to break
Grab a copy of the mail as it was submitted (e.g. stored in IMAP Sent folder), grab a copy of the raw mail as it was received, and compare byte by byte.
If the recipient cannot forward the full headers to you, you might be able to reproduce an issue by mailing it to your own box at the same provider, so you can look at the full headers.
a) You are modifying your own mail AFTER you are signing it, invalidating the signature
Are you sending invalid mail, and your mail system is fixing some problems for you, such as adding a missing Date
header? Fix/Replace non-compliant MUAs.
Is some software you use for outgoing spam filtering modifying headers you are signing?
Ensure that the order of mail processing software places the signing last, after any such modification.
b) The recipient is modifying your mail BEFORE verifying your signature, therefore unable to verify your signature
Examples I have seen in the wild:
- overlong lines have been refolded
- Apply appropriate folding before sending - though using a
relaxes
DKIM canonicalization can be sufficient.
- some software that does accept recipient addresses case insensitively (typically Microsoft) switched letter case of recipients to their canonical form
- Updating your address books with the canonical (typically lowercase) spelling!
- the recipient mail server encoded Internationalized domain name (IDN) it received as UTF-8
- This should be obvious because it will only happen with specific domains somewhere in the header. Send non-ASCII domains in idna encoding (
xn--..
)!
- you signed a header that is often legitimately modified by recipients
- Do not sign headers such as
Received
or X-Spam-Status
!
Note that if you mail server cannot apply the suggested transformation, you can still reject mail that you expect the fail - the sender can then try to use a different mail client or recipient address (or least notice something is wrong).