Start here
- The specification (draft-ietf-dkim-dkim2-spec-09) is the reference. Everything below follows -09; where this page goes further, it says it is a recommendation or a proposal.
- The implementer guide has the step-by-step detail: tag by tag, the exact error strings, and the APIs of our Perl, Python, Go and C implementations. This page is the overview; the guide is the reference.
- Conformance vectors: Steve Atkins’ dkim2tests, which every verifier in the interop repository is run against, plus that repository’s own fixtures and cross-implementation tests.
- Something to test against: the reflector addresses sign, change, re-sign and bounce mail for you, and the verifiers check what you produce — in your browser or on our server, level by level. Other independent code is on the implementations page.
- Add an
X-DKIM2-Infoheader while you interop (draft-gondwana-dkim2-debug-header): which draft you built, what you did, and which header fields you hashed. It answers the first two questions anyone will ask when your signature doesn’t verify.
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.
- 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, theFrommust be Authentic for yourd=. - 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 aPERMERRORdownstream. Being worked on: allowing a null Recipe when the hop also changes theFrom— together with the proposal that a hop making significant changes becomes the message’s author and puts its ownFromon it (see How it works). Neither is in the specification yet.
- A null Recipe (
- Sign the envelope.
mf=is theMAIL FROMyou send with andrt=the recipients, base64 with their angle brackets; theMAIL FROMdomain must be yourd=or a subdomain of it. Setf=explodedexactly 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 oni=1. - 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 ins=,h=orf=(the -09 grammar allows none aroundrt=’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. - 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:
- The MTA re-encoding the message after you sign
(8bit → 7bit). Turn it off: in Postfix,
disable_mime_output_conversion = yes. - Signing a message that isn’t the one that goes out. Unlike
DKIM, you don’t choose which header fields are signed: DKIM2
hashes them all, apart from trace fields and a few others. So sign
the message exactly as it will go out on the wire — if the
MTA adds a
Delivered-Tofor a pipe-to-command delivery, or strips aBcc, after you sign, the hash no longer matches. - Content filters or list software rewriting the MIME structure after the Recipe was computed.
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:
- Structure. Parse every Message-Instance and
DKIM2-Signature; no gaps in
m=ori=, no duplicates, no instance above every signature’sm=, noexplodedflag oni=1. Check the numbering against the fields you have, not the numbers you were given: with n signatures thei=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. - 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.
- Timestamps. A signature more than 14 days old, or more than a day in the future, fails.
- The Chain of Custody, then signatures. Each
hop’s
mf=domain must relaxed-match anrt=address of the hop before it; whenmf=is<>, or the hop before usednd=, compare itsd=instead (after annd=, the nextd=must equal it). Everymf=must also be at or below its ownd=. Only then fetch keys and verify every signature, not just the newest, each over the fields that existed when it was made. - Authentic
From. TheFromdomain isd=or a subdomain of it; it also passes whend=is a subdomain of theFromdomain, 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’s Recipe: {"b":[{"c":[2,9]},{"d":["line 9 as it was"]},{"c":[11,35]}]}
m=2’s Recipe: {"b":[{"c":[1,30]}]} (drop the footer)
lines current-body lines old 9 a Recipe literal current lines this instance doesn’t have (the banner, the rewritten line, the footer)
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:
- Trailing blank lines. -09 §6.1 does not hash blank lines at the end of a body, and you can’t know a blank line is trailing until something follows it or the body ends. Count them per group as pending; hash them when a non-blank line or literal arrives; drop them at the end. A body that is empty or all blank still hashes one CRLF.
- Shared digests. Instances with no body Recipe have the same body as their parent, so they share one list and one set of digests. Most chains hash the body once or twice, however many hops there were.
- Copy ranges past the end. A Recipe that names a
line the body doesn’t have is invalid: an instant
PERMERROR. Streaming, you learn the body is short when it ends. - Line endings. A bare LF ends a line as CRLF does, as the Recipes number lines, and lines are hashed as CRLF; a last line with no line ending is still a line.
- Headers work the same way, per field name: each instance has, for each name, a list of that name’s values as received (numbered bottom-up, as Recipes number them) and of literals. Split the fields once, canonicalize a value only if its name is hashed, once; a name no Recipe touched is shared.
- Prefetch the keys. At the end of the headers
you know every
selector._domainkey.domainyou will need: start those lookups in the background while the body streams, top signature first. The names come from the message, so bound how many you start, for DoS protection (we chose 8). Use the definitive answers; if one hasn’t answered when you need it (we wait 1 s in Perl, 5 s elsewhere) or failed temporarily, do it again then. Look each name up once per message.
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:
- Perl:
perl/lib/Mail/DKIM2/BodyPlan.pmandHeaderPlan.pm - Go:
go/dkim2/plan.go - C:
c/dkim2_plan.c - Python:
python/dkim2plan.py - JavaScript (the browser verifier):
deploy/www/verify/plan.js
Testing
- Run Steve Atkins’ dkim2tests vectors against your verifier; every verifier in the interop repository passes them.
- Send mail from your signer through the reflector addresses: each one changes the message in a known way and re-signs it, so you see your chain extended by someone else’s code.
- Paste the results into the verifiers — in your browser or on our server — for a level-by-level breakdown.
- The interop repository cross-tests every signer against every verifier; add yours and run the matrix.