XML Signature Digest Mismatch Explained: Canonicalization, Transforms and Hash Failures

Overview

A digest mismatch means the verifier hashed different bytes

Each ds:Reference records a digest for one selected data object. To validate it, the verifier resolves the URI, applies the declared transforms in order, converts the result to an octet stream, calculates the configured digest and compares it with ds:DigestValue.^[1]

If the values differ, Reference validation fails. Certificate validity is a separate question and does not change the bytes used for this digest.

Visually similar XML can produce different canonical bytes because the selected node, namespace context, text nodes, attributes, transforms, algorithm parameters, or parsing history changed. Conversely, different source serialisations can sometimes canonicalize to the same bytes.

Validation layers

DigestValue, SignatureValue and certificate trust are different checks

A valid Reference digest does not establish signer identity. A valid SignatureValue does not prove the certificate is trusted. A trusted certificate cannot rescue a digest mismatch caused by altered content.

Reference processing

Reproduce the digest in the verifier's order

1. Read the Reference URI. Determine whether it identifies the whole document, a same-document ID, or an external resource supported by the profile.
2. Resolve exactly one intended target. A short URI such as #Body-123 must not ambiguously match multiple ID-style attributes.
3. Apply every declared Transform in document order. The output of one transform becomes the input to the next.
4. Obtain the final octet stream. When the transform chain ends in a node-set, canonicalization is needed before hashing. The effective canonicalization may be explicit or determined by XMLDSig processing rules.
5. Hash the resulting bytes. Use the exact algorithm URI in ds:DigestMethod.
6. Compare the digest value. Base64-encode the calculated digest bytes and compare the result with ds:DigestValue, or decode ds:DigestValue and compare the raw bytes.

Reference URI
  → resolved data object
  → Transform 1
  → Transform 2
  → canonical or other final octets
  → DigestMethod
  → digest bytes
  → Base64 text in DigestValue

Do not hash the visible Base64 characters from DigestValue. That element stores a Base64 representation of the already-calculated digest bytes.

Canonicalization

Canonical XML creates a defined physical representation

Canonicalization does not simply remove whitespace or “standardise formatting.” It serializes an XML node-set according to a specific algorithm. Canonical XML 1.1 includes rules such as UTF-8 output, line-break normalization before parsing, replacement of character and parsed entity references, expansion of empty elements into start/end pairs, preservation of character-content whitespace, and ordered namespace declarations and attributes.^[2]

Inclusive versus exclusive canonicalization

Inclusive Canonical XML can carry ancestor namespace and selected xml: context into a canonicalized subdocument. Exclusive XML Canonicalization was designed to reduce the effect of omitted ancestor context when signed XML is moved between envelopes or protocol layers.^[3]

Exclusive canonicalization can also include an InclusiveNamespaces PrefixList. Omitting a required prefix, adding an unexpected prefix, or using a different default-namespace treatment can alter the canonical output even when the element text looks unchanged.

Transforms and targets

A different target or transform chain normally produces a different digest

The ds:Reference identifies what is signed; it does not automatically mean “the SOAP Body” or “the visible clinical document.” Verify the resolved node path and ID value rather than relying on the element's apparent purpose.

Enveloped-signature transform

When a signature is embedded inside the content it signs, the enveloped-signature transform removes the relevant ds:Signature element from that Reference's input. If only one side removes it, the digest inputs differ and Reference validation fails.

Duplicate and unrecognised IDs

XMLDSig relates same-document data to signatures through fragment identifiers and warns that ID collisions must be avoided.^[1] SOAP and WS-Security implementations may recognise wsu:Id, schema-typed IDs, xml:id, or application-specific attributes differently. A secure verifier should resolve the intended target unambiguously and verify that the application consumes that same signed node.

Worked examples

Three common ways the canonical bytes diverge

1. Apostrophe entity versus double-escaped entity text

Same parsed character value
<familyName>O'BRIEN</familyName>
<familyName>O&apos;BRIEN</familyName>

Different parsed character value
<familyName>O&amp;apos;BRIEN</familyName>

The first two forms parse to the text value O'BRIEN and normally canonicalize equivalently. The third parses to the literal text O'BRIEN. Its ampersand must remain escaped in canonical XML, so the canonical bytes differ.

2. Formatting whitespace becomes signed character data

Before signing
<patient><id value="123"/><name>SAMPLE</name></patient>

After pretty-printing
<patient>
  <id value="123"/>
  <name>SAMPLE</name>
</patient>

The line breaks and indentation between child elements can become text nodes. Canonicalization does not generally delete that character-content whitespace, so pretty-printing after signing can invalidate the Reference.

3. A namespace is inherited in one context but not another

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:app="urn:example:app">
  <soap:Body wsu:Id="body-1" xmlns:wsu="urn:example:wssecurity-utility">
    <app:Request>...</app:Request>
  </soap:Body>
</soap:Envelope>

Canonicalizing only the Body can produce different namespace output depending on the algorithm, visible prefix use, inclusive-prefix parameters, and whether the Body is processed in its original ancestor context. Compare canonical output, not merely namespace declarations physically written on the target element.

Failure patterns

Common causes of a Reference digest mismatch

Troubleshooting

A repeatable digest-mismatch investigation

1. Capture the exact verifier input. Preserve the received XML bytes before any pretty-printing, normalisation, logging redaction, or object mapping.
2. Identify the failing Reference. Record its URI, DigestMethod, DigestValue and every Transform.
3. Resolve the target explicitly. Report the element path, ID attribute and number of matches.
4. Apply transforms one at a time. Save the intermediate node-set or octets after each step.
5. Display canonical output and UTF-8 bytes. Compare namespace declarations, text nodes, attributes and algorithm parameters with the signer.
6. Calculate the digest independently. Compare the raw digest bytes and Base64 representation.
7. Compare the signing and sending boundaries. Find any serializer, DOM mutation, SOAP library, security handler or transport filter that runs after digest calculation.
8. Only then inspect SignatureValue. Once all Reference digests match, verify canonicalized SignedInfo with the declared SignatureMethod and selected public key.

The XML Signature Digest & Canonicalization Inspector exposes supported Reference targets, canonical XML, UTF-8 bytes, calculated digests, SignedInfo and SignatureValue verification in this order.

The local calculation matches, but the remote service rejects it

Confirm both sides recognise the same ID attributes and transforms. Compare the literal transmitted XML rather than the local pre-send object. SOAP libraries may add namespaces, regenerate prefixes, alter security headers, normalise character encoding, or rebuild the envelope after custom signing code has already calculated its digest.

Only one Reference fails

Focus on that Reference's target and transforms. Multiple References share the SignedInfo signature but can protect different elements with different transform chains. A correct Timestamp digest does not prove the Body digest input is correct.

Every digest passes, but SignatureValue fails

Every Reference matches its recorded DigestValue. Move the investigation to canonicalized SignedInfo, its CanonicalizationMethod, SignatureMethod, decoded SignatureValue and verification key. Do not keep changing the signed Body when its digest already matches.

After the digest

SignatureValue covers SignedInfo rather than the XML document directly

ds:SignedInfo contains the canonicalization method, signature method and one or more References with their digest values. The signer canonicalizes SignedInfo and signs those bytes. This indirectly binds the signature to every Reference digest.

Referenced XML → transforms → digest → DigestValue inside SignedInfo
SignedInfo → canonicalization → SignatureMethod → SignatureValue

If SignatureValue verifies, the signature over canonicalized SignedInfo is valid for the selected public key. Whether that key belongs to an acceptable signer remains a separate policy decision involving certificate chains, validity periods, revocation, key usage, identity and transaction-specific authorisation. The Certificate Decoder can help inspect certificate structure, but it is not a substitute for a complete trust-policy validator.

Checklist

What to define and log in an XML Signature implementation

• Supported Reference URI forms and which attributes are registered as IDs.
• Duplicate-ID rejection and signed-node/application-node binding rules.
• Permitted transforms, canonicalization algorithms and InclusiveNamespaces parameters.
• Digest and signature algorithms permitted by the profile.
• The exact point in processing where the final envelope becomes immutable.
• Character encoding and XML parser/serializer behaviour.
• Whether intermediary systems may add or change unsigned envelope content.
• Safe diagnostic logging of Reference URI, algorithms, target path and calculated digest.
• Protection against logging patient data, credentials, private keys or complete confidential XML.
• Certificate-chain, revocation, identity and authorisation requirements after cryptographic verification.

Primary references

XML Signature and canonicalization standards

1. W3C XML Signature Syntax and Processing Version 1.1 — Reference processing, DigestValue, SignedInfo, SignatureValue, algorithms and same-document references.
2. W3C Canonical XML Version 1.1 — canonical serialization rules for XML documents and document subsets.
3. W3C Exclusive XML Canonicalization Version 1.0 — reduced ancestor-context handling and InclusiveNamespaces PrefixList behaviour.
4. W3C XML 1.0, Fifth Edition — XML parsing, entities, attributes, IDs and well-formedness rules.
5. W3C XML Signature Best Practices — implementation guidance, signed-content visibility and wrapping-risk considerations.

SOAP, WS-Security, CDA, national infrastructure and vendor profiles can impose narrower algorithms, ID conventions and trust requirements. Follow the profile governing the actual transaction.