]> Fastmail Pty Ltd

Level 2, 114 William Street 3000 Australia +61 457 416 436 brong@fastmailteam.com

Internet-Draft DomainKeys Identified Mail Signatures v2 (DKIM2) produces a verification result for an email message. This document defines how that result is reported in the Authentication-Results header field, registering the "dkim2" authentication method, the result values it can take, and two properties which identify the signing domain and the point in the chain at which verification failed. Diagnostic detail about each hop is carried in a human-readable comment.

Introduction DKIM2 () associates a domain with an email message, and provides a chain of signatures which documents each system that handled the message. Verification of that chain produces a single result for the message as a whole. The Authentication-Results header field () is the standard means by which an Administrative Management Domain (ADMD) records the outcome of message authentication for the benefit of other elements within that same ADMD. anticipates this: it defines its verification outcomes as four states chosen "for compatibility with the Authentication-Results header field", and it defines a set of human-readable strings which a Verifier is directed to use when describing a failure. It leaves to this document how any of this is expressed in an Authentication-Results header field, and the registration of anything with IANA. This document supplies that. It registers the "dkim2" authentication method and its result values, and defines two properties. It deliberately does not attempt to make the whole of a DKIM2 verification machine-readable. The result value is machine-readable, because software acts on it; the per-hop detail is reported in a comment, because its audience is a human being diagnosing a problem. This follows the approach taken by ARC (), which registered two properties and carried its per-instance detail in a comment. This document defines no new header field and no new ptype.

Terminology and conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . These words take their normative meanings only when they are presented in ALL UPPERCASE. Basic email terminology is taken from . The terms Signer, Verifier, Originator, Signing Domain and Chain of Custody are used as defined in . Syntax descriptions use Augmented BNF (ABNF) . The tokens "FWS", "comment", "ctext" and "quoted-pair" are imported from ; the token "Domain" is imported from ; the tokens "ptype", "property" and "resinfo" are imported from . For clarity this document refers to DKIM () as DKIM1.

The dkim2 Authentication Method A Verifier which has attempted DKIM2 verification of a message reports the outcome using the authentication method name "dkim2". A single Authentication-Results header field SHOULD contain at most one "resinfo" for the "dkim2" method. Unlike DKIM1, where each signature authenticates an identity independently and so warrants its own result, a DKIM2 verification produces one result for the message as a whole: the Chain of Custody either holds or it does not.

Result values The four output states defined in map onto result values as follows: DKIM2 output state Result value PASS pass FAIL fail PERMERROR permerror TEMPERROR temperror This document additionally defines the result value:

none:

The message contained no DKIM2 header fields: neither a Message-Instance nor a DKIM2-Signature header field.

reports such a message as a PERMERROR, with the human-readable string "PERMERROR: No DKIM2 header fields found". In an Authentication-Results header field it is instead reported as "none", which serves the same purpose as "none" does for DKIM1 and for ARC, and allows a consumer to distinguish a message which was checked and carried nothing to check from a message which was never checked at all. A message which carries some DKIM2 header fields but not others is not reported as "none". A Verifier which attempts DKIM2 verification SHOULD report "dkim2=none" rather than omitting the method, so that this distinction is available. Note that this is distinct from the "no-result" production of , which records that no authentication of any kind was performed on the message. No other result values are defined. In particular a DKIM2 verification does not produce "neutral" or "policy" results.

Properties Two properties are defined, both with the "header" ptype. Both are OPTIONAL, and each MUST be omitted when its value cannot be determined.

header.d The value of the "d=" tag of the DKIM2-Signature header field whose "i=" tag has the value 1: that is, the Signing Domain of the Originator of the message. This is the identity to which a receiving system would ordinarily attach reputation, and is the direct analogue of the "header.d" property reported for DKIM1. The Signing Domain of the highest-numbered DKIM2-Signature header field is deliberately not reported, because requires it to match the SMTP transaction in which the message was received, and it is therefore already available to the receiving system by other means. This property MUST be omitted if no DKIM2-Signature header field with "i=1" is present, or if such a field is present but sufficiently malformed that no "d=" value can be extracted from it. A Verifier MAY report "header.d" alongside any result value, and doing so assists diagnosis. However, the domain is an authenticated identity only when the reported result is "pass". Consumers MUST NOT use "header.d" as an input to reputation or message disposition decisions unless the reported result is "pass".

header.i The value of the "i=" tag of the DKIM2-Signature header field to which the reported failure is attributed. This property MUST be omitted when the result is "pass" or "none". It MUST also be omitted where the reported failure cannot be attributed to any one signature. Where a Verifier has ceased verifying once the outcome was known, as permits, the value reported is that of the signature at which it stopped. Some of the failures defined in are reported against a Message-Instance header field, identified by its "m=" tag, rather than against a DKIM2-Signature header field. For these, the value reported is the "i=" tag value of the DKIM2-Signature header field whose "m=" tag references that Message-Instance. A Verifier which cannot make that association MUST omit this property. Implementers should note that the property name "header.i" is also registered for the "dkim" method, where it carries an entirely different value: the Agent or User Identifier of a DKIM1 signature, such as "@example.com". The two registrations are distinguished by their method, and a Verifier which reports both methods for the same message will emit both spellings in the same header field. This is permitted, and follows the convention of naming the property after the tag it reports, but it is a plausible source of confusion when such a header field is read by eye.

The explanatory comment Per-hop detail is reported in a comment () placed within the "resinfo" for the "dkim2" method. permits a comment wherever CFWS is permitted, which includes the position immediately following the result value. A comment is not part of the "resinfo" grammar, and a conforming parser is free to discard it. The information carried in the comment is therefore advisory, intended for a human being diagnosing a delivery problem. Consumers MUST NOT depend on its presence, and MUST NOT rely on its internal structure. Implementers requiring a machine-readable signal MUST use the result value and the properties defined in . When the reported result is anything other than "pass" or "none", the comment SHOULD include, verbatim, the relevant human-readable string defined in , with its "<x>", "<y>", "<value>", "<s1>" and "<s2>" placeholders substituted as that document directs. already instructs Verifiers to use those strings so as to give senders the maximum possible assistance; reproducing the string here places it where a recipient-side diagnosis will find it.

Recommended form The following form is RECOMMENDED. It is given so that comments produced by different implementations resemble one another, not so that they may be parsed:

The "hop-list" reports one item per DKIM2-Signature header field, in ascending order of "i=", giving the Signing Domain and the outcome for that signature. The "diagnostic", where present, carries the human-readable string from . The "skipped" outcome records a signature which was not verified, either because the Verifier ceased verifying upon detecting a failure or because it was unable to check that signature. does not specify the order in which signatures are checked, so which signatures are reported as skipped depends on the Verifier.

Escaping Several of the values substituted into the human-readable strings of originate in the message under evaluation, and are therefore under the control of whoever composed or handled it. These include Selector values, domain names, MAIL FROM and RCPT TO values, and the text of invalid Recipe steps. The "ctext" production of excludes the characters "(" (%x28), ")" (%x29) and "\" (%x5C), and comments nest. A value containing any of those characters, emitted without escaping, will either terminate the comment early or leave it unterminated, in either case corrupting the remainder of the header field. A Verifier MUST therefore escape those three characters as "quoted-pair" () wherever they occur in a substituted value. A Verifier SHOULD additionally impose an implementation-defined limit on the length of any substituted value.

Verifier behaviour

Reporting A Verifier adds its result to an Authentication-Results header field as described in . ignores Authentication-Results header fields when calculating header hash values, so adding one does not count as a modification to the message for DKIM2 purposes.

Trust boundary An Authentication-Results header field is meaningful only within the ADMD which added it, and requires that an ADMD remove untrusted instances of the field on ingress. That requirement applies to "dkim2" results exactly as it does to any other method. This bears emphasis for DKIM2 specifically. excludes Authentication-Results from the set of header fields it signs, and does so deliberately, because those fields are added after verification has occurred and are commonly stripped as a message crosses a trust boundary. A "dkim2" result therefore carries no cryptographic protection whatsoever, notwithstanding that the mechanism it reports on is cryptographic. An ADMD MUST NOT infer any trustworthiness for a "dkim2" result from the nature of DKIM2 itself.

Results do not transfer A "dkim2=pass" records that the Chain of Custody verified as far as the reporting Verifier, in the SMTP transaction in which that Verifier received the message. It says nothing about any subsequent hop: binds the highest-numbered DKIM2-Signature header field to the MAIL FROM and RCPT TO of a particular transaction, so a verification performed by one system is not evidence for the next. A system which forwards a message MUST NOT copy a "dkim2" result forward for the benefit of a downstream system. A forwarder wishing to make its own handling verifiable adds a DKIM2-Signature header field of its own, as describes.

Examples In these examples, line breaks and indentation within the header field are for readability and follow the folding rules of . A message signed only by its Originator, verifying correctly:

A message which passed through a mailing list, verifying correctly:

A four-hop message whose third signature does not verify. The Verifier worked downwards from the most recently applied signature and ceased verifying at the failure, so the first and second signatures are reported as skipped. Note that "header.d" is still reported even though the "i=1" signature was never checked, and so is not an authenticated identity here:

A message for which a public key could not be retrieved:

A message carrying no DKIM2 header fields at all:

A Chain of Custody failure in which the substituted MAIL FROM value contains parentheses, and has been escaped as requires:

did not match) header.d=sender.example.com header.i=2 ]]>

A message reported on by several methods at once. Note that "header.i" appears twice with different meanings, as discussed in : for "dkim" it is the DKIM1 signature's Agent or User Identifier, and for "dkim2" it is a sequence number:

IANA considerations

Email Authentication Methods registry IANA is requested to add the following entries to the "Email Authentication Methods" registry: Method Definition ptype Property Value Status Version dkim2 this document, header d The "d=" tag value of the DKIM2-Signature header field with "i=1" active 1 dkim2 this document, header i The "i=" tag value of the DKIM2-Signature header field to which a reported failure is attributed active 1 No new ptype is required; both properties use the existing "header" ptype.

Email Authentication Result Names registry IANA is requested to add the following entries to the "Email Authentication Result Names" registry: Auth Method Code Specification Status dkim2 none this document, active dkim2 pass this document, active dkim2 fail this document, active dkim2 permerror this document, active dkim2 temperror this document, active

Security considerations The security considerations of apply in full. Those below are additional, or bear repeating in the DKIM2 context.

No cryptographic protection As set out in , a "dkim2" result in an Authentication-Results header field is unsigned and unprotected, even though DKIM2 itself is a cryptographic mechanism. An Authentication-Results header field can be added, altered or removed by any system which handles the message, and DKIM2 will not detect that this has occurred, because it does not sign the field. An ADMD which acts on "dkim2" results without removing untrusted instances of the field on ingress can be induced to accept an attacker-supplied verdict for an arbitrary message. The mitigation is the ingress requirement of , and it is not optional.

A pass is not an assurance about content states explicitly that its output states report whether a message traveled to its destination without undeclared modifications and along a delivery path consistent with that specification, and that they do not attest in any way as to whether the message will be of value to the recipient or whether any declared modifications were benign. A "dkim2=pass" therefore means that the Chain of Custody held. It does not mean the message is wanted, truthful, or safe, and it does not mean that the changes made by intermediaries in the chain were harmless. Consumers which treat "pass" as a proxy for any of those properties will be wrong, and can be made wrong deliberately by an attacker who constructs a correctly signed chain.

Attacker-influenced comment content The comment described in reproduces values taken from the message under evaluation, and those values are chosen by whoever composed or handled that message. requires that the characters which are significant to the comment syntax be escaped. A Verifier which does not do so can be made to emit a malformed header field, and in the worst case to terminate its comment early and have attacker-chosen text parsed as further "resinfo" content, forging results for other methods within the ADMD's own trusted header field. Bounding the length of substituted values, as also recommends, limits the related denial-of-service risk of an attacker inflating the header field. Software which renders these comments to a user should treat their content as untrusted text, and in particular should not interpret it as markup.

Information disclosure The comment described in may reveal the Signing Domains of every system which handled a message, and the human-readable strings of may include MAIL FROM and RCPT TO values. Where a message was forwarded, this can disclose the existence and identity of forwarding relationships, and RCPT TO values can disclose recipient addresses. This is not a new exposure, since the information is present in the DKIM2-Signature header fields themselves, and an Authentication-Results header field is in any case intended to remain within the ADMD which added it. It is nonetheless a further reason to remove these fields at trust boundaries, in both directions.

In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This document is a specification of the basic protocol for Internet electronic mail transport. It consolidates, updates, and clarifies several previous documents, making all or parts of most of them obsolete. It covers the SMTP extension mechanisms and best practices for the contemporary Internet, but does not provide details about particular extensions. Although SMTP was designed as a mail transport and delivery protocol, this specification also contains information that is important to its use as a "mail submission" protocol for "split-UA" (User Agent) mail reading systems and mobile environments. [STANDARDS-TRACK] This document specifies the Internet Message Format (IMF), a syntax for text messages that are sent between computer users, within the framework of "electronic mail" messages. This specification is a revision of Request For Comments (RFC) 2822, which itself superseded Request For Comments (RFC) 822, "Standard for the Format of ARPA Internet Text Messages", updating it to reflect current practice and incorporating incremental changes that were specified in other RFCs. [STANDARDS-TRACK] This document specifies a message header field called "Authentication-Results" for use with electronic mail messages to indicate the results of message authentication efforts. Any receiver-side software, such as mail filters or Mail User Agents (MUAs), can use this header field to relay that information in a convenient and meaningful way to users or to make sorting and filtering decisions. This document obsoletes RFC 7601. Yahoo Google Fastmail Pty Ltd DomainKeys Identified Mail v2 (DKIM2) permits a person, role, or organization that owns a signing domain to document that it has handled an email message by associating their domain with the message. This is achieved by providing a hash value that has been calculated on the current contents of the message and then applying a cryptographic signature that covers the hash values and other details about the transmission of the message. Verification is performed by querying an entry within the signing domain's DNS space to retrieve an appropriate public key. As a message is transferred from author to recipient, systems that alter the body or header fields will provide details of their changes and calculate new hash values. Further signatures will be added to provide a "chain" that receivers can validate. This permits verifiers to identify the nature of changes made by intermediaries and apply a reputation to the systems that made changes. DKIM2 also allows recipients to detect when messages have been unexpectedly "replayed" and will ensure that Delivery Status Notifications are only sent to entities that were involved in the transmission of a message. Over its thirty-five-year history, Internet Mail has changed significantly in scale and complexity, as it has become a global infrastructure service. These changes have been evolutionary, rather than revolutionary, reflecting a strong desire to preserve both its installed base and its usefulness. To collaborate productively on this large and complex system, all participants need to work from a common view of it and use a common language to describe its components and the interactions among them. But the many differences in perspective currently make it difficult to know exactly what another participant means. To serve as the necessary common frame of reference, this document describes the enhanced Internet Mail architecture, reflecting the current service. This memo provides information for the Internet community. DomainKeys Identified Mail (DKIM) permits a person, role, or organization that owns the signing domain to claim some responsibility for a message by associating the domain with the message. This can be an author's organization, an operational relay, or one of their agents. DKIM separates the question of the identity of the Signer of the message from the purported author of the message. Assertion of responsibility is validated through a cryptographic signature and by querying the Signer's domain directly to retrieve the appropriate public key. Message transit from author to recipient is through relays that typically make no substantive change to the message content and thus preserve the DKIM signature. This memo obsoletes RFC 4871 and RFC 5672. [STANDARDS-TRACK] The Authenticated Received Chain (ARC) protocol provides an authenticated "chain of custody" for a message, allowing each entity that handles the message to see what entities handled it before and what the message's authentication assessment was at each step in the handling. ARC allows Internet Mail Handlers to attach assertions of message authentication assessment to individual messages. As messages traverse ARC-enabled Internet Mail Handlers, additional ARC assertions can be attached to messages to form ordered sets of ARC assertions that represent the authentication assessment at each step of the message-handling paths. ARC-enabled Internet Mail Handlers can process sets of ARC assertions to inform message disposition decisions, identify Internet Mail Handlers that might break existing authentication mechanisms, and convey original authentication assessments across trust boundaries.

Changes from Earlier Versions draft-gondwana-dkim2-authres-01 Aligned with draft-ietf-dkim-dkim2-spec-08. "none" now means no DKIM2 header fields at all, and is mapped to the PERMERROR that reports for that case. Removed the donotmodify, donotexplode and duplicate-message failures from "header.i", as no longer defines them, along with the duplicate-message example. Updated placeholder names and example strings to match , including MAIL FROM mismatch now being a FAIL. no longer specifies the order in which signatures are checked. draft-gondwana-dkim2-authres-00 Initial version.