Document: draft-ietf-marf-dkim-reporting-15
Title: Extensions to DKIM for Failure Reporting
Reviewer: Aaron Stone
Review Date: 3/15/2012
IESG Telechat Date: 3/15/2012

Summary: This draft is generally in good shape; the major issues here
should be easy to resolve.
I hope the minor issues notes are helpful and not too pedantic.

=== Major Issues:

Should the well-known domain components "_report._domainkey" be
registered with IANA?
(Hmm, I don't see any such registry. In that case, there is an edit
below suggesting text to more clearly state a MUST around this domain
record name.)


Please add a note about DKIM selectors. The name "_report._domainkey" is in the
same namespace as RFC 6376, Section 3.1 Selectors, which take the form,
"yourselector._domainkey". This effectively states that a domain implementing
both strategies MUST NOT use "_report" as a selector, because of this
requirement of the algorithm described in Section 3.3:

   3.   If the DNS query returns anything other than RCODE 0 (NOERROR),
        or if multiple TXT records are returned, terminate.


=== Minor Issues:

Introduction:

UPDATED
   DomainKeys Identified Mail [DKIM] introduced a mechanism for message
   signing and authentication.  It uses digital signing to associate a
   domain name with a message in a reliable manner.
   The verified domain name can then be evaluated before
   the message is delivered, e.g., checking advertised sender
   policy, comparing to a known-good sender list, submitting to a reputation
   service, and so on.

   A message sender employing [DKIM] may want to know when and why
   messages received by others fail verification. This applies equally to
   verification failures in a message containing DKIM headers, as well as
   published signing practices (e.g., Author Domain Signing
   Practices, [ADSP]) in an Administrative Management Domain
   (ADMD; see [EMAIL-ARCH]).

   This document extends [DKIM] and [ADSP] to add an optional reporting
   address and some reporting parameters.  Reports are generated using
   the format defined in [I-D.IETF-MARF-AUTHFAILURE-REPORT].

Sections 2.2 and 2.3 - switch the order, so that it goes: Keywords,
Notation, Imported Definitions, Other Definitions.

Section 2.4 - report generator has an awkward use of "also". Remove
the world "also":

OLD
    ... also designed to ...
NEW
   ... designed to ...

Section 3:

OLD
   A domain name owner employing [DKIM] for email signing and
   authentication might want to know when signatures in use by that ought to be
   verifiable with specific public keys are not successfully verifying.
   Currently there is no such mechanism defined.

   This document adds optional "tags" (as defined in [DKIM]) to the
   DKIM-Signature header field and the DKIM key record in the DNS, using
   the formats defined in that specification.
NEW
   A domain name owner employing [DKIM] for email signing and
   authentication might want to know when message recipients are unable
   to verify a message due to problems in the keys published for a domain.
   Currently there is no such mechanism defined.

   This section adds optional tags to the DKIM-Signature header field
   and the DKIM key record in the DNS, using the formats defined in [DKIM].

Section 3.1: mismatch between prose and ABNF. Prose says "upper or
lower case", ABNF is lower-case only. Edit the prose to match the
ABNF:

OLD
    At present, the only legal value is the single character "y"
    (in either upper or lower case).

NEW
    At present, the only legal value is the single character "y".


Section 3.2: I'm confused by the following paragraph, and took a while to
understand which DNS record would be used. I suggest this edit:

OLD
   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).  The RR is made up of a sequence of tag-value objects (much
   like DKIM key records, as defined in Section 3.6.1 of [DKIM]), but it
   is entirely independent of those key records and is found at a
   different name.  In the case of a record advertising the desire for
   authentication failure reports, 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.
NEW
   When a Signer wants to receive reports of failed DKIM verifications,
   it adds a TXT resource record (RR) in the DNS, advertising how to
   notify the Signer of such failures.  The RR contains a sequence of
   tag-value objects in a similar format as DKIM key records, specifying
   parameters to be used when generating failure reports.

   The TXT record containing failure reporting information MUST be
   "_report._domainkey" within the relevant DNS domains.  A report
   generator will request the contents of this record when it sees an
   "r=" tag in a DKIM-Signature header field.


Section 3.2: Confusing use of "tags" and "tokens". Edited to use "tokens".
HOWEVER - maybe the word "values" would be better?

OLD
   rr=  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 Section 5.1 for a
      list of valid tags.
NEW
   rr=  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 Section 5.1 for a
      list of valid tokens.


Section 3.2: Use of dkim-quoted-printable in prose, but qp-section in ABNF.
Please edit this as apprpriate.

ERR
   rs=  Requested SMTP Error String (text; OPTIONAL; no default).  The
      value is a dkim-quoted-printable string that the publishing ADMD
                 ^^^^^^^^^^^^^^^^^^^^^
      requests be included in [SMTP] error strings if messages are
      rejected during the delivery SMTP session.  ABNF:

       rep-rs-tag = %x72.73 *WSP "=" qp-section
                                     ^^^^^^^^^^
                  ; "rs=..." (lower-case only for the tag name)


Section 4: Confusing language, similar edits as intro to Section 3:

OLD
   There also exist cases in which a domain name owner employing [ADSP]
   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
   [ADSP]) to the DKIM ADSP records, using the form defined in that
   specification:
NEW
   A domain name owner employing Author Domain Signing Practices [ADSP]
   may also want to know when message recipients are unable to verify
   a message due to errors in the ADSP records.
   Currently there is no such mechanism defined.

   This section adds optional tags to the DKIM ADSP records,
   using the formats defined in [ADSP].
(and [DKIM] ?)

Section 4: Run-on sentence, and dkim-quoted-printable vs. qp-section again.

OLD
   ra=  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 [ADSP], in particular because a message arrived
      without a signature that validates, which contradicts what the
      ADSP record claims.
NEW
   ra=  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 [ADSP].

ERR
       adsp-ra-tag = %x72.61 *WSP "=" qp-section
                                      ^^^^^^^^^^
                   ; "ra=..." (lower-case only for the tag name)

Section 4: remove this sentence, it's not particularly useful?

      ... An exception to this
      might be some out-of-band arrangement between two parties to
      override it with some mutually agreed value. ...

Section 4: tokens vs. tags again. "value" might still be a better word?

OLD
   rr=  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 Section 5.2 for a
      list of valid tags.  ABNF:
NEW
   rr=  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 Section 5.2 for a
      list of valid tokens.  ABNF:


Section 5: remove extra sentence

OLD
   This memo also includes, as the "ro" "rr" 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.
NEW
   The "ro" and "rr" tags allow a Signer to specify the types of errors it
   is interested in receiving reports about. This section defines
   the error types and corresponding token values.

   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.


Section 8.3: missing context clues

OLD
   Some threats caused by deliberate misuse of this mechanism are
   discussed in Section 3.3, but they warrant further discussion here.
NEW
   Some threats caused by deliberate misuse of this error reporting
   mechanism are discussed in Section 3.3, but they warrant further
   discussion here.

Paragraph out of order; this paragraph:
   Negative caching offers some protection against this pattern of
   abuse, although it will work only as long as the negative time-to-
   live on the relevant SOA record in the DNS.

Please move it to just above the paragraph about positive caching, as well
as making some small changes below:

OLD
   Implementers are therefore strongly advised not to advertise that DNS
   record except when reports desired, including the risk of receiving
   this kind of attack.

   Positive caching of this DNS reply also means turning off the flow of
   reports by removing the record is not likely to have immediate
   effect.  A low time-to-live on the record needs to be considered.
NEW
   Domain owners are therefore strongly advised not to advertise the DNS
   records specified in this document except when failure reports are desired.
   Domain owners ought to be prepared to receive unexpected traffic and attacks.

   Negative caching offers some protection against this pattern of
   abuse, although it will work only as long as the negative time-to-
   live on the relevant SOA record in the DNS.

   Positive caching of DNS records also means turning off the flow of
   reports by removing the record is not likely to have immediate
   effect.  A low time-to-live on the record needs to be considered.


=== Nits: [list editorial issues such as typographical errors,
preferably by section number]

Section 3.2: typo at the very last sentence:
OLD
   See Section 8.4 for some considerations regardin limitations of
this mechanism.
NEW
   See Section 8.4 for some considerations regarding limitations of
this mechanism.

Remove the quotes around "tags" -- tags appears as a bare word in [DKIM], so
it's safe to use here, too.

Choose either "document" or "memo" to refer to this document / memo throughout.


END