Skip to content
Get Stalwart

DKIM

A domain that signs its mail with DKIM has no direct way to see that its signatures fail at the receiving end. DKIM failure reporting (RFC 6651) gives it that view: a receiving server reports each signature that fails verification back to the signing domain. A failure points to one of a few problems: a broken signing setup, a key that is not published, or messages modified in transit.

A signer opts in to these reports in two places. Its signatures carry the r=y tag, which requests reports, and a TXT record at _report._domainkey.<domain> publishes the address to report to. Each report is a message in the Abuse Reporting Format (RFC 6591), a standard format for reports about individual messages, and describes one failed signature.

Stalwart plays both roles. As a receiver, it sends a DKIM failure report when it verifies a message whose signature fails and requests reports, at the rate allowed by sendFrequency. As a signer, its own signatures request reports while their report field is enabled, as it is by default (Signing).

The reports that Stalwart sends are configured on the DkimReportSettings singleton (found in the WebUI under Settings › MTA › Reports › DKIM). Each field is an expression evaluated with the RCPT TO variables. The fields answer two questions: how many reports to send, and what the report message looks like.

sendFrequency decides how many reports go to each report address, as a count and a period. Setting it to false disables DKIM failure reports altogether. The default rate of 1 per day limits the reports sent to each address.

The other fields describe the report message:

  • fromName and fromAddress set the display name and the address of the report’s sender.
  • subject sets the subject of the report message.
  • dkimSignDomain sets the domain whose DKIM keys sign the report.

The default sender address and signing domain are built from system('report_domain'). This expression returns the report domain shared by all reports, or the default domain unless the report domain is set.

The following object body disables DKIM failure reports:

{
  "sendFrequency": {"else": "false"}
}

Reports also travel in the other direction. Failure reports that other servers send about the domains hosted on Stalwart are analysed as described in Analysis.