]> Fastmail

brong@fastmailteam.com

Yahoo

rclayton@yahooinc.com

Google

weihaw@google.com

Internet-Draft This document describes the email header fields defined for DKIM2, and how they work togther to provide the required properties. This is an early draft, a work in progress.

Introduction To achieve the goals laid out in , this document describes the content of a 'DKIM2-Signature' header field, which can be added to messages. The 'DKIM2-Signature' header field contains signatures which can be verified using public keys from the DNS, in a similar way to how works. The 'DKIM2-Signature' header field also borrows design elements from , however it places strict requirements on the alignment of the components of header fields in the message with the reverse-path and forward-path.

Imported ABNF This document imports the following ABNF: mailbox and domain from Section 4.1.2. selector from Section 3.1. tag-list from Section 3.2. date-time from Section 5.6.

Defined ABNF We will copy (re-define) at least: instance and position from Section 3.9.

Definitions "DKIM2 Header". Any header field with the name 'DKIM2-Signature'. "Historical DKIM2 Header". Any DKIM2 Header where there exists another DKIM2 Header with a higher position on the message. "Active DKIM2 Header". Any DKIM2 Header where there is no DKIM2 Header with a higher position on the message. "Initial Timestamp". The timestamp on the DKIM2 Header in position 1.

The DKIM2 Header The DKIM2 Header draws significant amounts of design from . Headers are a structured tag-list as defined in Section 3.2. Field identifier Type Explanation i= position Sequence Number (from 1 to N) t= date-time Timestamp () f= dkim2-flags Indicates if feedback is requested, or that changes are not allowed d= domain Signing domain a= TBD Crypto algorithm(s) used (unless combined with b= to allow for multiple signatures on the same email, see discussion of crypto-agility above) s= selector DKIM b= base64 Signature over hash value strings (DKIM uses b=) bh= base64 Body hash value (see discussion) h= header-list Headers signed by this hop mf= mailbox reverse-path MUST be exactly this value rt= mailbox-list forward-path MUST only contain members of this list mv= position MAILVERSION version number signed by this header n= TBD a nonce value (could use for database lookup for DSN handling) Note that we have not included a version number. Experience from onwards shows that it is essentially impossible to change version numbers. If it becomes necessary to change DKIM2 in the sort of incompatible way that a new version number would be needed, we recommend using new header field names instead.

Value of i= The maximum allowed position is 50. If the Active DKIM2 Header is not in position 1, there MUST be exactly one Historical DKIM2 header for each lower integer number, starting at 1. To allow transactions with more than one forward-path, there MAY be more than one Active DKIM2 header on a message. If a message is recieved with multiple Active DKIM2 headers, the next signer MUST remove all but one of them, keeping the one with the forward-path for which it is creating an onward message. For example if one of the recipients of a multi-recipient message has a forwarding rule, then the DKIM2 header field for that recipient will be the one that is retained as the Historical DKIM2 Header for the previous position on that particular copy of the message.

Value of t= The value is a date-time. For a message in transit, the timestamp SHOULD be less than one week ago. For bounces, they SHOULD be returned to their source within 2 weeks of the timestamp on the DKIM2 Header with position 1. This requires that as the destination, or as any intermediate hop unable to deliver the message further, you SHOULD create a bounce within one week of the initial timestamp. Also, as a recipient, you SHOULD reject any message with an initial timestamp more than a week in the past. This allows signing hosts to rotate keys and only have to keep the old keys (and keep the private key private) for a maximum of 2 weeks.

Value of f= The value is a comma-separated list of flags. The following flags are defined: Flag Position Description donotmodify any This signer requests that this message not be further modified donotexplode any This signer requests that this message not be further exploded to multiple recipients donotforward any This signer requests that this message not be sent to any different recipient exploded any This signed wishes to state that it created multiple different copies of this same message feedback any This signer requests that this message be included in any feedback loop reports The "donot" fields are advisory. They might be appropriate for some types of transactional email. Since it is only a request, intermediaries may, by local policy, not honor it, but they SHOULD NOT relay mail where the request has not been honored to third parties. The "exploded" tag has security and privacy implications, which will be fleshed out in the security and privacy considerations if this stays in. If sending a BCC, or having a hidden alias target, setting exploded could leak that fact. If you don't set exploded and have taken a hidden copy, they could both wind up at a later system which might then reject the copies. The "feedback" field is advisory, however its absence means that the sender does not want feedback on this message. This document does not describe a mechanism for determining how to send feedback, or what format that feedback should be in.

Value of bh= The body hash is always calculated with the "relaxed" algorithm defined in section 3.4.2.

Value of b= The header hash is always calculated with the "relaxed" algorithm defined in section 3.4.4. The heades are calculated by first adding each of the headers listed in the h= field. Where multiple headers with the same field name exist, the first instance of the name means the value of the first instance of that header field, including the field name, colon, field body and CRLF. Further instances of the stame name mean further instances of the same header field, counting from the bottom. After all the named headers have been added, for each DKIM2-Signature header with a lower instance number is added. Before each DKIM2-Signature, any Mail-Version headers (see MAILVERSION with a lower mv= or equal value to the mv= value of that DKIM2-Signature are added. This matches the order which they will have been created. Any past Mail-Version headers, then the DKIM2-Signature which signs that set, then any further Mail-Version headers and the signature which signs those, and so on. Finally, there MUST NOT be any Mail-Version headers with a higher mv= than the mv= value on this signature. This signature header field is included last, with the value of b= being blank, exactly how it is done in .

Value of n= The nonce value is available for any purpose, but may well be used as an index into a database to access meta-data about an email that has been handled in the past. DKIM2 signatures expire after a fixed period (a week would be appropriate) so that it is not necessary to hold information for indefinite periods or to handle DSNs for email that was delivered long ago.

Value of rt= If a message is sent over , then to be accepted as a valid DKIM2 message, every forward-path MUST exactly match the rf= value of an Active DKIM2 Header. See Security Considerations in this document for a discussion of avoiding inadvertant information disclosure in cases where multiple Active DKIM2 headers are present.

Value of mf= If a message is sent over , then to be accepted as a valid DKIM2 message, the reverse-path MUST exactly match the mf= value of the Active DKIM2 Headers. The domain part of the mf= value MUST exactly match the d= value on all DKIM2 Headers.

Value of d= For DKIM2 Headers with position greater than 1, the value of d= MUST be aligned with the domain of the rt= value of the immediately previous DKIM2 Header, for example the d= value for the DKIM2 header with i=3 must be the same as the domain part of the rt= value for the DKIM2 header with i=2.

Value of mv= This value is an integer for the matching MAILVERSION version that this signature was created for. The inclusion of a version implicitly includes all MailVersion header fields with a lower or equal version, and excludes all MailVersion header fields with a greater version, when calculating the h= value.

Value of h= See the definition in

Implicitly signed headers See the description of 'b=' above. All DKIM2 Headers with a position less than or equal to the position of the DKIM2 Header itself are implicitly included in the signed headers for that DKIM2 Header. So in a message the Active DKIM2 Header at position 3, all the DKIM2- prefixed header are included in the signature. The Historical signature at position 2 includes the prefixed headers for positions 1 and 2 only, excluding those with position 3 - and of course the Historical signature with position 1 only includes those prefixed headers that are also at position 1 and excludes the others. The MailVersion headers for lower or equal versions to the mv= field are also implicitly signed, interleaved with the DKIM2-Signatures such that each signature is added after the MailVersion headers which describe the path to creating the version of the message which it signs.

Values of s= and a= TBD; we want to support multiple signatures with different algorithms in the same DKIM2 Header, so we need to figure out how to represent that to allow crypto agility.

Process for validating a DKIM2 message on receipt describes that bounce messages are only allowed for validated messages. To be able to safely create bounces, a DKIM2 aware MTA will run the following checks before responding to the DATA step of an transaction. 1) find the Active DKIM2 Header in the message header. If none are present, accept the message if local policy allows. 2) validate that the timestamp on the Active DKIM2 Header is less than one week old. 3) validate that the mf= on the Active DKIM2 Header matches the SMTP reverse-path, and that the d= matches the domain. 4) validate that every mailbox in the SMTP forward-path matches an item in the rt= on the Active DKIM2 Header. 5) validate that the local system can sign for each address in the SMTP forward-path. 6) fetch the public key for each given selector and algorithm that the receiver supports (or reply with a 5xx if no algorithms are supported). Reply with a 4xx error if the public key is unable to be feched due to a temporary error. 7) validate that the signature is valid on the Active DKIM2 Header This is sufficient information to be able to validate the bounce address and that the message was intended for the named recipients, so it can now be accepted subject to other local policy. At this stage if you generate a bounce, it will go back to the signer and the signer will accept it from you. A receiver MAY choose not to perform the above tests during the SMTP transaction, or MAY choose to accept a message despite it failing those tests, however it MUST perform the tests before creating a DSN, and MUST NOT send a DSN if it is unable to create a valid signature.

Temporary Notes The below is text from an earlier version of this document which I think is valuable to preserve at this point, however it probably belongs in another document and has not been updated to match the above.

Dealing with modifications. Find the highest numbered DKIM2 header that reports a modification. Undo the modification and repeat. When all modifications have been done then there should be a match with the original signature (at hop1). If not then the email has been altered (in an undocumented manner) on its way to you and it SHOULD be rejected. Note that it is not necessary to check the signature on a DKIM2 header that reports a modification. Undoing the modification and discovering that the message can now be authenticated is sufficient. Over time a reputation can be developed for a intermediary which is making modifications and given sufficient trust then the "undo" step could be skipped. Note that the signature of the DKIM2 header that reports the modification would need to be checked to ensure reputation accrued to the correct entity. If the modification is substantial (eg URLs rewritten, MIME parts removed) and it cannot be undone then the receiver (who may not be the immediate next hop) MUST trust the system doing the modification. If it does not then the mail SHOULD be rejected. It will be noted that some modifications can totally change the meaning of an email. This specification does not try to limit modifications. We believe that being able to attribute modifications to a particular entity will allow reliable blocking of malicious intermediaries once they are identified.

Dealing with replays Checking source and destination as recorded by the previous hop makes many “DKIM replay” scenarios impossible. It is possible to exclude all replays by determining if any DKIM2 header reports an expansion event (one incoming email resulting in multiple further emails). If not then you would expect that the (original) hash of the email is unique and duplicates can be rejected. If a expansion event is recorded then receiving multiple copies would not be a surprise. It will be necessary to use local policy to assess whether the number of copies received is acceptable or not. Over time you may wish to develop a reputation for a DKIM2 identity which is doing expansions and conclude that a specific number of copies is to be expected. This can be used to refine local policy.

Feedback loops Some mailbox providers are prepared to report their, or their customers', opinions about incoming email -- for example: that a customer marked a particular email as "spam". These systems are generally called "feedback loops". There are usually bureaucratic systems to ensure reports are only sent to entities that wish to receive them and the mailbox provider may decide that some entities should not be sent any feedback. The senders of email, the originator and/or a commercial company (an ESP) hired to send the email generally favor feedback loops because it allows them to make their emails more acceptable, and the commercial companies can rapidly become aware of customers whose email is widely disliked. In DKIM2 any intermediary can request feedback, but it is still the decision of the mailbox provider as to whether any feedback will be sent. They may still require pre-registration on a per domain basis to receive feedback if only to ensure that any nominated email address is appropriate and is not an unsuspecting third party. Note that feedback can be sent to any requesting entity. There is nothing special about a requester being at hop1 or hop2 on a chain. In particular some forwarding systems late in the chain may wish to become aware if they are forwarding emails that are then reported to be spam.

Handling of messages that leave the DKIM2 ecosystem Note that DKIM2 signed email can also be DKIM1 signed, and so systems that are not DKIM2 aware can and will operate as they do at present. DKIM2 capable servers will announce the capability in their initial banner in the usual manner for SMTP extensions. When a DKIM2 signed email is delivered to a server that does not understand DKIM2 and leaves the DKIM2 ecosystem the DKIM2 specific events can no longer be expected to occur. In particular any failures to be deliver will be reported to the address in the relevant return path and not back along the DKIM2 chain. A DKIM2 signed email may be delivered to a server that understands DKIM2 but if that server needs to forward the email elsewhere it may find that there is no signing key available for the relevant domain (recalling that the incoming email recorded the destination domain and it is necessary for the next "hop" to match with that. In such a case, once more the email will leave the DKIM2 ecosystem. Refusing to allow an email to leave the DKIM2 ecosystem may be an appropriate choice in some circumstances. If so then an appropriate DSN should be created and passed back along the chain in the normal manner. It is more likely that local policy will be to pass the email to the next intermediary even though this means that it leaves the DKIM2 ecosystem. In such a case it would be possible to add a final DKIM2 header to record this event, but doing this adds considerable complexity, and would provide limited information which was not otherwise available, hence no such header will be added. If, after having left the DKIM2 ecosystem, the email reaches a DKIM2 aware system then the email may have been altered in such a way that the DKIM2 signatures now fail. The receiving system will apply its local policy to determine whether or not to accept the email. If the DKIM2 signatures on the mail are valid, except that the last header does not specify the receiving system as the next hop, then once again it will a matter for local policy as to whether to accept the email. It might be thought that it was obvious that the email was acceptable, but the non-DKIM2-aware intermediaries that have handled it may have duplicated the email and there will be no DKIM2 headers to record this. In any event, systems that accept email which has been outside the DKIM2 ecosystem MUST NOT add any further DKIM2 headers.

DKIM2-foo headers DKIM2 allows for extension headers which are always added to the signature, but ONLY where they have an i= with a value equal to or lower than the matching DKIM2 header. This allows for extensions to add something at each DKIM2 hop; with it automatically added to the signed header set.

DKIM2-Authentication-Results If present, is identical to how ARC-Autentication-Results from ARC are used, a place for any hop to add their calculated Authentication-Results header in a way that is signed; allowing other hops to add a similar header without needing to use modification algebra to remove it when reversing the calculation.

Security Mostly TBD

Multiple addresses in the rt= field If a message has multiple values in the rt= field, it is imperative that the creating system ensure that it doesn't leak BCC information to other recipients. This MUST be done by the sending system, by creating a separately signed message for each BCC recipient.

IANA Considerations IANA is requested to add to the Permanent Message Header Field Names registry the following record. Header Field Name: DKIM2-Signature Template: Protocol: mail Status: standard Trace: no Reference: this document

This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. 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] 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] Fastmail Yahoo Google This memo provides a rationale for replacing the existing email security mechanisms with a new mechanism based around a more strongly authenticated email delivery pathway, including an asynchronous return channel. Google Inc. This memo provides a description of the procedures for bounce processing that should be performed by any mail system that implements DKIM2, as part of the overall DKIM2 protcol definition. 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 applying a cryptographic signature to 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 further signatures will be added to provide a validatable "chain". This permits validators to identify when messages have been unexpectedly "replayed" and can ensure that delivery status notifications are only sent to entities that were involved in the transmission of a message. 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 [[This section to be removed by RFC Editor]]

draft-ietf-dkim-dkim2-header-00: Renamed to working group document Added IANA considerations

draft-gondwana-dkim2-header-05: Updated description of b= and implicitly included headers to match the ordering discussed at the hackathon and in the slides I'll be presenting Removed the pp= field again (TO BE DISCUSSED) Removed the idea of multiple "active" signatures Updated MAILVERSION reference (not linked yet due to datatracker shenanigans)

draft-gondwana-dkim2-header-04: Replace nd= tag with pp= tag and update docs

draft-gondwana-dkim2-header-03: Add nd= tag and update the instructions to use it Add mv= tag and align with modification-algebra-04 Remove the modifiedbody and modifiedheader flags, they are duplicative of the mv= data; which is more useful. Update the rt= tag to be a list of addresses and require that all forward-path mailboxes be members of that list.

draft-gondwana-dkim2-header-02: cross-reference Richard's spec draft and rename to DKIM2-Signature NOTE: we need to figure out if the two drafts make sense as separate documents or whether we should just merge them

draft-gondwana-dkim2-header-01: major rewrite included support for multiple Active DKIM2 headers, as I have had side discussions that indicate that large corporate systems would have a lot of difficulty without this, and it removes constraints at the SMTP layer that were previously present. cross referenced other drafts

draft-gondwana-dkim2-header-00: initial version content extracted from draft-gondwana-dkim-motifivation