Understanding Canonical XML with Comments

Canonical XML with Comments is a specific XML canonicalization (C14N) algorithm variant that normalizes an XML document while intentionally preserving its XML comment nodes. In the context of XML Digital Signatures (XMLDSig), it ensures that comments are treated as integral parts of the signed data, protecting them from tampering. This article explains the technical mechanics of the Canonical XML with Comments variant, its differences from standard canonicalization, and the specific scenarios where it is selected during digital signature generation.

What is Canonical XML with Comments?

XML canonicalization is the process of converting an XML document into a standardized physical representation (a byte stream) to ensure that logically identical XML structures generate identical cryptographic hashes. Standard canonicalization (such as C14N 1.0, C14N 1.1, or Exclusive C14N) resolves syntactic variations such as attribute ordering, namespace prefix redeclarations, character encoding differences, and whitespace within tags.

By default, standard canonicalization algorithms discard all XML comments (<!-- comment -->). The Canonical XML with Comments variant modifies this behavior by retaining comment nodes in their exact relative positions during the normalization process. Common URI identifiers for this variant include:

When is it Selected During Signature Generation?

During XML signature generation, canonicalization can be applied in two places: to the <SignedInfo> block via the <CanonicalizationMethod> element, or to referenced payload data via a <Transform> element. The “with comments” variant is selected in the following circumstances:

1. Legally Binding or Semantically Critical Comments

When an XML document includes comments containing terms of service, legal disclaimers, human-readable contract clauses, or audit metadata, omitting those comments from the cryptographic signature allows third parties to alter or remove them without invalidating the signature. The “with comments” variant is selected to bind the integrity of these annotations directly to the signature.

2. Downstream Systems Rely on Comment Data

If downstream consuming applications parse or execute business logic based on information stored inside XML comments, those comments must not be altered in transit. Selecting canonicalization with comments guarantees that any post-signing modification to those processing notes results in a signature verification failure.

3. Strict Document Integrity Requirements

Certain security profiles and regulatory compliance frameworks require complete bit-level and structural preservation of the original document, including non-executable data. When a policy mandates that the entire document context—down to developer notes or version tags—must remain unaltered, this variant is chosen.

4. Specification or Schema Mandates

Certain vertical industry standards, government submission standards, or web service security specifications explicitly mandate specific canonicalization algorithm URIs. If an interface definition or interoperability profile specifies the #WithComments URI, signing engines must use it to ensure cross-platform signature verification.