Canonicalization of Messages for Digital Signature Manifests

In Chapter 4 on XML Signature, we briefly discussed a complex concept called canonicalization . As you recall, canonicalization of message text prior to applying a digital signature is critical because signature verification will fail if any changes occur to the message through "normal" XML processing as it moves from one node in a Web service network to another. The following sections discuss some of the detailed steps used in canonicalization. You can find even more details in the definitive reference for Canonical XML version 1.0 at http://www.w3.org/TR/2001/REC-xml-c14n-20010315.

Canonicalization V1 Transform Steps

The following is a list of the transformations that occur to an XML document when it goes through a Canonical XML version 1.0 transform:

• The document is encoded in UTF-8.

• Line breaks are normalized to #xA on input, before parsing.

• Attribute values are normalized, as if by a validating processor.

• Character and parsed entity references are replaced .

• CDATA sections are replaced with their character content.

• The XML declaration and Document Type Definition (DTD) are removed.

• Empty elements are converted to start-end tag pairs.

• Whitespace outside the document element and within start and end tags is normalized.

• All whitespace in character content is retained (excluding characters removed during line-feed normalization).

• Attribute value delimiters are set to quotation marks (double quotes).

• Special characters in attribute values and character content are replaced by character references.

• Superfluous namespace declarations are removed from each element.

• Default attributes are added to each element.

• Lexicographic order is imposed on the namespace declarations and attributes of each element.

Canonicalization Subtleties: Exclusive Canonicalization

Although the concept of standardizing the XML before digesting and before verifying is reasonably simple, complex subtleties arise in some specific situations. One of the subtleties became a significant issue upon the creation of practical implementations of XML Signing. It came up when applying XML Signing to fragments of XML within a larger XML document, which is the predominant scenario in Web services using SOAP. The issue was primarily related to namespaces. Per the XML Canonicalization version 1.0 specification, namespaces are to be propagated down to all their descendents. This makes sense because, in the context of a document, these namespaces are implicit, so making them explicit seems to be a reasonable strategy. However, removing an XML fragment from the context of a document ”as in the case of SOAP when you have an XML payload within the overall document ”can cause significant problems.

This issue resulted in the creation of a new canonicalization algorithm called Exclusive Canonicalization (http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/). This canonicalization method strives to "exclude ancestor context" as much as is practical. It primarily does so by not propagating the ancestor namespaces down to the children nodes. It turns out that this canonicalization approach is the most practical in most circumstances and the one that you should use. As Donald Eastlake points out in his book Secure XML (Addison-Wesley, 2003, p. 218), "Almost all CanonicalizationMethod elements should specify Exclusive XML Canonicalization."

The extensibility of the canonicalization method is a tribute to the XML Signature working group and is what made the advent of the Exclusive canonicalization method possible. Custom canonicalization methods are also possible; however, you should be extremely careful about using one because the canonicalization algorithm modifies the XML to be signed and is verified in a way that is difficult to see. It would not be difficult for a canonicalization algorithm to modify the XML, for example, to have all signatures verify correctly.