Extensions to DomainKeys Identified Mail (DKIM) for Failure Reporting
Extracted elements (28)
Placing the report request in the DKIM-Signature header (rather than only in the key record, as in early OpenDKIM implementations) ensures the request is visible even for failure cases where the key record is not retrieved, while the DNS confirmation step prevents forgery.
The two-step design (r= in signature + DNS confirmation record) prevents a malicious Signer from directing reports to an arbitrary address; the DNS record must exist under the Signer's own domain, making it impossible to redirect reports outside that domain. This addresses both unauthorized report flooding and distributed email-based DoS.
The DKIM Reporting TXT record is entirely independent of DKIM key records and is found at a different DNS name ('_report._domainkey.<domain>'). Implementations must not conflate the two record types.
A report generator SHOULD NOT issue more than one report to any given domain as a result of a single message, and SHOULD establish an upper bound on total reports per message, to prevent conversion into a DoS amplifier.
All reports generated by this mechanism MUST comply with RFC 5965 (ARF) and RFC 6591 (ARF-AUTHFAIL). Report generators are strongly advised to DKIM-sign the reports they generate.
For ADSP records, in the absence of an 'ra=' tag, the 'rp=' and 'rr=' tags MUST be ignored and the report generator MUST NOT issue a report.
Implementations MUST support all tags defined in Section 3.2. Any unrecognized tag in the reporting TXT record MUST be ignored.
In the absence of an 'ra=' tag, the 'rp=' and 'rr=' tags MUST be ignored, and the report generator MUST NOT issue a report.
The multiple-string TXT record concatenation procedure from Section 3.6.2.2 of RFC 6376 (DKIM) MUST be applied to DKIM Reporting TXT records that span multiple DNS character-strings.
The reporting algorithm's processing is a reporting extension only; the outcome of the DKIM evaluation MUST be otherwise unaffected.
Verifiers MUST NOT generate reports for incidents that do not match a requested report type (per the 'rr=' tag), and MUST ignore requests for report types not included in the defined list.
A DKIM Reporting TXT record is published in the DNS at '_report._domainkey.<d=value>' and contains tag-value pairs (ra=, rp=, rr=, rs=) that control report generation. It is independent of the DKIM key record and is queried only when 'r=y' appears in a DKIM-Signature.
ADSP failure report-type tokens for 'rr=': 'all' (all failures), 'o' (other ADSP failures), 'p' (local policy rejection), 's' (valid DKIM signature but mismatches ADSP policy), 'u' (no valid DKIM signature and mismatches ADSP policy).
DKIM ADSP records are extended with four optional tags: 'ra=' (reporting address local-part), 'rp=' (report percentage), 'rr=' (requested report types: all/o/p/s/u), and 'rs=' (SMTP error string). The full reporting address appends '@' and the RFC5322.From domain.
DKIM failure report-type tokens for 'rr=': 'all' (all failures), 'd' (DNS/key retrieval issues), 'o' (other), 'p' (local policy rejection), 's' (syntax errors), 'u' (unknown tags), 'v' (verification failure or body hash mismatch), 'x' (expired signature).
The 'r=' tag is added to DKIM-Signature header fields to request that Verifiers generate a failure report. The only legal value is the single character 'y', encoded as lowercase. Its presence triggers the DKIM reporting algorithm.
The 'ra=' tag in the DKIM Reporting TXT record specifies the local-part of the address to which failure reports should be sent. The full address is constructed by appending '@' and the 'd=' domain from the DKIM-Signature.
The 'rp=' tag specifies the percentage (0–100, default 100) of failure incidents that should randomly generate reports. Generators SHOULD NOT exceed this percentage; they MAY use the ARF 'Incidents:' field to indicate unreported incidents.
The 'rr=' tag is a colon-separated list of failure-type tokens (e.g., 'all', 'd', 'o', 'p', 's', 'u', 'v', 'x') specifying which DKIM failure conditions should trigger reports. The default value is 'all'.
The 'rs=' tag provides a dkim-quoted-printable string that the signing ADMD requests be included in SMTP error strings when messages are rejected during the delivery session.
IANA added tag 'r' (status: active) to the DKIM Signature Tag Specifications registry, referencing this document.
IANA added tags 'ra', 'rp', 'rr', and 'rs' to the DKIM ADSP Specification Tags registry, all referencing this document.
IANA created a new 'DKIM Reporting Tag Registry' sub-registry under DKIM Parameters, with 'Specification Required' policy. Initial entries are 'ra', 'rp', 'rr', and 'rs', all active. Required columns: Tag, Reference, Status.
An attacker can forge DKIM-Signature fields with 'r=y' and 'd=<target>' to flood a victim domain with reports. Implementers are strongly advised not to publish the reporting DNS record unless failure reports are actively desired, and should anticipate denial-of-service traffic if they do.
Fraudulent DKIM-Signature fields that omit 'r=' cannot be detected or reported by this mechanism. Extending detection to signatures without 'r=' would create a DoS vector (Verifiers would always query the reporting TXT record), so such reporting is intentionally unsupported.
Report volume is unpredictable and potentially very large. An implementer ought to anticipate substantial volume when enabling this facility, since the amount of abuse cannot be known ahead of time.
The DKIM Reporting Algorithm is a 10-step process: (1) check for 'r=' tag; (2) DNS TXT query to '_report._domainkey.<d=>'; (3) validate RCODE and single-record response; (4) concatenate fragments; (5) validate syntax; (6) match failure reason to 'rr='; (7) apply 'rp=' random sampling; (8–9) construct recipient and send ARF report; (10) optionally include 'rs=' string in SMTP reply. Processing MUST NOT affect the DKIM evaluation outcome.
The sig-r-tag ABNF is: `sig-r-tag = %x72 *WSP "=" *WSP %x79` — i.e., the literal string 'r=y', lowercase only. No other values are defined.