| Internet-Draft | Local Headers | June 2026 |
| Chuang | Expires 11 December 2026 | [Page] |
The DKIM2 specification authenticates email messages with digital signatures, with additional metadata to recover the signature even when the message is forwarded and modified. This draft builds upon DKIM2 to support hashing and authentication of domain specific headers even when the message is forwarded and modified. Other trace-like headers may be supported as well. Authentication-Result header fields support documentation of authentication results as seen by receivers during the forwarding path. Receivers often delete older copies of Authentication-Results even though they may have forensic value. This draft provides a means to preserve those header fields despite those receiver actions.¶
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 11 December 2026.¶
Copyright (c) 2026 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 (draft-clayton-dkim2-spec) specification builds upon DKIM ([RFC6376]) to authenticate email messages with digital signatures, even when the message is forwarded and modified. It calls for a signature at the originator and each of the forwarder ADMDs with metadata to recover the earlier signature.¶
This draft proposes an optional scheme to help publish and preserve proprietary and trace-like header fields. It calls for these header fields to be prefixed and labeled with an index to identify and protect them. They are authenticated by having the opt-in SMTP ([RFC5321]) senders hash these header fields and publish the hash in the DKIM2 Message-Instance header field as a new tag. Upon receiving such a message, the validation engine recomputes the hash. If the published and recomputed values mismatch, the message is rejected.¶
Authentication-Result ([RFC8601]) header fields document authentication results as seen by SMTP receivers. When the message is forwarded, prior Authentication-Result header fields may be deleted to prevent confusion however they contain historic information that may be of value when messages are mis-delivered. The proposed scheme in this draft prevents confusion hence enables preserving forensic information to help debug delivery.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].¶
DKIM2 Localized Header Fields are identified by a prefix "DKIM2-" and preserve the value of domain specific content. DKIM2 senders and receivers MAY opt to handle these header fields using the following procedures to generate and validate them.¶
DKIM2 Localized Header Fields are identified by a field name starting with a prefix "DKIM2-" followed by a distinguishing field-name ([RFC5322]), excluding "signature". The field name is separated by a local instance tag-value by a colon separator and the body by semi-colon. The local instance is designated by a tag "m" and value number whose value corresponds to the Message-Instance that it is created with. The unstructured field body as defined by SMTP email headers field syntax ([RFC5322]).¶
local-header = local-field-name ":" 0*WSP local-instance 0*WSP ";" unstructured local-field-name = "DKIM2-" field-name local-instance = "m" 0*WSP "=" 0*WSP number¶
Because there will be no registry to disambiguate these field header names, each sender must use their judgement to find a distinguishing name. For example one strategy might be to use a domain specific name followed by another purpose name.¶
To protect the DKIM2 Localized Header Fields headers, this specification introduces a new Message-Instance tag-value "l" followed by a hash value of DKIM2 Localized Header Fields headers.¶
DKIM2 Localized Header Fields are generated typically at SMTP outbound. Before creating new headers, the header generator discovers the highest DKIM2 (draft-clayton-dkim2-spec) Message-Instance revision number tagged by "m". The generator increments this number to create the local instance value¶
When the DKIM2 signer generates a new Message-Instance header field on SMTP outbound, the signer needs to compute the hash of the DKIM2 Localized Header Fields. The signer calls up the hashing process described below and obtains a base64 hash. With this, the signer adds a "l' tag and the hash value to the Message-Instance header field.¶
As input to this process, it takes the revision number of the Message-Instance to be generated that acts as the limit. The hashing processor scans the headers from bottom up and finds all DKIM2 Localized Header Fields with revision numbers at the limit or lower, and provides them in the found order to the SHA256 hasher. The binary hashed output is base64 encoded ([RFC4648]) and returned.¶
As part of the DKIM2 verification, when each Message-Instance header field is examined, the verifier may choose to validate the DKIM2 Localized Header Fields verifier as well. At the very minimum, verifiers choosing to validate the DKIM2 Localized Header Fields MUST verify the "l" hash of the Message-Instance with the highest numbered revision number. If header algebra indicates that DKIM2 Localized Header Fields have been restored at lowered numbered revision numbers, the verifier MAY re-verify "l" hash.¶
To check "l" hash, the verifier computes the current hash by passing the revision number to the hashing procedure above to obtain a base64 hash. It does an exact comparison between the computed hash and the Message-Instance "l" hash. If they are different, this causes DKIM2 verification to fail. in addition results from the DKIM2 Localized Header Fields SHOULD NOT be used. Potentially the message SHOULD be rejected with SMTP PERMFAIL. If the hashes are the same, DKIM2 verification continues.¶
One important application of DKIM2 Localized Header Fields to protect Authentication-Result, which can be converted as described above. Authentication-Result header fields are typically generated on SMTP inbound which is different from the above outbound SMTP handling context. To protect these headers, this procedure is to generate DKIM2 signatures on SMTP inbound assuming that they will be delivered to the inbox. For these signatures, the value of the "rt=" is left empty, and will fail the chain of custody validation if the message was replayed out of the inbox. If the messages are SMTP relayed, and signer SHOULD check the most recent DKIM2 signatures remains valid excluding the empty "rt=". The signer strips the top most DKIM2 signature, DKIM2 signs the message again at the same instance number, and sets the "rt=" tag to the recipient.¶
The result of DKIM2 Localized Header Fields validation can be added to Authentication-Result ([RFC8601]). This specifies a new method "lhf" that can take a result of "pass" or "fail".¶
This specification provides protection for DKIM2 Localized Headers. More considerations will be generated in the future.¶
This document has no IANA actions yet.¶