Extensions to DKIM for Failure Reporting
Cloudmark128 King St., 2nd FloorSan FranciscoCA94107US+1 415 946 3800msk@cloudmark.com
Applications
MARF Working GroupInternet-DraftStandards Track This memo presents extensions to the DomainKeys Identified
Mail (DKIM) specification to allow for detailed reporting
of message authentication failures in an on-demand
fashion. introduced a mechanism for message
signing and authentication. It uses digital signing to
associate a domain name with a message in a reliable
(i.e. not forgeable) manner. The output is a verified
domain name that can then be subjected to some sort of
evaluation process (e.g., advertised sender policy,
comparison to a known-good list, submission to a
reputation service, etc.). Deployers of message authentication technologies
are increasingly seeking visibility into DKIM verification
failures and conformance failures involving the
published signing practices (e.g., )
of an Administrative Management Domain (ADMD; see
). This document extends and
to add an optional reporting
address and some reporting parameters. Reports are
generated using the format defined in
. The key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described
in . The ABNF token "qp-section" is imported from
. Numerous DKIM-specific terms used here are defined
in . The definition of the
ABNF token "domain-name" can also be found
there. A report
generator is an entitiy that generates
and sends reports. For the scope of
this memo, the term refers to
Verifiers, as defined in Section 2.2
of , designed
also to generate authentication
failure reports according to this
specification. A domain name owner employing for
email signing and authentication might want to know when
signatures in use by specific keys are not successfully
verifying. Currently there is no such mechanism
defined. This document adds optional "tags" (as defined in
) to the DKIM-Signature header field
and the DKIM key record in the DNS, using the formats
defined in that specification. The following tag is added to DKIM-Signature header
fields when a Signer wishes to request that
reports of failed verifications be generated
by a Verifier:
Reporting Requested
(plain-text; OPTIONAL; no default). If
present, this tag indicates that the Signer
requests that Verifiers generate a report
when verification of the DKIM signature
fails. At present, the only legal value
is the single character "y" (in either upper
or lower case). A complete description and
illustration of how this is applied can be
found in . ABNF:
When a Signer wishes to advertise that it wants
to receive failed verification reports, it also
places in the DNS a TXT resource record (RR)
whose content follows the same general syntax as
DKIM key records, as defined in Section 3.6.1 of
, in that it is made up of
a sequence of tag-value objects. In this case,
the tags and values comprise the parameters to
be used when generating the reports. A report
generator will request the content of this record
when it sees an "r=" tag in a DKIM-Signature
header field. The reassembly rules of Section 3.6.2.2 of
also apply here if the
reporting TXT record consists of several string
fragments. Any tag found in the content of this record that
is not registered with IANA as described in
MUST be
ignored. The initial list of tags supported for the
reporting TXT record is as follows:
Reporting Address
(plain-text; OPTIONAL). A
dkim-quoted-printable string (see Section
2.11 of ) containing the
local-part of an email address to which a
report SHOULD be sent when mail fails
DKIM verification for one of the reasons
enumerated below. The value MUST be
interpreted as a local-part only. To
construct the actual address to which the
report is sent, the Verifier simply appends to
this value an "@" followed by the domain
name found in the "d=" tag of the
DKIM-Signature header field. Therefore, an
ADMD making use of this specification MUST
ensure that an email address thus constructed
can receive reports generated as described in
. ABNF:
Requested Report Percentage
(plain-text; OPTIONAL; default is "100"). The
value is an integer from 0 to 100
inclusive that indicates what percentage of
incidents of signature authentication failures,
selected at random, are to cause reports to be
generated. The report generator SHOULD NOT
issue reports for more than the requested
percentage of incidents. Report generators
MAY make use of the "Incidents:" field in
to indicate that there
are more reportable incidents than there are
reports. ABNF:
Requested Reports
(plain-text; OPTIONAL; default is "all"). The
value MUST be a colon-separated list of tokens
representing those conditions under which a
report is desired. See
for a list of
valid tags. ABNF:
Requested SMTP Error String
(text; OPTIONAL; no default). The value is a
dkim-quoted-printable string that the
publishing ADMD requests be included in
error strings if
messages are rejected during the delivery SMTP
session. ABNF:
In the absence of an "ra=" tag, the "rp=" and
"rr=" tags MUST be ignored, and the report
generator MUST NOT issue a report. Report generators MUST apply the following
algorithm, or one semantically equivalent to
it, for each DKIM-Signature header field
whose verification fails for some reason.
Note that this processing is done as a reporting
extension only; the outcome of the specified DKIM
evaluation MUST be otherwise unaffected.
If the DKIM-Signature field did not
contain a valid "r=" tag, terminate. Issue a TXT query to
the name that results from appending
the value of the "d=" tag in the
DKIM-Signature field to the string
"_report._domainkey.". For example, if the
DKIM-Signature header field contains
"d=example.com", issue a DNS TXT query to
"_report._domainkey.example.com". If the DNS query returns anything other
than a success status code (0), also
known as NOERROR, or if multiple TXT
records are returned, terminate. If the resultant TXT is in several
string fragments, reassemble it as
described in Section 3.6.2.2 of
. If the TXT content is syntactically
invalid, the implementation,
terminate. If the reason for the signature evaluation
failure does not match one of the report
requests found in the "rr=" tag (or its
default value), terminate. If a report percentage ("rp=") tag was
present, select a random number between
0 and 99, inclusive; if the selected number
is higher than the tag's value,
terminate. If no "ra=" tag was present, skip this step
and the next one. Otherwise, determine
the reporting address by extracting the
value of the "ra=" tag and appending to
it "@" followed by the domain name found
in the "d=" tag of the DKIM-Signature
header field. Construct and send a report in compliance
with of this
memo that includes as its intended
recipient the address constructed in the
previous step. If the session
during which the DKIM signautre was
evaluated is still active and the SMTP
server has not already given its response
to the DATA command that relayed the
message, and an "rs=" tag was present
in the TXT record, the SMTP server SHOULD
include the decoded string found in the
"rs=" tag in its SMTP reply to the DATA
command. This algorithm has the following advantages over
previous implementations:
If the DKIM signature fails to verify,
no additional DNS check is made to see
if reporting is requested; the request
is active in that it is included in the
DKIM-Signature header field. (Previous
implementations included the reporting
address in the DKIM key record, which is
not queried for certain failure cases.
This meant, for full reporting, that the
key record had to be retrieved even when
it was not otherwise necessary.) The request is confirmed by the presence
of a corresponding TXT record in the DNS,
since the Signer thus provides the
parameters required to construct and send
the report. This means a malicious
Signer cannot falsely assert that someone
else wants failure reports and cause
unwanted mail to be generated. It can
cause additional DNS traffic against the
domain listed in the "d=" signature tag,
but negative caching of the requested DNS
record will help to mitigate this
issue. It is not possible for a Signer to direct
reports to an email address outside of its
own domain, preventing distributed
email-based denial-of-service attacks. The above procedure does not permit the detection
and reporting of messages including a fraudulent
DKIM-Signature header field, where such signature
did not include an "r=" tag. It might be useful
to some Signers to receive such reports, but this
use case is not supported. To support this, a
Verifier would have to violate the first
step above and continue even in the absence of
an "r=" tag. Although this satisfies this
reporting requirement (which is expected to be
unusual), it also creates a possible
denial-of-service attack as such Verifiers will
always look for the reporting TXT record, so
the generator of fraudulent messages could simply
send a large volume of such messages to a
number of destinations. Thus, the specified
algorithm does not accommodate this case. There also exist cases in which a domain name owner
employing
for announcing signing practises with DKIM
may want to know when messages are received without
valid author domain signatures. Currently there is no
such mechanism defined. This document adds the following optional "tags"
(as defined in ) to the DKIM ADSP
records, using the form defined in that specification:
Reporting Address (plain-text;
OPTIONAL; no default). The value MUST be a
dkim-quoted-printable string containing the local-part
of an email address to which a report SHOULD be sent
when mail claiming to be from this domain failed
the verification algorithm described in
, in particular because a message
arrived without a signature that validates,
which contradicts what the ADSP record claims. The
value MUST be interpreted as a local-part only. To
construct the actual address to which the report is
sent, the Verifier simply appends to this value an
"@" followed by the domain whose policy was queried
in order to evaluate the sender's ADSP, i.e., the
one taken from the RFC5322.From domain of the message
under evaluation. Therefore, a signer making
use of this extension tag MUST ensure that an
email address thus constructed can receive reports
generated as described in .
ABNF:
Requested Report Percentage
(plain-text; OPTIONAL; default is "100"). The value
is a single integer from 0 to 100 inclusive that
indicates what percentage of incidents of ADSP
evaluation failures, selected at random, should
cause reports to be generated. The report generator
SHOULD NOT issue reports for more than the requested
percentage of incidents. Report generators MAY make
use of the "Incidents:" field in
to indicate that there are more reportable incidents
than there are reports. ABNF:
Requested Reports (plain-text;
OPTIONAL; default is "all"). The value MUST be a
colon-separated list of tokens representing those
conditions under which a report is desired.
See for a list of
valid tags. ABNF:
Requested SMTP Error String
(plain-text; OPTIONAL; no default). The value
is a string the signing domain requests be included
in error strings when messages
are rejected during a single SMTP session. ABNF:
In the absence of an "ra=" tag, the "rp=" and "rr=" tags
MUST be ignored, and the report generator MUST NOT issue
a report. This memo also includes, as the "ro" tags defined
above, the means by which the signer can request
reports for specific circumstances of interest. Verifiers
MUST NOT generate reports for incidents that do not
match a requested report, and MUST ignore requests for
reports not included in this list. The following report requests are defined
for DKIM keys:
All reports are
requested. Reports are requested for
signature evaluation errors that
resulted from DNS issues (e.g.,
key retrieval problems). Reports are requested for
any reason related to DKIM signature
evaluation not covered by other
report requests listed here. Reports are requested for
signatures that are rejected for
local policy reasons at the
Verifier that are related to DKIM
signature evaluation. Reports are requested for
signature or key syntax errors. Reports are requested for
signature verification failures or
body hash mismatches. Reports are requested for
signatures rejected by the Verifier
because the expiration time has
passed. The following report requests are defined
for ADSP records:
All reports are
requested. Reports are requested for
messages that could not have
evaluated due
to DNS (policy retrieval) issues. Reports are requested for
any -related
failure reason not covered by other
report requests listed here. Reports are requested for
messages that are rejected for
local policy reasons at the Verifier
that are related to
. Reports are requested for
messages that have a valid
signature but
do not match the published
policy. Reports are requested for
messages that have no valid
signature and
do not match the published
policy. This section describes the process for generating and
sending reports in accordance with the request of the
signer and/or sender as described above. All reports generated as a result of requests
contained in these extension parameters MUST be
generated in compliance with
and its extension specific to this work,
. Additional guidance about the generation of these
reports can be found in
, especially
Section 9. As required by ,
this section contains registry information for the new
signature tags, and the new
tags. It also creates a DKIM
reporting tag registry. IANA is requested to update the DKIM Signature Tag
Specification Registry to include the following new
items: IANA is requested to update the DKIM ADSP
Specification Tag Registry to include the
following new items: IANA is requested to create a sub-registry of the
DKIM Parameters registry called "DKIM Reporting
Tags". Additions to this registry follow the
"Specification Required" rules, with the following
columns required for all registrations:
The name of the tag being
used in reporting records The document that
specifies the tag being defined The status of the tag's
current use, either "active" indicating
active use, or "historic" indicating
discontinued or deprecated use The initial registry entries are as follows:
Security issues with respect to these reports
are similar to those found in . Implementers are advised to consider the
Security Considerations sections of
,
,
, and
.
Many security issues related to this draft are
already covered in those documents. Some threats caused by deliberate misuse of this
mechanism are discussed in
. DKIM Sender Signing Practises
Sendmail, Inc.
Yahoo! Inc.
Cisco Systems, Inc.
Taughannock Networks
An Extensible Format for Email
Feedback Reports
SolidMatrix Technologies, Inc.
Domain Assurance Council
Cloudmark, Inc.
DomainKeys Identified Mail (DKIM)
Signatures
Brandenburg InternetWorking
AT&T Laboratories
Cloudmark
Domain names - implementation and
specification
USC/ISI
4676 Admiralty
Way
Marina del Rey
CA90291US+1 213 822 1511Internet Mail ArchitectureCreation and Use of Email Feedback
Reports: An Applicability Statement for
the Abuse Reporting Format (ARF)
Return Path
Cloudmark
Authentication Failure Reporting using
the Abuse Report Format Guidelines for Writing an IANA
Considerations Section in RFCs
Google
IBM
Key words for use in RFCs to Indicate
Requirement Levels
Harvard University
Multipurpose Internet Mail
Extensions (MIME) Part One: Format of
Internet Message Bodies Simple Mail Transfer Protocol An Extensible Message Format for
Delivery Status Notifications
University of Tennessee
Lucent Technologies
The authors wish to acknowledge the following for their
review and constructive criticism of this proposal:
Steve Atkins,
Monica Chew,
Dave Crocker,
Tim Draegen,
Frank Ellermann,
JD Falk,
John Levine,
and
Scott Kitterman. This section contains examples of the use of each of the
extensions defined by this memo. This example DKIM-Signature field contains the
"r=" tag that indicates reports are requested
on verification failure. If this signature fails to verify, a TXT query
will be sent to "_report._domainkey.example.com"
to retrieve a reporting address and other report
parameters. This example, continuing from the previous one,
shows a message that might be found at
"_report._domainkey.example.com" in a TXT record.
It makes the following requests:
Reports about signature evaluation failures
should be send to the address
"dkim-errors" at the signer's domain; All (100%) incidents should be
reported; Only reports about signature verification
failures and expired signatures should
be generated. This example ADSP record makes the following
assertions:
The sending domain (i.e. the one that is
advertising this policy) signs all mail
it sends; Reports about ADSP evaluation failures
should be send to the address
"dkim-adsp-errors" at the Author's
domain; Only reports about unsigned messages
should be generated.