In DKIM, what exactly do the simple and relaxed canonicalization algorithms change for header fields and for the message body?
answer
- names, not values
- unfold, then collapse whitespace
- trim at colon and line end
- trailing empty lines both ways
- relaxed body: line-end whitespace
basics
~20 sSimple hashes headers byte for byte; relaxed lowercases field names, unfolds lines, collapses whitespace runs to one space and trims it at the colon and value end. Both body algorithms drop trailing empty lines; relaxed also strips line-end whitespace and collapses runs.
solid answer
~40 sFor headers, `simple` changes nothing: name case and every space count. `relaxed` applies five steps in order: lowercase the field name (not the value), unfold continuation lines, reduce each run of spaces and tabs to one space, delete whitespace at the end of the value, and delete whitespace around the colon. For the body, `simple` only reduces any run of empty lines at the end to a single CRLF, and an empty body becomes one CRLF. `relaxed` additionally drops whitespace at the end of each line and reduces runs of whitespace inside a line to one space, then ignores trailing empty lines; an empty body becomes zero octets. Neither algorithm touches header values' case, words, line breaks inside the body or the transfer encoding.
go deeper
Recall the headline: simple hashes headers as they are, relaxed lowercases names and normalises whitespace and folding; both body algorithms ignore trailing empty lines.
Walk through the five relaxed header steps in order and the two relaxed body steps, including that leading indentation shrinks to one space rather than vanishing.
Map a transit change to the half it hits: re-folding and name case break simple headers, line-end spaces break simple bodies, changed characters break everything.
Weigh relaxed's survival on lists and gateways against section 8.1's re-spacing concern, and decide per mail stream which body algorithm the domain signs with.
## Two algorithms, two halves RFC 6376 (September 2011) section 3.4 defines a `simple` and a `relaxed` algorithm for the header and, separately, for the body. The signer records its pair in the `c=` tag, header first. Both algorithms assume the message is already in network form: ASCII text with lines ending in CRLF. **WSP** below means a space or a horizontal tab. ## Header canonicalization **`simple`** (section 3.4.1) does not change header fields at all. Field names MUST NOT be case folded and whitespace MUST NOT be changed. `Subject: Hello` and `SUBJECT: Hello` hash differently, and so does a field that a relay rewraps onto two lines. **`relaxed`** (section 3.4.2) MUST apply these steps in order: 1. Convert every header field **name** to lowercase. The value keeps its case: `SUBJect: AbC` starts becoming `subject: AbC`. 2. **Unfold** continuation lines: a CRLF followed by WSP inside a value is read without the CRLF. The CRLF that ends the field stays. 3. Reduce every sequence of one or more WSP characters to a **single space**, including whitespace either side of a former fold. 4. Delete WSP at the **end** of each unfolded value. 5. Delete WSP **before and after the colon**; the colon itself stays. `SUBJect: AbC` ends as `subject:AbC`. So relaxed absorbs re-folding, tab-for-space swaps, extra spaces and changes to the case of a field name. It does not absorb any change to the characters of a value. ## Body canonicalization **`simple`** (section 3.4.3) ignores all empty lines at the end of the body, converting any run of trailing CRLFs to a single CRLF. If there is no body, or no CRLF at its end, one CRLF is added, so an empty body canonicalizes to two octets. It makes no other change. **`relaxed`** (section 3.4.4) MUST apply two steps in order: 1. Reduce whitespace: ignore all whitespace at the **end of each line** (keeping the CRLF), and reduce each run of WSP **within a line** to one space. Indentation at the start of a line therefore becomes a single space; it is not removed. 2. Ignore all empty lines at the end of the body. A non-empty body without a final CRLF gets one. An empty body canonicalizes to **zero octets**, which is why the RFC lists a different empty-body hash for each algorithm. ## A worked example RFC 6376 section 3.4.5 canonicalizes this message, written with `<SP>`, `<HTAB>` and `<CRLF>` markers: ```pseudocode input: A: <SP> X <CRLF> B <SP> : <SP> Y <HTAB><CRLF> <HTAB> Z <SP><SP><CRLF> <CRLF> <SP> C <SP><CRLF> D <SP><HTAB><SP> E <CRLF> <CRLF> <CRLF> relaxed header: a:X <CRLF> b:Y <SP> Z <CRLF> relaxed body: <SP> C <CRLF> D <SP> E <CRLF> simple body: <SP> C <SP><CRLF> D <SP><HTAB><SP> E <CRLF> ``` The relaxed header lowercased `A` and `B`, removed the spaces around the colons, unfolded `B` and joined `Y` and `Z` with one space. The relaxed body kept the leading space before `C` as one space, dropped the trailing space after it and collapsed the space-tab-space run between `D` and `E`. Both body algorithms dropped the two trailing empty lines. ## What each algorithm absorbs | Change in transit | simple header | relaxed header | simple body | relaxed body | |---|---|---|---|---| | Field name case changed | breaks | survives | n/a | n/a | | Header line re-folded | breaks | survives | n/a | n/a | | Spaces added at a line end | breaks | survives | breaks | survives | | Empty lines added at the end | n/a | n/a | survives | survives | | Whitespace run collapsed | breaks | survives | breaks | survives | | A word or value character changed | breaks | breaks | breaks | breaks | | Non-empty line appended | n/a | n/a | breaks | breaks | ## Choosing between them - `relaxed` survives more relays, which makes `c=relaxed/relaxed` a common choice. - RFC 6376 section 8.1 notes that relaxed body canonicalization could allow crude "ASCII art" changes made purely by re-spacing words, and says `simple` should be used where that is a concern. - Section 5.4.1 suggests receipts that nothing should modify suit `simple`, and person-to-person mail suits `relaxed`.
- Why does an empty body produce a different DKIM body hash under simple and relaxed?Simple canonicalizes an empty or missing body to a single CRLF, two octets, while relaxed canonicalizes it to zero octets. The hash inputs differ, so RFC 6376 sections 3.4.3 and 3.4.4 list a separate empty-body SHA-256 value for each algorithm.
- DKIM matches h= names case-insensitively, so why does simple header canonicalization still break on a name-case change?Matching which fields to sign and hashing them are separate steps. RFC 6376 section 6.1.3 matches h= names against the header case-insensitively, but simple then hashes the field exactly as written, name case included, so SUBJECT: and Subject: produce different hash input.
- Why might a signer deliberately choose simple body canonicalization?Simple refuses whitespace changes inside lines. RFC 6376 section 8.1 warns that relaxed body canonicalization could let someone convey a different message purely by re-spacing words, and section 5.4.1 suggests messages that nothing should modify, such as receipts, suit simple.
- Relaxed canonicalization lowercases header values too, so value case changes are harmless.
- Simple body canonicalization keeps trailing empty lines exactly as sent.
- Relaxed body canonicalization removes all indentation at the start of lines.
- Relaxed header canonicalization tolerates any edit that keeps the meaning.
- Simple header canonicalization ignores name case because header names are case-insensitive.