Summary

  • draft-gondwana-dkim2-debug-header-01 standardises the shape of an X-DKIM2-Info troubleshooting trail for early DKIM2 testing, not a new verification result.
  • The field is deliberately unsigned and excluded from DKIM2 hashes. It can tell a human where to investigate, but it cannot authenticate the emitter, action, snapshot or completeness of the trace.

The failed message looks unusually well documented. One header says which draft revision an inbound filter implemented. Another names its repository and program. A third says that the mailing-list software created Message-Instance m=2, lists the headers it hashed and points to an earlier stored snapshot. An outbound filter then says it declined to sign because the chain was broken.

That is enough detail to make a support engineer feel close to the cause. It is not enough evidence to let software decide what happened. Every line in this forensic narrative can be added, altered, reordered or removed while the DKIM2-protected parts of the message continue to verify.

That tension is the point of A Diagnostic Header Field for DKIM2 Implementations. Revision 01 appeared in the Datatracker history on 30 September 2026 in Pacific time, already 1 October in Shanghai and UTC. It is an individual Informational Internet-Draft in I-D Exists, not a DKIM Working Group document, an RFC or an IANA registration. The text says it is for early testing, is unlikely to be published and is not a normative dependency of DKIM2.

A place for evidence-shaped clues

DKIM2 is trying to preserve a verifiable chain through transformations such as mailing-list changes. Message-Instance fields contain hashes and Recipes for reconstructing earlier message states; DKIM2-Signature fields bind those protected records into a chain of custody. When two implementations disagree, the final verification error can be too coarse. A tester wants to know which software touched the message, which draft it implemented, which header names it hashed and which snapshot it compared.

X-DKIM2-Info gives those clues a repeatable location. Each field carries five required tags in order: draft, repo, date, sw and action. The first identifies the DKIM2 revision implemented. The repository and program distinguish a component or fork. The date is meant to change when that emitter's DKIM2 behaviour changes. One field records one action; multiple actions produce multiple fields.

The defined vocabulary covers verification, a newly added Message-Instance, a signature and a refusal to sign. verify=pass or verify=fail may carry a free-text explanation. mi-m=<N> can add the count and ordered names of hashed headers, plus identifiers for the snapshot fetched and the one stored. sign names the domain and algorithm. not-signed carries an implementation-chosen reason such as broken-mi-chain.

For a person comparing two test runs, this is valuable. Revision 01 even tightens interoperability from revision 00: it reuses DKIM2's own extension-tag grammar, requires a semicolon after every tag and renames mi-m<N> to mi-m=<N>. Different implementations now have fewer trivial syntax differences to obscure a real disagreement.

The field survives because the proof ignores it

The design obtains that flexibility through a sharp exclusion. The underlying DKIM2 draft says header names beginning with X- are omitted from the Message-Instance header hash. The diagnostic draft also forbids emitters from putting X-DKIM2-Info into anything they sign or hash. A handler can therefore insert a debug field beside the header it describes without changing the protected Message-Instance or invalidating a DKIM2 signature.

The same property prevents the field from proving its own story. The draft says it is not a verification result; the authoritative result belongs in Authentication-Results. It says the field records only what an emitter claims it did, and software must not base any message decision on it. A message may contain any number of fields from any number of emitters. Security considerations state plainly that anyone handling the message can add, alter or remove one undetected.

The distinction from the existing BTW coverage is important. The Chain Passed. The Header That Said So Was Unsigned examined a DKIM2 result inside Authentication-Results, where a consumer may rely on a locally trusted authserv-id within one administrative domain and SMTP transaction. X-DKIM2-Info sits below even that local-verdict layer. It is deliberately disqualified from automated trust. Its job is to help a human ask a better question.

Position is a clue, not a causal signature

The draft tells an emitter to add the protected or operational header first and then put its debug field immediately above it. It also says a conforming emitter must not modify or remove fields already present. This builds a readable chronology into the header block.

But adjacency is not authenticated causality. A later handler can prepend a convincing action=sign, move a field next to another Message-Instance or delete the line that would explain a failure. A repository path and program name are self-descriptions, not a binary attestation. The behaviour date is not a commit hash. No event identifier, emitter-instance key, sequence number, receiver acknowledgement or completeness statement links the separate fields into a tamper-evident log.

Silence is also ambiguous. If an emitter finds that the top Message-Instance still matches and adds nothing, the draft records no action. An absent mi-m=<N> therefore does not prove that a check ran, that nothing changed or that an intermediary preserved the trace. A human can read what is present; the format cannot show that nothing is missing.

Snapshot pointers do not carry snapshots

The most operationally useful tags expose another boundary. snapf names the earlier stored copy used to compute a Recipe. snaps names the current copy retained for a later comparison. The draft says these identifiers are meaningful only to the emitter that wrote them. One example looks like a database key or path.

That token can shorten a support conversation: take it to the operator of the named component and request the corresponding bytes and logs. Outside that system, it proves no snapshot content, retention period, custody or availability. Unless an implementation separately provides a content digest and retrieval receipt, a copied identifier is not a portable evidence object.

The field can also disclose more than intended. It names source repositories and programs, hints at storage layout, exposes draft versions and lists the header inventory present at hashing time. Free-text failure explanations can reveal parser behaviour. Operators may strip the field at an outbound boundary without affecting DKIM2 verification. That protects architecture but removes the very breadcrumb a remote tester hoped to inspect, so retention and disclosure policy must be designed together.

There is a parser edge too. RFC 5322 permits a semicolon in a header field name. Because semicolons terminate tags and the format has no quoting mechanism, a copied name could look like a new tag. The draft tells emitters to omit unsafe names from hn, cap its length and replace or remove semicolons in substituted values. Those rules reduce ambiguity; they do not prove that every early implementation follows them.

RFC 6648 explains the wider risk of X- names: supposedly private fields escape, become de facto interfaces and create migration or security ambiguity. Here the prefix is a conscious engineering trade. It keeps the field outside DKIM2 protocol meaning and cryptographic coverage. Leadership should not mistake that clean boundary for containment.

Use the breadcrumb to find the receipt

A defensible investigation keeps ten facts apart: the emitter's claimed software identity; its claimed action; the field currently present in the message; the boundary that received or stripped it; the actual DKIM2 verification; the authoritative local Authentication-Results; the corresponding build, logs and stored snapshots; the operator's root-cause judgment; the repair; and the observed delivery or user outcome.

Heng Lu's minimum-specification doctrine favours exactly this division. A shared format should make independent testing easier without pretending that it can supply local runtime truth. Running-code primacy asks whether the implementation, snapshot, logs and later result can be observed and reproduced.

X-DKIM2-Info is useful because it leaves readable fingerprints near the failure. It becomes dangerous only when a support convenience is promoted into provenance, policy or verdict. The right automation does not act on the breadcrumb. It uses the breadcrumb to retrieve the evidence that can be checked.

Sources