A DKIM body-hash failure means the verifier did not reproduce the body hash carried in the signature, after applying the signature's relevant rules. It does not identify which system changed the message, and it is not the same diagnosis as a missing public key.
Start by preserving the original received message. Copying the visible text from a mail client loses MIME structure, encoding and other bytes that matter to verification.
Confirm the exact failure
Inspect the trusted receiver's result and the signature being assessed. A message can have more than one DKIM signature, and each can have a different signing domain or outcome.
Record d=, s=, the algorithm, the c= canonicalization setting and any l= body-length tag. Keep the exact verification reason. A key lookup timeout, an unsupported algorithm, a header-signature mismatch and a body-hash mismatch call for different investigations.
In RFC 6376 §3.5, the bh= value is the encoded hash of the canonicalized body, subject to the defined length treatment. The b= value belongs to the signature calculation. Treating these as interchangeable obscures which check failed.
Preserve evidence that can reproduce the result
Save the raw message through an approved export path and restrict access according to its content. Keep the received original intact, with a hash and collection time if the investigation process supports them.
Create analysis copies separately. Redacting an address, changing an attachment or saving a reconstructed message may alter material relevant to verification. A safe sharing copy can be useful, but it is not automatically equivalent to the preserved original.
Record the source of any verification output. A tool that normalises line endings on import may not be assessing the same bytes as the receiving server. If two tools disagree, first establish their inputs and supported behaviour.
Compare the message before and after likely modifiers
Map the actual route from the sender through gateways, relays, mailing lists and receiving services. Seek controlled captures immediately before and after a suspected transformation.
Common investigation candidates include a footer inserted after signing, URL rewriting, MIME re-encoding, attachment processing and repairs to malformed content. These are hypotheses until evidence places a relevant change at a hop.
Use a controlled test that follows the same route and exercises the suspected feature. For example, compare an otherwise equivalent message with and without the gateway's footer rule. Do not generalise from a direct test that bypasses the production gateway.
In a synthetic case, the sender's stored output verifies successfully, while the captured message after a disclaimer gateway has a body-hash mismatch. The gateway adds a footer after the sender signs. Under those stated hypothetical observations, that identifies a configuration dependency to address, rather than a reason to replace the DKIM public key.
Understand what canonicalization can tolerate
DKIM’s canonicalization rules permit particular normalisations. They do not make arbitrary content editing safe. Relaxed body canonicalization is not permission to rewrite links or add a paragraph after signing.
Inspect the algorithm specified by the signature and use a verifier that implements it correctly. Do not diagnose from a visually identical rendering: two displayed messages can contain different signed octets.
Under RFC 6376 §3.5, an l= value limits the canonicalized body octets covered by the defined calculation. It is not a general fix for a modifying gateway, and deliberately leaving content outside protection changes the security assessment. Use supported configurations and review the implications rather than adding a length limit to suppress a symptom.
Fix the modifying route, then reassess alignment
Where the organisation controls the route, arrange required modifications before the final appropriate signing stage. If a service re-signs mail, check the new signing identity and what it proves. A passing signature from an unrelated intermediary does not automatically align with the original visible From domain; RFC 9989 §4.4.1 requires the authenticated signing identity to align.
For legitimate indirect routes outside the sender's control, assess the applicable interoperability guidance. Do not disable security processing or weaken a domain policy solely because one test fails.
Repeat the affected business workflow and retain before-and-after evidence. Then use DMARC alignment diagnosis to establish whether a passing aligned path remains. The incident closes when the relevant transformation and its effect are understood and the intended route has been verified.
Choose the next diagnostic step
Use this proposed decision sequence; it records no executed test:
- No usable key or key-query timeout: follow the lookup result under RFC 6376 §6.1.2 rather than diagnosing a footer.
- Recomputed body hash differs from bh: compare the body representation, actual c/l settings and recorded bh value under RFC 6376 §6.1.3. A damaged or incorrectly generated bh, or a signer/verifier implementation error, is also a possible cause; the mismatch alone does not prove body modification.
- Body hash matches but the signature fails: inspect signed headers, the signature calculation and the key-to-signer relationship; matching bh alone is not a DKIM pass.
- Multiple signatures disagree: keep each result tied to its own d and s before deciding whether a passing aligned path remains.