]> Fastmail Pty Ltd

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

Internet-Draft Implementations of DomainKeys Identified Mail Signatures v2 (DKIM2) benefit from seeing extra debug information during the early deployment phase. This document is intended to help testers, and unlikely to be published.

Introduction DKIM2 () software generates Message-Instance and DKIM2-Signature header fields. Validators also create Authentication-Results headers that may include dkim2 status. During interoperability testing it is useful to have debug information in a consistent place, so testers can examine the headers and see what disagreement or misunderstanding may have caused failures. Several testing implementations already create a header field called X-DKIM2-Info. This document describes how to create it. Nothing in this document is normative, and does not depend on it.

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, Message-Instance, Recipe and Chain of Custody are used as defined in . Syntax descriptions use Augmented BNF (ABNF) . The token "CRLF" is imported from , and "tag-list" from the "Tag=Value Lists" section of . An "emitter" is any piece of software which adds an X-DKIM2-Info header field to a message. An "action" is the single step in DKIM2 processing which one such field records.

The "X-" name excludes from its header hash every header field whose name begins with "x-", so this field can be added at any point, by any system, without changing any Message-Instance header hash or invalidating any DKIM2-Signature.

No protocol meaning An X-DKIM2-Info header field is not a verification result. If the software is generating an Authentication-Results () data then the verification result goes there. The field is not signed, nor covered by any hash. It only records what the emitter says it did. Software MUST NOT make any decision about a message on the basis of an X-DKIM2-Info header field.

The X-DKIM2-Info header field

Syntax The value is a Tag=Value list, using exactly the syntax that defines for the Message-Instance and DKIM2-Signature header fields:

A tag value may contain "=", ",", "(", ")" and space. It MUST NOT contain ";", which separates tags. There is no quoting mechanism; an emitter MUST replace or remove ";" in any value it substitutes. Five tags are always present, in the order "draft", "repo", "date", "sw", "action", followed by any supplementary tags in alphabetical order. Tag names and values are case-sensitive, and tag names are lower case. Unknown tags MUST be ignored. A message may carry any number of X-DKIM2-Info fields, from any number of emitters.

Provenance tags These identify the software which emitted the field. They are the same in every field an emitter produces.

draft:

The revision the emitter implements, without the "draft-" prefix, for example "ietf-dkim-dkim2-spec-08".

repo:

Where the emitter's source code lives, as host and path with no scheme, for example "git.example.com/dkim2". For DKIM2 code embedded in larger software, this names the fork carrying it.

date:

The date the emitter's DKIM2 behaviour last changed, as YYYY-MM-DD. A version stamp for the code, not the date of the draft. Bump it on any change to what is emitted.

sw:

The program within "repo" which emitted the field, for example "inbound-filter".

The action tag

action:

What the emitter did at the point it added this field. One action per field; several actions mean several fields.

An action value is a short verb, optionally followed by "=" and a result, optionally followed by space-separated qualifiers:

The vocabulary is in .

Supplementary tags

hc:

The number of header fields in the header hash of the Message-Instance this field describes. Fields, not names: two "To" fields both hashed count two.

hn:

The names of those fields, lower case, in the order they were hashed (which defines as ascending octet order), comma-separated with no whitespace. A name appears once per field, so the list may contain duplicates; its length equals "hc", and it is empty when "hc" is 0.

snapf:

"Snapshot fetched": the identifier of the stored earlier copy of the message the emitter diffed against to compute a Recipe.

snaps:

"Snapshot stored": the identifier under which the emitter stored the message in its current state, for a later Recipe.

Snapshot identifiers are meaningful only to the emitter which wrote them; examples might be a database record id, or a path on disk.

Actions The actions any emitter may record, with their supplementary tags. An emitter MAY record other actions in the same form; a reader should not expect them from other software.

verify=<result> The emitter verified the message on receipt. The result is one of the four output states in lower case, or "none" if there were no DKIM2 header fields, as reported in Authentication-Results (), optionally followed by a free-text explanation in parentheses:

The authoritative result is in Authentication-Results (). No supplementary tags.

mi-m=<N> The emitter added a Message-Instance with "m=" N. Accompanied by "hc" and "hn"; where a snapshot store is used, also "snaps" and, for N above 1, "snapf". An emitter which found the topmost Message-Instance still matched, and added nothing, records no action.

sign d=<domain> a=<algorithm> The emitter added a DKIM2-Signature with that Signing Domain and algorithm. No supplementary tags.

not-signed=<reason> The emitter was asked to sign and declined. The reason is a short token chosen by the emitter, for example "broken-mi-chain" when the Message-Instance chain would not undo to "m=1". No supplementary tags.

Emitter behaviour One field per action. An emitter MUST NOT combine actions into one field, and MUST NOT modify or remove any X-DKIM2-Info field already present. The field goes at the top of the header block when the action is taken. Where the action added a header field, the emitter MUST add that field first and the X-DKIM2-Info after it, so the X-DKIM2-Info sits immediately above the field it describes. The value is folded. Folding MUST happen only after a ";", after a "," inside a list, or at a space inside a value. Whitespace next to ";" is not part of any value under ; in addition, a consumer MUST ignore whitespace next to ",". An emitter MUST NOT fold inside a token. The field is excluded from the header hash by the "x-" rule (). An emitter MUST NOT include it in anything it signs or hashes.

Reading the field The field is for a person reading a message which did not verify. Which software touched this, and to which draft? Compare "draft", "repo", "sw" and "date" across the fields. Why does the header hash of "m=2" not match? Compare the "hn" of the "mi-m=2" field with the names the Verifier hashed. Why did the Recipe not undo? Take "snapf" from the failing "mi-m=" field to the emitter's operator. Why was this not signed? Look for "not-signed", else for a "verify" that is not "pass".

Examples Line breaks and indentation follow folding. Domains, repositories and program names are examples. An inbound filter verified a message and, finding no Message-Instance, added "m=1":

The same message after a mailing list recorded its changes as "m=2":

An outbound filter then verified the chain and signed:

A Signer which declined because the Message-Instance chain would not undo:

Two implementations on different drafts:

IANA considerations None.

Security considerations The field is not signed or hashed. Anyone handling the message can add, alter or remove one undetected. Software MUST NOT act on it. The field discloses the software, draft revision and source repository of each system, something of an emitter's storage layout, and the names of header fields present at hashing time. An operator MAY strip X-DKIM2-Info at its outbound boundary; verification is unaffected. permits ";" in a header field name, so a name copied into "hn" verbatim could be read as further tags. An emitter SHOULD omit from "hn" any name containing a character outside %x21-3A / %x3C-7E, and SHOULD cap the length of "hn".

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 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] 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. Fastmail Pty Ltd 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.

Changes from Earlier Versions draft-gondwana-dkim2-debug-header-02 Reference the generic Tag=Value list syntax of draft-ietf-dkim-dkim2-spec-08, which makes the final ";" optional, in place of the "x-tag" rule it no longer defines. Permit folding at a space inside a value, as the examples already did. "verify=none" means no DKIM2 header fields, as in . Corrected the header hash order to ascending octet order. Examples updated to current draft revisions. draft-gondwana-dkim2-debug-header-01 Use the tag-list syntax, with every tag followed by ";", rather than defining a third tag-list variant. Renamed the mi-m<N> action to mi-m=<N> so every action with a value uses "=". draft-gondwana-dkim2-debug-header-00 Initial version.