Network Working Group B. Gondwana
Internet-Draft Fastmail Pty Ltd
Obsoletes: 4686 (if approved) R. Clayton
Intended status: Standards Track Yahoo
Expires: 4 September 2025 W. Chuang
Google
3 March 2025
DKIM2 Header Definitions
draft-gondwana-dkim2-header-00
Abstract
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.
Status of This Memo
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 Notice
Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved.
Gondwana, et al. Expires 4 September 2025 [Page 1]
Internet-Draft DKIM2 Headers March 2025
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.
Table of Contents
1. The DKIM2 Header . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Value of rt= . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Maximum value for i= . . . . . . . . . . . . . . . . . . 4
1.3. Maximum age for t= . . . . . . . . . . . . . . . . . . . 5
1.4. Registry of values for m= . . . . . . . . . . . . . . . . 5
1.5. Value for the fb= header . . . . . . . . . . . . . . . . 5
2. Checking hashes . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2. Step 2 . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3. Dealing with modifications. . . . . . . . . . . . . . . . 6
2.4. Dealing with replays . . . . . . . . . . . . . . . . . . 7
3. Feedback loops . . . . . . . . . . . . . . . . . . . . . . . 7
4. Handling of messages that leave the DKIM2 ecosystem . . . . . 8
4.1. DKIM2-foo headers . . . . . . . . . . . . . . . . . . . . 9
4.1.1. The DKIM2-Delta-Header and DKIM2-Delta-Body
headers . . . . . . . . . . . . . . . . . . . . . . . 9
4.1.2. DKIM2-Authentication-Results . . . . . . . . . . . . 9
5. Security . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
7. Normative References . . . . . . . . . . . . . . . . . . . . 9
Appendix A. Changes from Earlier Versions . . . . . . . . . . . 10
A.1. draft-gondwana-dkim2-headers-00: . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10
1. The DKIM2 Header
The DKIM2 header draws significant amoungs of design from ARC.
DKIM2 headers will have the following fields
Gondwana, et al. Expires 4 September 2025 [Page 2]
Internet-Draft DKIM2 Headers March 2025
+============+=================================================+
| Field | Explanation |
| identifier | |
+============+=================================================+
| 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) |
+------------+-------------------------------------------------+
Table 1
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.
Gondwana, et al. Expires 4 September 2025 [Page 3]
Internet-Draft DKIM2 Headers March 2025
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).
1.1. Value of rt=
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.
1.2. Maximum value for i=
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.
Gondwana, et al. Expires 4 September 2025 [Page 4]
Internet-Draft DKIM2 Headers March 2025
1.3. Maximum age for t=
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.
1.4. Registry of values for m=
+==========+==============================================+
| 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 |
+----------+----------------------------------------------+
Table 2
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.
1.5. Value for the fb= header
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).
2. Checking hashes
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.
Gondwana, et al. Expires 4 September 2025 [Page 5]
Internet-Draft DKIM2 Headers March 2025
2.1. Step 1
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.
2.2. Step 2
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.
2.3. 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.
Gondwana, et al. Expires 4 September 2025 [Page 6]
Internet-Draft DKIM2 Headers March 2025
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.
2.4. 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.
3. 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.
Gondwana, et al. Expires 4 September 2025 [Page 7]
Internet-Draft DKIM2 Headers March 2025
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.
4. 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
Gondwana, et al. Expires 4 September 2025 [Page 8]
Internet-Draft DKIM2 Headers March 2025
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.
4.1. 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.
4.1.1. The DKIM2-Delta-Header and DKIM2-Delta-Body headers
See draft-gondwana-dkim2-modifications for definitions of these
headers, which are used for the modification algebra. These headers
are used to allow
4.1.2. 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.
5. Security
TBA
6. IANA Considerations
TBA
7. Normative References
[RFC4871] Allman, E., Callas, J., Delany, M., Libbey, M., Fenton,
J., and M. Thomas, "DomainKeys Identified Mail (DKIM)
Signatures", RFC 4871, DOI 10.17487/RFC4871, May 2007,
<https://www.rfc-editor.org/rfc/rfc4871>.
[RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
DOI 10.17487/RFC5321, October 2008,
<https://www.rfc-editor.org/rfc/rfc5321>.
Gondwana, et al. Expires 4 September 2025 [Page 9]
Internet-Draft DKIM2 Headers March 2025
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/rfc/rfc5322>.
[RFC8617] Andersen, K., Long, B., Ed., Blank, S., Ed., and M.
Kucherawy, Ed., "The Authenticated Received Chain (ARC)
Protocol", RFC 8617, DOI 10.17487/RFC8617, July 2019,
<https://www.rfc-editor.org/rfc/rfc8617>.
Appendix A. Changes from Earlier Versions
[[This section to be removed by RFC Editor]]
A.1. draft-gondwana-dkim2-headers-00:
* initial version
* content extracted from draft-gondwana-dkim-motifivation
Authors' Addresses
Bron Gondwana
Fastmail Pty Ltd
Level 2, 114 William Street
3000
Australia
Phone: +61 457 416 436
Email: brong@fastmailteam.com
Richard Clayton
Yahoo
Email: rclayton@yahooinc.com
Wei Chuang
Google
Email: weihaw@google.com
Gondwana, et al. Expires 4 September 2025 [Page 10]