A Diagnostic Header Field for DKIM2 Implementations
draft-gondwana-dkim2-debug-header-03
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Bron Gondwana | ||
| Last updated | 2026-11-02 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-gondwana-dkim2-debug-header-03
Network Working Group B. Gondwana
Internet-Draft Fastmail Pty Ltd
Intended status: Informational 2 November 2026
Expires: 6 May 2027
A Diagnostic Header Field for DKIM2 Implementations
draft-gondwana-dkim2-debug-header-03
Abstract
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.
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 6 May 2027.
Copyright Notice
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.
Gondwana Expires 6 May 2027 [Page 1]
Internet-Draft DKIM2 Debug Header November 2026
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology and conventions . . . . . . . . . . . . . . . . . 3
3. The "X-" name . . . . . . . . . . . . . . . . . . . . . . . . 3
4. No protocol meaning . . . . . . . . . . . . . . . . . . . . . 3
5. The X-DKIM2-Info header field . . . . . . . . . . . . . . . . 3
5.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3
5.2. Provenance tags . . . . . . . . . . . . . . . . . . . . . 4
5.3. The action tag . . . . . . . . . . . . . . . . . . . . . 4
5.4. Supplementary tags . . . . . . . . . . . . . . . . . . . 4
6. Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
6.1. verify=<result> . . . . . . . . . . . . . . . . . . . . . 5
6.2. mi-m=<N> . . . . . . . . . . . . . . . . . . . . . . . . 5
6.3. sign d=<domain> a=<algorithm> . . . . . . . . . . . . . . 5
6.4. not-signed=<reason> . . . . . . . . . . . . . . . . . . . 6
7. Emitter behaviour . . . . . . . . . . . . . . . . . . . . . . 6
8. Reading the field . . . . . . . . . . . . . . . . . . . . . . 6
9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6
10. IANA considerations . . . . . . . . . . . . . . . . . . . . . 8
11. Security considerations . . . . . . . . . . . . . . . . . . . 8
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
12.1. Normative References . . . . . . . . . . . . . . . . . . 8
12.2. Informative References . . . . . . . . . . . . . . . . . 9
Appendix A. Changes from Earlier Versions . . . . . . . . . . . 9
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10
1. Introduction
DKIM2 ([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 [DKIM2] does not depend on
it.
Gondwana Expires 6 May 2027 [Page 2]
Internet-Draft DKIM2 Debug Header November 2026
2. 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
[RFC2119]. These words take their normative meanings only when they
are presented in ALL UPPERCASE.
Basic email terminology is taken from [RFC5598]. The terms Signer,
Verifier, Originator, Message-Instance, Recipe and Chain of Custody
are used as defined in [DKIM2].
Syntax descriptions use Augmented BNF (ABNF) [RFC5234]. The token
"CRLF" is imported from [RFC5234], and "tag-list" from the "Tag=Value
Lists" section of [DKIM2].
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.
3. The "X-" name
[DKIM2] 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.
4. No protocol meaning
An X-DKIM2-Info header field is not a verification result. If the
software is generating an Authentication-Results ([AUTHRES]) 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.
5. The X-DKIM2-Info header field
5.1. Syntax
The value is a Tag=Value list, using exactly the syntax that [DKIM2]
defines for the Message-Instance and DKIM2-Signature header fields:
info-field = "X-DKIM2-Info:" tag-list CRLF
Gondwana Expires 6 May 2027 [Page 3]
Internet-Draft DKIM2 Debug Header November 2026
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.
5.2. Provenance tags
These identify the software which emitted the field. They are the
same in every field an emitter produces.
draft: The [DKIM2] revision the emitter implements, without the
"draft-" prefix, for example "ietf-dkim-dkim2-spec-09".
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".
5.3. 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:
action-value = verb [ "=" result ] *( SP qualifier )
The vocabulary is in Section 6.
5.4. 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
Gondwana Expires 6 May 2027 [Page 4]
Internet-Draft DKIM2 Debug Header November 2026
hashed (which [DKIM2] 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.
6. 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.
6.1. verify=<result>
The emitter verified the message on receipt. The result is one of
the five [DKIM2] output states in lower case, as reported in
Authentication-Results ([AUTHRES]), optionally followed by a free-
text explanation in parentheses:
action=verify=pass (i=1..2 verified)
action=verify=fail (Message-Instance m=2 header hash
mismatch (sha256))
action=verify=none (no DKIM2 header fields found)
The authoritative result is in Authentication-Results ([AUTHRES]).
No supplementary tags.
6.2. 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.
6.3. sign d=<domain> a=<algorithm>
The emitter added a DKIM2-Signature with that Signing Domain and
algorithm. No supplementary tags.
Gondwana Expires 6 May 2027 [Page 5]
Internet-Draft DKIM2 Debug Header November 2026
6.4. 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.
7. 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 [DKIM2]; in addition, a consumer
MUST ignore whitespace next to ",". An emitter MUST NOT fold inside
a token.
The field is excluded from the [DKIM2] header hash by the "x-" rule
(Section 3). An emitter MUST NOT include it in anything it signs or
hashes.
8. 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".
9. Examples
Line breaks and indentation follow [RFC5322] folding. Domains,
repositories and program names are examples.
Gondwana Expires 6 May 2027 [Page 6]
Internet-Draft DKIM2 Debug Header November 2026
An inbound filter verified a message and, finding no Message-
Instance, added "m=1":
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-09;
repo=git.example.net/dkim2; date=2026-11-02;
sw=inbound-filter; action=mi-m=1; hc=8;
hn=content-type,date,from,message-id,mime-version,subject,
to,to;
snaps=a5/a5440deb07cdcf63cd16bfaa29d9a87c0b97a300e1c2d3f4;
Message-Instance: m=1; ...
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-09;
repo=git.example.net/dkim2; date=2026-11-02;
sw=inbound-filter; action=verify=none (no DKIM2 header
fields found);
Authentication-Results: mx.example.net; dkim2=none
The same message after a mailing list recorded its changes as "m=2":
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-09;
repo=git.example.org/listmanager; date=2026-11-02;
sw=listmanager; action=mi-m=2; hc=18;
hn=archived-at,content-type,date,feedback-id,from,list-archive,
list-help,list-id,list-owner,list-post,list-subscribe,
list-unsubscribe,message-id,message-id-hash,mime-version,
precedence,subject,to;
snapf=a5440deb07cdcf63cd16bfaa29d9a87c0b97a300;
Message-Instance: m=2; ...
An outbound filter then verified the chain and signed:
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-09;
repo=git.example.net/dkim2; date=2026-11-02;
sw=outbound-filter; action=sign d=list.example.org a=rsa-sha256;
DKIM2-Signature: i=2; d=list.example.org; ...
A Signer which declined because the Message-Instance chain would not
undo:
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-09;
repo=git.example.net/dkim2; date=2026-11-02;
sw=outbound-filter; action=not-signed=broken-mi-chain;
Two implementations on different drafts:
Gondwana Expires 6 May 2027 [Page 7]
Internet-Draft DKIM2 Debug Header November 2026
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-09;
repo=git.example.net/dkim2; date=2026-11-02;
sw=inbound-filter; action=verify=fail (Message-Instance m=1
header hash mismatch (sha256));
...
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-07;
repo=git.example.com/mta; date=2026-10-20;
sw=delivery-proxy; action=mi-m=1; hc=8;
hn=content-type,date,feedback-id,from,message-id,mime-version,
subject,to;
10. IANA considerations
None.
11. 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.
[RFC5322] 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".
12. References
12.1. Normative References
[DKIM2] Clayton, R., Chuang, W., and B. Gondwana, "DomainKeys
Identified Mail Signatures v2 (DKIM2)", Work in Progress,
Internet-Draft, draft-ietf-dkim-dkim2-spec-09, 1 November
2026, <https://datatracker.ietf.org/doc/html/draft-ietf-
dkim-dkim2-spec-09>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
Gondwana Expires 6 May 2027 [Page 8]
Internet-Draft DKIM2 Debug Header November 2026
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/rfc/rfc5234>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
DOI 10.17487/RFC5322, October 2008,
<https://www.rfc-editor.org/rfc/rfc5322>.
12.2. Informative References
[AUTHRES] Gondwana, B., "Reporting DKIM2 Verification Results in
Authentication-Results", Work in Progress, Internet-Draft,
draft-gondwana-dkim2-authres-01, 28 October 2026,
<https://datatracker.ietf.org/doc/html/draft-gondwana-
dkim2-authres-01>.
[RFC5598] Crocker, D., "Internet Mail Architecture", RFC 5598,
DOI 10.17487/RFC5598, July 2009,
<https://www.rfc-editor.org/rfc/rfc5598>.
Appendix A. Changes from Earlier Versions
draft-gondwana-dkim2-debug-header-03
Aligned with draft-ietf-dkim-dkim2-spec-09: "none" is now one of the
five [DKIM2] output states. Examples name spec-09.
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 [AUTHRES]. Corrected the header hash order to
ascending octet order. Examples updated to current draft revisions.
draft-gondwana-dkim2-debug-header-01
Use the [DKIM2] 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.
Gondwana Expires 6 May 2027 [Page 9]
Internet-Draft DKIM2 Debug Header November 2026
Author's Address
Bron Gondwana
Fastmail Pty Ltd
Level 2, 114 William Street
3000
Australia
Phone: +61 457 416 436
Email: brong@fastmailteam.com
Gondwana Expires 6 May 2027 [Page 10]