A Diagnostic Header Field for DKIM2 Implementations

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 22 March 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.¶

Table of Contents

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.¶

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 tokens "FWS", "CRLF", "VCHAR" and "WSP" are imported from [RFC5322].¶

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

info-field  = "X-DKIM2-Info:" [FWS] tag-list [FWS] CRLF
tag-list    = tag-spec *( [FWS] ";" [FWS] tag-spec )
tag-spec    = tag-name "=" tag-value
tag-name    = ALPHA *( ALPHA / DIGIT / "-" )
tag-value   = *( tv-char / FWS )
tv-char     = %x21-3A / %x3C-7E
              ; VCHAR except ";"

action-value = verb [ "=" result ] *( SP qualifier )

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.¶

action=verify=pass (i=1..2 verified)
action=verify=fail (Message-Instance m=2 header hash
  mismatch (sha256))
action=verify=none (no DKIM2-Signature headers found)

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 the ";" between tags or after a "," inside a list; a consumer MUST ignore whitespace next to ";" and ",". 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-m2" 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.¶

An inbound filter verified a message and, finding no Message-Instance, added "m=1":¶

X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-06;
  repo=git.example.net/dkim2; date=2026-08-28;
  sw=inbound-filter; action=mi-m1; 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-06;
  repo=git.example.net/dkim2; date=2026-08-28;
  sw=inbound-filter; action=verify=none (no DKIM2-Signature
  headers 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-06;
  repo=git.example.org/listmanager; date=2026-08-28;
  sw=listmanager; action=mi-m2; 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-06;
  repo=git.example.net/dkim2; date=2026-08-28;
  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-06;
  repo=git.example.net/dkim2; date=2026-08-28;
  sw=outbound-filter; action=not-signed=broken-mi-chain

Two implementations on different drafts:¶

X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-06;
  repo=git.example.net/dkim2; date=2026-08-28;
  sw=inbound-filter; action=verify=fail (Message-Instance m=1
  header hash mismatch (sha256))
...
X-DKIM2-Info: draft=ietf-dkim-dkim2-spec-05;
  repo=git.example.com/mta; date=2026-08-25;
  sw=delivery-proxy; action=mi-m1; 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

Appendix A. Changes from Earlier Versions

draft-gondwana-dkim2-debug-header-00¶

Initial version.¶

Author's Address