[Ietf-dkim] Re: Hackathon day 1 report -- draft-clayton-dkim2-spec-08 review

Richard Clayton <richard@highwayman.com> Sun, 15 March 2026 02:43 UTC

Return-Path: <richard@highwayman.com>
X-Original-To: ietf-dkim@mail2.ietf.org
Delivered-To: ietf-dkim@mail2.ietf.org
Received: from localhost (localhost [127.0.0.1]) by mail2.ietf.org (Postfix) with ESMTP id 34A7ECA1E475 for <ietf-dkim@mail2.ietf.org>; Sat, 14 Mar 2026 19:43:01 -0700 (PDT)
X-Virus-Scanned: amavisd-new at ietf.org
X-Spam-Flag: NO
X-Spam-Score: -2.098
X-Spam-Level:
X-Spam-Status: No, score=-2.098 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: mail2.ietf.org (amavisd-new); dkim=pass (2048-bit key) header.d=highwayman.com
Received: from mail2.ietf.org ([166.84.6.31]) by localhost (mail2.ietf.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 7jqXi8NVdqKu for <ietf-dkim@mail2.ietf.org>; Sat, 14 Mar 2026 19:43:00 -0700 (PDT)
Received: from mail.highwayman.com (mail.highwayman.com [82.69.6.249]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-256) server-digest SHA256) (No client certificate requested) by mail2.ietf.org (Postfix) with ESMTPS id 2B898CA1E40B for <ietf-dkim@ietf.org>; Sat, 14 Mar 2026 19:42:37 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=highwayman.com; s=rnc1; h=Content-Transfer-Encoding:Content-Type: MIME-Version:In-Reply-To:References:Subject:From:To:Date:Message-ID:Sender: Reply-To:Cc:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=iaoO1MPaMSWDC3dJEFmbBGqgQkRzCb5SZnLlg+dXyq8=; t=1773542557; x=1774406557; b=FERoYYYYzbJ6EIsAdlc3jS4Sd75nTeDEJI5kuRZ0eqUjGbcSTB93VmCfBVGLTT3+LC4o+HC4aJk J/u5W7CPe1FL5tixDf/OlEa4JpfG3hui45HkYfHb0Y/8t687Wh1P66LpBEk8/j69SiOv3yS5zmcOl wTplDkL5RITo6k2fm61y72TrwMvK75x20xBAiFoAJJQWP7PnVjLZrnQ8rJ+4vkUl2SSZJMbLl2Tiw K3sGRKr++AprmyvZnuikXthgZyRuffEabtWp65+aL+LkkcpKZRZgWW9B3fT/Kdgh+ygIAthGn9ofn n9HtNN+3Bqls6uKsTZWjbAE5+zG0uyEslJSg==;
Received: from [127.0.0.1] (port=44686 helo=happyday.al.cl.cam.ac.uk) by mail.highwayman.com with esmtp (Exim 4.98.2) (envelope-from <richard@highwayman.com>) id 1w1bQz-00000000DLh-3ALK for ietf-dkim@ietf.org; Sun, 15 Mar 2026 02:42:29 +0000
Message-ID: <Z3TFLXBXwhtpFAW2@highwayman.com>
Date: Sun, 15 Mar 2026 02:40:23 +0000
To: ietf-dkim@ietf.org
From: Richard Clayton <richard@highwayman.com>
References: <47baafa2-200e-4bfb-923d-79ec9a0eb21d@app.fastmail.com>
In-Reply-To: <47baafa2-200e-4bfb-923d-79ec9a0eb21d@app.fastmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit
X-Mailer: Turnpike Integrated Version 5.03 M <zqz$+$F777$MhPKLF6b+denf5D>
Message-ID-Hash: SO5QDPXZIV75SN2HXYMDT5RIYZWOP4NO
X-Message-ID-Hash: SO5QDPXZIV75SN2HXYMDT5RIYZWOP4NO
X-MailFrom: richard@highwayman.com
X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-ietf-dkim.ietf.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header
X-Mailman-Version: 3.3.9rc6
Precedence: list
Subject: [Ietf-dkim] Re: Hackathon day 1 report -- draft-clayton-dkim2-spec-08 review
List-Id: IETF DKIM List <ietf-dkim.ietf.org>
Archived-At: <https://mailarchive.ietf.org/arch/msg/ietf-dkim/PBHmvj24plA3tmC3jIBqzdlHEhs>
List-Archive: <https://mailarchive.ietf.org/arch/browse/ietf-dkim>
List-Help: <mailto:ietf-dkim-request@ietf.org?subject=help>
List-Owner: <mailto:ietf-dkim-owner@ietf.org>
List-Post: <mailto:ietf-dkim@ietf.org>
List-Subscribe: <mailto:ietf-dkim-join@ietf.org>
List-Unsubscribe: <mailto:ietf-dkim-leave@ietf.org>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

In message <47baafa2-200e-4bfb-923d-79ec9a0eb21d@app.fastmail.com>, Bron
Gondwana <brong=40fastmailteam.com@dmarc.ietf.org> writes

>The following review has been generated (with some input by me) from two copies 
>of Claude Code

my reply is all mine !

>Some interop issues are disagreements bewtween me and Richard I think, or 
>Richard failing to copy across things from my doc - I was always very clear that 
>I wanted headers counting from the bottom up so that recipes would say 
>"Authentication-Results: [1, 3]" rather than "Authentication-Results: [2, 4]".

I thought I did that for the recipes ... but onward ...

>1. Signing input header ordering (Section 11.5) — INTEROP FAILURE
>
>The spec says: “First come the Message-Instance header fields in ascending
>version (v=) order. Second are the DKIM2-Signature header fields in ascending
>sequence (i=) order. Last of all is an incomplete DKIM2-Signature header
>field.”
>This was read two different ways:
> • *All-then-all:* All MI headers first, then all DKIM2-Signature headers.
>For a 2-hop message signing i=2:
>`MI v=1, MI v=2, Sig i=1, Sig i=2 (incomplete)`

yes .. all the MIs and only then all the DSs. That should be
straightforward because you're likely to have the header fields in a
data-structure indexed by header field name

> • *Interleaved:* Each DKIM2-Signature follows the MI headers that existed
>when it was created:
>`MI v=1, Sig i=1, MI v=2, Sig i=2 (incomplete)`

if an AI interprets my text that way then I rather think that's the AI's
problem not mine

>The interleaved ordering is the correct semantic interpretation: when sig i=1
>was created, only MI v=1 existed. The signing input for sig i=2 should
>reflect the full chain of headers as they were added in sequence.

that would be complex to code because you would need to inspect the DS
header fields to see which MIs existed (recall that DS counts are likely
to be higher than MI counts).

you might get some saving for the verification process from being able
to hold some intermediate hash states rather than having to start from
the beginning every time ... but there is some complexity to doing that
and it may be that that saving is not available in some signature
schemes (recall that for DS we don't publish the hash because the
signature itself may provide that as part of its design)

>*Suggested fix:* Replace “First come… Second are…” with explicit
>interleaved ordering and a worked example for a multi-hop message.

I think that is a poor idea

I have shied away from putting examples into the document thus far
because they are hard to maintain (and may fool us into thinking that
the descriptive text is better than it is).

That said, I think one all-encompassing example in an Appendix would be
be a wise addition.

>2. “Null s=” ambiguity in signing input (Section 11.5) — INTEROP FAILURE
>
>The spec says: “the signature value (s=) is null (that is the base64 value
>is absent).”

this is talking about what string is fed to the signing code for the
incomplete DKIM2-Signature header field (which is in the process of
being constructed). Clearly the string has to contain everything that
will be in the final header field but it cannot of course contain the
signature values themselves.

>This could mean:
> • `s=` — literally nothing after the equals sign

yes... tell the AI that absent means literally nothing (or get another
AI that groks English a bit better) -- so there is no "could"

> • `s=<base64 of JSON with empty signature strings>` — preserving the
>selector/algorithm structure with empty values
> • The s= tag is entirely absent
>Because s= is included in the signing input, any disagreement here means
>signatures cannot be cross-verified.

I think that there is an issue here, but the AI has not understood what
it is ! or at least has not explained it helpfully

hmm... sort of

>*Trade-offs:*
> • `s=` (empty): Simpler, but loses selector and algorithm information. With
>multiple signatures (RSA + ed25519), the verifier can’t confirm which
>algorithms were intended. The signing input becomes identical regardless
>of algorithm count.
> • `s=<JSON with empty values>`: Preserves structure. The verifier can
>confirm the signing input included the correct algorithm/selector pairs.
>*Suggested fix:* Provide an explicit byte-for-byte example of the
>incomplete DKIM2-Signature header as it appears in the signing input.

So the issue is that we would rather like the signature to include the
selector values, but because we can have multiple selectors (one for
each of the signatures that are provided) I moved the selector string
into the JSON structure for the message signature and did not realise
that stopped it being signed.

So we will need to provide a JSON structure (with the selector strings
and, why not, the algorithm names) but with no actual signature text. We
then need to base64 encode that, put it into the DKIM2-Signature header
field that is being constructed and then calculate the signature(s).

The simple thing is to have the signature values be absent .. which is
nice and simple. That probably makes the blob invalid JSON but are
people going to do a "check this is valid JSON" step every time they
throw a string at their base64 encoder ??

I will fix this error in -09 (RSN)

>3. Header ordering for duplicates in header hash (Section 5.2) — INTEROP FAILURE
>
>The spec says duplicate headers with the same field name are “placed in the
>order in which they occur in the message header, from the top downwards.”
>Two of three implementations use bottom-to-top (reverse message order).
>On a message with 5 authentication-results headers, both orderings produce
>24 canonicalized headers totalling 2753 bytes but completely different hashes.
>*Suggested fix:* Clarify which direction. Either works as long as all
>implementations agree.

Since implementations will construct (the moral equivalent of) an array
for each header field name in bottom-to-top order (because they will
need this to deal with any recipes) it seems perverse to have another
ordering for the signing algorithm.

So I will change this in -09 (penalising the implementations written by
people who did what they were previously told)


>4. s= tag JSON schema — “items” keyword collision (Section 7)
>
>The signature JSON schema uses `"items"` as both a property name and a JSON
>Schema keyword. Three implementations produced three interpretations:
> 1. `{"items": ["selector", "algorithm", "value"]}` — literal object reading
> 2. `["selector", "rsa", "sig", "selector2", "ed25519", "sig2"]` — flat array
> 3. `[["sel1", "rsa", "<sig>"], ["sel2", "ed25519", "<sig>"]]` — array-of-arrays
>*Suggested fix:* Replace the JSON Schema with a concrete wire format
>example showing the expected structure before and after base64 encoding.
>Array of arrays is most clear in the multi-algorithm case.
>Spec Bugs

Not using a JSON schema runs counter to the rest of the design... and
having a property name clash with a schema reserved word is not wrong
per se...  but it is a dumb name so lets make it "s"

So (without most of the semantic stuff)

{
  "type": "object",
  "properties": {
    "s": {
      "description": "selector, algorithm, value",
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

Also ... there exist online resources that allow you to take a string
and determine what the schema requires

which in this case is

{
  "s": ["selector1", "rsa", "00000"],
  "s": ["selector2", "PQ1", "99999"]
}

For -09 I will change it to use "s"

>5. Typo: “DNS” instead of “DSN” (Section 13)
>
>Line: “If this field is null (“mf=<>”) then a DNS MUST NOT be sent.”
>Should be “DSN”.

it's a fair cop

>6. Numbered list uses “1)” three times (Section 13.1.2)
>
>The three verification steps are all numbered “1)” instead of “1)”, “2)”,
>“3)”.

and that's a markup language issue that is easy to fix

>7. JSON Schemas are not valid JSON Schema (Sections 4, 6, 7)
>
>Several JSON Schemas in the spec are syntactically invalid:

hmm... jsonschema.dev was happy, but jsonlint.com agrees with the AI

I will fix the schemas to be valid (and a slightly more up to date
schema draft as well)

>8. Recipe copy ranges use strings inside JSON (Section 4.1/4.2)
>
>The r= tag value is base64-encoded JSON, but copy ranges within the JSON are
>encoded as parenthetical strings like `"(1-5)"` rather than JSON arrays like
>`[1, 5]`. Since the data is already JSON, embedding a custom string format
>for structured data adds unnecessary parsing complexity.
>*Suggested fix:* Use `[start, end]` JSON arrays for copy ranges:
>`{"b": [[1, 500], "PGEgaHJlZj0i..."]}

fair point

>9. Recipe schema says `"recipes"` type is string (Section 4)
>
>The recipe schema declares `"recipes": { "type": "string" }` but recipes are
>either copy-range expressions or base64-encoded replacement text. The schema
>doesn’t describe the `"(start-end)"` format at all, and doesn’t indicate how
>to distinguish copy ranges from replacement text.
>Clarity Improvements Needed

that goes with point #7 above

>10. Algorithm identifiers (Section 7 / Section 3)
>
>The spec uses short names “rsa” and “ed25519” in the s= tag JSON. This is a
>departure from DKIM1 (RFC 6376) which uses compound names like “rsa-sha256”.
>Using bare key-type names implicitly locks SHA-256 as the only hash, with no
>way to express a different hash without defining entirely new identifiers.
>*Options:*
> • Keep short names but explicitly state SHA-256 is always implied
> • Use compound names like DKIM1 for consistency
> • Either way, define an IANA registry

I will review this, but the compound name would be right ... I think I
paid more attention to the DNS records than I should have at this point

Yes an IANA registry is required (though a DKIM1 registry may suffice)

I did not attempt to put in all the IANA stuff because (as you will see
when looking at the DKIM1 RFC) there is a LOT of verbiage, and while we
are still pinning down the tags it creates twice as much work to update
the document.

>11. Relay mf= update requirement (Section 11.2)
>
>The spec requires d= to match mf= at every hop, and the chain of custody
>requires mf of hop N to match an rt of hop N-1. The implication is that each
>relay MUST update MAIL FROM to its own domain — but this is not stated
>explicitly.

indeed

>*Suggested fix:* Add explicit text stating that when a relay adds a new
>DKIM2-Signature, it MUST set mf= to an address in its own domain (matching
>d=), both for domain alignment and bounce routing.

saying this explicitly doesn't change anything, but I agree that clarity
is helpful (and I get to write another MUST)

>12. Multiple signature items — signing semantics (Section 7/11.5)
>
>When a DKIM2-Signature contains multiple signature items (e.g. RSA +
>ed25519), the spec doesn’t clearly state whether all items sign the same
>signing input or each has its own signing process. This should be stated
>explicitly.

The intent of the text (and all the stuff about s= being absent) is that
you produce the same lump of text for all the signature algorithms to
chew on in parallel and once they are all done then you construct the
JSON blob and stick it into the DKIM2-Signature header field

>13. Signing input and folding relationship (Section 11.5)
>
>The spec describes canonicalization steps that handle folded headers but
>doesn’t explicitly state whether the signer MUST canonicalize its own
>newly-created header before signing. A note clarifying that “the signer MUST
>apply the same canonicalization to its own header before computing the hash”
>would prevent subtle bugs.

agreed -- the current text predates the current split into M-I and DS

>14. Canonicalization worked example needed (Section 11.5)
>
>A worked example showing a folded header before and after canonicalization
>would help implementers verify their code. The interaction between unfolding
>and WSP collapsing can be subtle.

the algorithm is the same as in DKIM1 ... I didn't copy the examples
from the DKIM1 spec because I didn't think they added much

The examples are not in any way a "test suite" that you might use to
prevent code regression or a "torture test" (where the community dreamt
up edge cases and pushed them through every implementation they can
find).

>15. Signing input worked example needed (Section 11.5)
>
>A complete worked example showing a sample message, its MI/DK2 headers, the
>canonicalized signing input (byte-for-byte), and the resulting hash/signature
>would be invaluable. This was the most common source of interop failures.

yes, but does it belong in a specification document ?

>16. m= tag with null MAIL FROM (Section 10/13)
>
>The m= tag is required (Section 10) and `mf=<>` is valid for DSNs
>(Section 13). But the verification behaviour for `mf=<>` is not explicit —
>should the d= vs mf= domain match be skipped? Should the chain of custody
>check be skipped for the DSN hop?

I will review the text to clarify this (but note that you have other
ways of assessing DSNs because you handled the message (and signed it)
on the outward path -- hence custody is less important

>17. IANA Considerations incomplete (Section 16)
>
>Section 16 just says “TBA”.

yes, that means that text needs to be added (and or copied from the
DKIM1 RFC)

>18. EAI and Security Considerations incomplete (Sections 15, 17)
>
>Both sections just say “TBA”.

the former is not going to say very much apart from an indication that
EAI is for consenting adults who know what they are doing (or something
along those line -- it will point to other documents)

I don't think we can write the Security Considerations section until the
design is pretty much stable (because if you come up with a security
issue then we may well fix the protocol rather than write it down as an
issue to be worried about)

>19. Section 12.4 step 2 wording (Section 12.4)
>
>“compute the signatures of the canonical copy” should say “compute the hash
>of the canonical copy, then verify using the public key and signature value”.
>The current wording conflates hashing and signing.

I will fix in -09

It is way too late in my timezone to tackle -09 now, but I hope the
above indicates what it will say where it impacts running code

Thanks for all the detailed comments -- really useful (and I will get my
codebase up to -09 ASAP as well)

- -- 
richard @ highwayman . com                       "Nothing seems the same
                          Still you never see the change from day to day
                                And no-one notices the customs slip away"

-----BEGIN PGP SIGNATURE-----
Version: PGPsdk version 1.7.1

iQA/AwUBabYcF2HfC/FfW545EQK5RwCfeDDCCVc/AKsz/7uN6q8eIhS6jgIAoMPW
ZVFwHzVgpTezEBchGzezR8A8
=qP6G
-----END PGP SIGNATURE-----