| Internet-Draft | DKIM2 Headers | March 2025 |
| Gondwana, et al. | Expires 4 September 2025 | [Page] |
This document describes the headers defined for DKIM2 and how they work togther to provide the behaviours that are designed into DKIM2.¶
This is an early draft, a work in progress.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 4 September 2025.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The DKIM2 header draws significant amoungs of design from ARC.¶
DKIM2 headers will have the following fields¶
| Field identifier | Explanation |
|---|---|
| i= | Sequence Number (from 1 to N) |
| t= | Timestamp |
| ds= | Signing key identifier (domain & selector) |
| a= | Crypto algorithm(s) used (unless combined with b= to allow for multiple signatures on the same email, see discussion of crypto-agility above) |
| b= | Signature over hash value strings (DKIM uses b=) |
| bh= | Body hash value (see discussion) |
| h= | Extra headers signed by this hop |
| m= | Indicates if mail has been modified or exploded |
| mf= | RFC5321.mail-from |
| rt= | RFC5321.rcpt-to |
| fb= | feedback requested for this email |
| n= | a nonce value (could use for database lookup for DSN handling) |
At the first hop there cannot be any modification, so instead the m= field is used to indicate a request by the sender that the email never be modified and/or never be “exploded” to multiple recipients. This 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.¶
We will always hash headers in a "relaxed" mode (to use the DKIM1 jargon). For the body we will always use "relaxed" because that is the usual scheme for DKIM1. Relaxed is more expensive than "simple" but there have been concerns about expressed about interworking. The vast majority of DKIM1 email (99%+) uses relaxed/relaxed.¶
The hashes of the header and the body can be placed into the DKIM2 header field, and then a signature is applied. Alternatively we could define a signature over the hashes but not record their values. The second is neater but the former does allow an unchanged body hash to just be copied and may assist in diagnosing faults. Note also, that there is no technical reason for computing two hashes rather than one, but the presence of an obviously unchanged body hash may again be useful for fault diagnosis and may assist humans in reasoning about how and where changes were made to the body.¶
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.¶
Note that we have not included a version number. Experience from MIME 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 v=2 / v=3 version number would support, we recommend using header fields labeled DKIM3 instead.¶
For simplicity using single characters before the = would be good, but we quickly run out of obvious relevant letters. Where there is a match to DKIM1 fields these have been copied (though this is merely to assist humans, it's unlikely to affect any code).¶
Note that is inherent in the DKIM2 design that emails are only ever sent to one recipient at a time. At present some mail servers will batch deliveries together if they are going to the same destination and issue multiple RCPT TO commands in the SMTP protocol conversation. This is not possible with DKIM2 because each email must document a single RFC5321 destination in the rt= parameter. This may seem inefficient but only about 1% of email is currently delivered using multiple RCPT TO commands.¶
There will be an absolutely maximum value of 255 for i=; though realistically we should be able to bring this value back down to about 50.¶
For a message in transit, the timestamp MUST be less than one week ago. For bounces, they MUST be returned to their source within 2 weeks of the timestamp on hop i=1. This requires that as the destination, you MUST create the bounce within 1 week of receipt.¶
| Value | Purpose |
|---|---|
| nomodify | Any hop that adds this requires no modifications; anybody later hop must either reject it or agree to pass it on unmodified |
| header | This hop has modified the headers; a separate header lists the algebra to revert the changes |
| body | This hop has modified the body; a separate header lists the algebra to revert the changes |
| complex | This hop has done something complex and there is no way to revert it |
If there is no "m" value then this hop asserts it has not modified either the body nor any header covered by a previous DKIM2 signature.¶
Not present, do not send feedback for this email to the signing domain¶
fb=y - this signing domain would like to receive feedback about the disposition of this email (e.g. percentage reported as spam).¶
For clarity this is written as if there is only one hash and signature to check, whereas there may in fact be one for the header and one for the body. Issues with DNS will cause [RFC5321] 4xx responses to be sent.¶
Find the latest DKIM2 signature and determine if the email as received matches that hash AND that you are named as the destination of the email AND that the mail is coming from the named source. If not then refuse to accept the email. The previous hop is responsible for the email (they have either forged it or mangled it -- either way it is their problem).¶
If this check passes then other checks can either be done at delivery time or the mail can be accepted and if later rejected there is a valid path back to the sender over which a DSN can be sent.¶
If it is decided, by local policy, to accept an email where the hash fails (or you are not the documented recipient) then DSN messages back along the chain MUST NOT be sent.¶
Find the first DKIM2 header (numbered 1) and determine if the email as received has the same hash as recorded there. If so, you know the email has not been altered on its way to you. The path it has followed is most likely irrelevant for deciding what to do with it.¶
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.¶
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.¶
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.¶
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 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.¶
See draft-gondwana-dkim2-modifications for definitions of these headers, which are used for the modification algebra. These headers are used to allow¶
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.¶
[[This section to be removed by RFC Editor]]¶