Developers

Building DKIM2 into your own software: how to build a signer, how to build a validator, and how to check every Message-Instance in one pass over the body.

Start here

Building a signer

A signer does one of two jobs. It originates a message — the first Message-Instance (m=1) and the first signature (i=1) — or it forwards one, adding the next signature and, if it changed anything, the next Message-Instance.

  1. Verify before you sign. If the message already carries DKIM2 header fields, you are extending a chain of custody: verify it first, and refuse to sign on top of a chain that doesn’t check out. The top Message-Instance may be unsigned (it is yours, about to be signed); everything below must verify. When you originate, or sign over a change to the From, the From must be Authentic for your d=.
  2. Record what you changed. If you changed the message, add a Message-Instance with the new hashes and a Recipe that rebuilds the previous version: a line-based diff for the body, per field name for the headers. Keep it small. We recommend keeping a Recipe to about 100 literal lines — a change bigger than that is a rewrite, not an edit (a recommendation, not part of the specification).
    • A null Recipe ("b": null) says the earlier body cannot be rebuilt. Under -09 that makes the message a PERMERROR downstream. Being worked on: allowing a null Recipe when the hop also changes the From — together with the proposal that a hop making significant changes becomes the message’s author and puts its own From on it (see How it works). Neither is in the specification yet.
  3. Sign the envelope. mf= is the MAIL FROM you send with and rt= the recipients, base64 with their angle brackets; the MAIL FROM domain must be your d= or a subdomain of it. Set f=exploded exactly as -09 §12.5 says: when you send copies of a message you received to more than one address, even if the copies differ. Never set it on i=1.
  4. Fold only where the grammar allows. Folding the two DKIM2 fields can’t change any signature (their signing form drops all whitespace), but the field must still parse: fold after a tag’s ;, inside base64, after a comma in s=, h= or f= (the -09 grammar allows none around rt=’s commas) — never inside a domain, selector or algorithm name. Never re-fold an ordinary header field you received except at whitespace that is already there.
  5. Offer several algorithms at once. s= can carry more than one signature: sign with the old and the new algorithm together (new|old) and receivers use whichever they support.

Operational traps — every one of these has broken real signatures:

Building a validator

Order matters, both for the result you report and for the work you do. Check everything you can from the message itself before you fetch a single key:

  1. Structure. Parse every Message-Instance and DKIM2-Signature; no gaps in m= or i=, no duplicates, no instance above every signature’s m=, no exploded flag on i=1. Check the numbering against the fields you have, not the numbers you were given: with n signatures the i= values must be exactly 1…n, so count up from 1 and stop at the first gap. And refuse more than two ASCII digits before converting — 99 of each is plenty.
  2. Recipes, then hashes, top down. Check the top instance’s hashes against the message as received, then each instance below against the version its parent’s Recipe rebuilds. Below: how to do all of them in one read.
  3. Timestamps. A signature more than 14 days old, or more than a day in the future, fails.
  4. The Chain of Custody, then signatures. Each hop’s mf= domain must relaxed-match an rt= address of the hop before it; when mf= is <>, or the hop before used nd=, compare its d= instead (after an nd=, the next d= must equal it). Every mf= must also be at or below its own d=. Only then fetch keys and verify every signature, not just the newest, each over the fields that existed when it was made.
  5. Authentic From. The From domain is d= or a subdomain of it; it also passes when d= is a subdomain of the From domain, unless that domain’s Domain Policy Record (f=strict) forbids subdomain signing.

The result is one of the five states of -09 §14.1: NONE (no DKIM2 header fields at all), PASS, FAIL, PERMERROR and TEMPERROR (a key lookup that may succeed later). Use the specification’s exact text for a failure — senders debugging their mail depend on it. When a message has more than one fault, our verifiers all report the first one found in this order (a convention, not a requirement of -09). Record the result in Authentication-Results as dkim2= (draft-gondwana-dkim2-authres).

Verifying every instance in one pass

A message that went through three hops carries three Message-Instances, and each one’s body hash covers a different version of the body. The obvious way to check them — the undo walk — rebuilds each earlier body in turn by applying the Recipes, and hashes it. That holds whole copies of the body and reads it once per instance.

All five of our verifiers instead check every instance in one forward read of the body as received, without rebuilding anything. The body can stream straight through: a milter keeps nothing.

The idea: each body is a list of segments

Describe each instance’s body not as text but as a list of segments: runs of lines of the current body (“lines 11–35”) and Recipe literals (a line the Recipe supplies). The top instance is just “every line”. Each instance below gets its list by applying its parent’s Recipe to the parent’s list: a copy range picks a span of the parent’s segments, a literal adds a literal segment. Because -09 requires copy ranges to ascend, every list comes out in body order.

An original 30-line message (m=1); a list adds a 4-line footer (m=2); a gateway adds a banner line at the top and rewrites a link on m=2’s line 9 — line 10 once the banner is added (m=3).

m=3
lines 1–35

m=3’s Recipe: {"b":[{"c":[2,9]},{"d":["line 9 as it was"]},{"c":[11,35]}]}

m=2
2–9 old 9 11–35

m=2’s Recipe: {"b":[{"c":[1,30]}]} (drop the footer)

m=1
2–9 old 9 11–31

lines current-body lines   old 9 a Recipe literal       current lines this instance doesn’t have (the banner, the rewritten line, the footer)

Read lines 1–35 once: each line goes to every instance whose list holds it, each literal when its place is reached. No earlier body is ever built.

The algorithm

# Plan: one segment list per instance, top down.
list[top] = [ current lines 1..end ]
for each instance m from the top down:
    if m's body Recipe is null:  no list below m   # nothing to check
    elif m has a body Recipe:    list[m-1] = compose(list[m], recipe(m))
    else:                        list[m-1] = list[m]  # unchanged body
group instances with equal lists: one digest per group

compose(parent, recipe):
    out = []
    for step in recipe:
        {"d": lines}   -> append LITERAL(lines)
        {"c": [a, b]}  -> append the parts of parent covering
                          its lines a..b (ranges ascend)
    return out

# Hash: one read of the current body.
for each line n, in order:
    for each group:
        emit the literals before n in its list, then line n if it holds it
at the end: emit remaining literals; drop pending blank lines;
            if nothing was hashed, hash one CRLF  # empty body, -09 §6.1

emit(group, line):
    blank     -> group.pending += 1      # may turn out to be trailing
    otherwise -> hash pending blank lines, then the line; pending = 0

The details a port has to get right:

What it buys. A live five-domain chain verifies about 4× faster in every implementation; a 10 MB body takes 7–20 ms across C, Go, JavaScript, Python and Perl; the body itself is never held — only the segment lists, the Recipes’ literals and one digest per group.

Our code. Each implementation keeps the undo walk as its reference and is parity-tested against it on about 4,780 corpus messages:

Testing