W3C

Exclusive XML Canonicalization
Version 1.0

W3C Working Draft xxx October 2001

This version:
http://www.w3.org/Signature/Drafts/xml-exc-c14n
Latest version:
http://www.w3.org/TR/xml-exc-c14n
Previous version:
n/a
Authors/Editors:
Donald E. Eastlake 3rd, Motorola, Donald.Eastlake@Motorola.com
John Boyer, PureEdge Solutions Inc., jboyer@PureEdge.com

Abstract

Canonical XML [XML-C14N] recommends a standard means of serializing XML that, when applied to a subdocument, includes its namespace and some other XML context. However, for many applications, it is desirable to have a method which, to the extent practical, excludes such context from a canonicalized subdocument. In particular, where a digital signature over an XML subdocument is needed which will not break when that subdocument is removed from its original document and/or inserted into a different context. The Exclusive XML Canonicalization method described herein provides such a method.

Status of this document

This is an editors' copy with no standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document has been produced by the IETF/W3C XML Signature Working Group, (see also W3C XML Signature Activity Statement). This is the first public version, as this specification is expected to be advanced quickly, immediate comments and implementation experience are welcome.

Please report errors in this document to the editors and cc: the public email list w3c-ietf-xmldsig@w3.org.

A list of all current W3C Technical Reports can be found at http://www.w3.org/TR.

Table of Contents

  1. Introduction
    1. Terminology
    2. Applications
    3. Limitations
  2. The Need for Exclusive XML Canonicalization
    1. A Simple Example
    2. General Problems with Enveloping and de-Enveloping
    3. Requirement for Uniform Processing
  3. Specification of Exclusive XML Canonicalization
  4. Use in XML Security
  5. References
  6. Acknowledgements

1. Introduction

The XML Recommendation [XML] specifies the syntax of a class of objects called XML documents. The Namespaces in XML Recommendation [Names] specifies additional syntax and semantics for XML documents. It is normal for XML documents and subdocuments which are equivalent for the purposes of many applications to differ in their physical representation. For example, they may differ in their entity structure, attribute ordering, and character encoding. The goal of this specification is to establish a method for serializing an XPath node set representing a subdocument such that this method has the following properties:

  1. It is minimally affected by the XML context of the subdocument.
  2. If the input represents a well-formed XML document, then the output will be a well-formed XML document which will be unaltered by further applications of exclusive canonicalization.
  3. So far as practical, it can be determined whether two subdocuments are identical, or whether an application has not changed a subdocument, except for insignificant transformations permitted by XML 1.0 and Namespaces in XML, by comparing their exclusive canonicalization.

Complete familiarity with the Canonical XML Recommendation [XML-C14N] is assumed.

1.1 Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [Keywords].

The XPath 1.0 Recommendation [XPath] defines the term node-set and specifies a data model for representing an input XML document as a set of nodes of various types (element, attribute, namespace, text, comment, processing instruction, and root). The nodes are included in or excluded from a node-set based on the evaluation of an expression. Within this specification and [XML-C14N], a node-set is used to directly indicate whether or not each node should be rendered in the canonical form (in this sense, it is used as a formal mathematical set). A node that is excluded from the set is not rendered in the canonical form being generated, even if its parent node is included in the node-set. However, an omitted node may still impact the rendering of its descendants (e.g. by affecting the namespace context of the descendants).

A document subset is a portion of an XML document indicated by an XPath node-set that may not include all of the nodes in the document. An apex node is an element node in a document subset having no element node ancestor in the document subset. An orphan node is a node whose parent element node is not in the document subset. The output parent of an orphan node that is not an apex node is the nearest ancestor element of the orphan node that is in the document subset. The output parent of a non-orphan node is the parent of the node.

An element E in a document subset visibly utilizes a namespace declaration, i.e. a namespace prefix P and bound value V, if E or an attribute node in the document subset with parent E has a qualified name in which P is the namespace prefix and V is the namespace name. A similar definition applies for an element E in a document subset that visibly utilizes the default namespace declaration, which occurs if E has no namespace prefix.

The namespace axis of an element contains nodes for all namespace declarations made within the element as well as namespace declarations inherited from ancestors of the element. Any subset of the nodes in a namespace axis can be included in a document subset.

The method of canonicalization described in this specification receives an InclusiveNamespacePrefix List parameter, which lists namespace prefixes that are handled in the manner described by the Canonical XML Recommendation [XML-C14N].

The exclusive canonical form of a document subset is a physical representation of the XPath node-set, that is an octet sequence, produced by the method described in this specification. It is as defined in the Canonical XML Recommendation [XML-C14N] except for the changes summarized as follows:

The term exclusive canonical XML refers to XML that is in exclusive canonical form. The exclusive XML canonicalization method is the algorithm defined by this specification that generates the exclusive canonical form of a given XML document subset. The term exclusive XML canonicalization refers to the process of applying the exclusive XML canonicalization method to an XML document subset.

1.2 Applications

The applications of Exclusive XML Canonicalization are very similar to those for Canonical XML [XML-C14N]. However, exclusive canonicalization, or equivalent means of excluding most XML context, is necessary for signature applications where the XML context of signed XML will change. This sort of change is typical of many protocol applications.

Note that in the case of the SignedInfo element of [XML-DSIG], the specification of an appropriate canonicalization method is the only technique available to protect the signature from insignificant changes in physical form and changes in XML context.

1.3 Limitations

Exclusive XML Canonicalization has the limitations of Canonical XML [XML-C14N] plus two additional limitations as follows:

  1. The XML being canonicalized may depend on the effect of xml namespace attributes, such as xml:lang and xml:space, appearing in ancestor nodes. To avoid problems due to the non-importation of such attributes into an enveloped document subset, either they must be explicitly given in the apex nodes of the XML document subset being canonicalized or they must always be declared with an equivalent value in every context in which the XML document subset will be interpreted.
  2. The XML being canonicalized may depend on the effect of XML namespace declarations where the namespace prefix being bound is not visibly utilized. An example would be an attribute whose value is an XPath expression and whose evaluation therefore depends upon namespace prefixes referenced in the expression. To avoid problems with such namespace declarations,

2. The Need for Exclusive XML Canonicalization

In some cases, particularly for signed XML in protocol applications, there is a need to canonicalize a subdocument in such a way that it is substantially independent of its XML context. This is because, in protocol applications, it is common to envelope XML in various layers of message or transport elements, to strip off such enveloping, and to construct new protocol messages, parts of which were extracted from different messages previously received. If the pieces of XML in question are signed, they needs to be canonicalized in a way such that these operations do not break the signature but the signature still provides as much security as can be practically obtained.

2.1 A Simple Example

As a simple example of the type of problem that changes in XML context can cause for signatures, consider the following two documents, the second of which is the first enveloped:

   <n1:elem1 xmlns:n1="http://b.example">
       content
   </n1:elem1>
   <n0:pdu xmlns:n0="http://a.example">
      <n1:elem1 xmlns:n1="http://b.example">
          content
      </n1:elem1>
   </n0:pdu>

The first document above is in canonical form. But assume that document is enveloped as in the second case. The subdocument with elem1 as its apex node can be extracted from this second case with an XPath expression such as

 (//. |  //@* | //namespace::*)[ancestor-or-self::elem1]

The result of applying Canonical XML to the resulting XPath node set is the following (except for line wrapping to fit this document):

   <n1:elem1 xmlns:n0="http://a.example"
             xmlns:n1="http://b.example">
       content
   </n1:elem1>

Note that the n0 namespace has been included by Canonical XML because it includes namespace context. This change which would break a signature over elem1 based on the first version.

2.2 General Problems with re-Enveloping

As a more complete example of the changes in canonical form that can occur when the enveloping context of a document subset is changed, consider the following document:

   <n0:local xmlns:n0="foo:bar"
             xmlns:n3="ftp://example.org">
      <n1:elem2 xmlns:n1="http://example.net"
                xml:lang="en">
          <n3:stuff xmlns:n3="ftp://example.org"/>
      </n1:elem2>
   </n0:local>

And the following which has been produced by changing the enveloping of elem2:

   <n2:pdu xmlns:n1="http://example.com"
           xmlns:n2="http://foo.example"
           xml:lang="fr"
           xml:space="retain">
      <n1:elem2 xmlns:n1="http://example.net"
                xml:lang="en">
          <n3:stuff xmlns:n3="ftp://example.org"/>
      </n1:elem2>
   </n2:pdu>

Assume an XPath node set produced from each case by applying the following XPath expression

 (//. | //@* | //namespace::*)[ancestor-or-self::elem2]

Applying Canonical XML to the node set produced from the first document yields the following serialization (except for line wrapping to fit in this document):

   <n1:elem2 xmlns:n0="foo:bar"
             xmlns:n1="http://example.net"
             xmlns:n3="ftp://example.org"
             xml:lang="en">
       <ns3:stuff></ns3:stuff>
   </n1:elem2>

However, although elem2 is represented by the same octet sequence in both pieces of external XML above, the Canonical XML version of elem2 from the second case would be (except for line wrapping so it will fit into this document) as follows:

   <n1:elem2 xmlns:n1="http://example.net"
             xmlns:n2="http://foo.example"
             xml:lang="en"
             xml:space="retain">
       <n3:stuff xmlns:n3="ftp://example.org"></n3:stuff>
   </n1:elem2>

Note that the change in context has resulted in lots of changes in the subdocument as serialized by the inclusive Canonical XML [XML-C14N]. In the first example, n0 had been included from the context and the presence of an identical n3 namespace declaration in the context had elevated that declaration to the apex of the canonicalized form. In the second example, n0 has gone away but n2 has appeared, n3 is no longer elevated, and an xml:space declaration has appeared, due to changes in context. But not all context changes have effect. In the second example, the presence at ancestor nodes of an xml:lang and n1 prefix namespace declaration have no effect because of existing declarations at the elem2 node.

On the other hand, using Exclusive XML Canonicalization as specified herein, the physical form of elem2 as extracted by the XPath expression above is (except for line wrapping so it will fit into this document) as follows:

   <n1:elem2 xmlns:n1="http://example.net"
             xml:lang="en">
       <n3:stuff xmlns:n3="ftp://example.org"/>
   </n1:elem2>

in both cases.

3. Specification of Exclusive XML Canonicalization

The data model, processing, input parameters, and output data for Exclusive XML Canonicalization are the same as for Canonical XML [XML-C14N] with the following exceptions:

  1. Canonical XML applied to a document subset requires the search of the ancestor nodes of each orphan element node for attributes in the xml namespace, such as xml:lang and xml:space. These are copied into the element node except if a declaration of the same attribute is already in the attribute axis of the element (whether or not it is included in the document subset). This search and copying are omitted from the Exclusive XML Canonicalization method.
  2. The Exclusive XML Canonicalization method may receive an additional, possibly null parameter InclusiveNamespacePrefix List containing a white space separated list of namespace prefixes. All namespace uses and declarations with prefixes appearing on this list are handled as provided in Canonical XML [XML-C14N]
  3. For namespace prefixes not appearing on the InclusiveNamespacesPrefix List, a namespace declaration is output at every output element where that prefix is visibly used unless such a declaration is unnecessary due to the appearance of such a declaration at an ancestor output node

One method for implementing the Exclusive XML Canonicalization method is as follows:

  1. Do a root down recursive pass over the entire XPath node-set to which the document subset selection was applied in document order. The operation of copying ancestor xml: namespace attributes into output apex elements is NOT done.
  2. Maintain a stack of what namespace declarations present at ancestor nodes affect will each element. For Namespace declarations whose prefix is in the InclusiveNamespacePrefix List, the declaration is always added to the stack. Other namespace declarations are only added to the stack if they are visibly used at an output node.
  3. Process nodes to produce output as specified in Canonical XML except for Namespace nodes.
  4. For Namespace nodes whose prefix is on the InclusiveNamespacePrefix List, always include the namespace declaration, taken from that element if present or from the stack maintained as above if not present at the element, for that prefix on output apex elements. For non-apex output elements, output Namespace declarations for prefixes on the InclusiveNamespacePrefix List if and only if a Namespace node for that prefix is present at the element and there is no declaration on the stack or a declaration for that prefix with a different value on the stack.
  5. For Namespace nodes whose prefix is not on the InclusiveNamespacePrefix List, output a namespace declaration at an element only if that prefix is visibly used at that element and is not already on the stack.

4. Use in XML Security

Exclusive Canonicalization may be used as a Transform or CanonicalizationMethod algorithm in XML Digital Signature [XML-DSig] and XML Encryption [XML-Enc].

Identifier:
http://www.w3.org/TR/2001/xml-exc-c14n.html

This algorithm takes an optional explicit parameter of an empty InclusiveNamespacePrefix element with a List attribute. The value of this attribute, which may be null, is the list of namespace prefixes to be handled as per Canonical XML. The list is in NMTOKENS format (a white space separated list). An example is as follows:

   <Transform
      Algorithm="http://www.w3.org/TR/2001/xml-exc-c14n.html">
      <InclusiveNamespacePrefix List="foo bar"/>
   </Transform>

The schema for InclusiveNamespacePrefix is as follows:

   Schema Definition:
   <element name="InclusiveNamespacePrefix"
            type="InclusiveNamespacePrefixType>
   <comlexType name="InclusiveNamespacePrefix">
      <attribute name="List" type="NMTOKENS">
   </complexType>
   DTD:
   <!ELEMENT InclusiveNamespacePrefix    EMPTY >
   <!ATTLIST InclusiveNamespacePrefix
      List    NMTOKENS    #REQUIRED >

5. References

Keywords
Key words for use in RFCs to Indicate Requirement Levels , IETF RFC 2119. S. Bradner. March 1997. http://www.ietf.org/rfc/rfc2119.txt.
Namespaces
Namespaces in XML , W3C Recommendation. eds. Tim Bray, Dave Hollander, and Andrew Layman. http://www.w3.org/TR/1999/REC-xml-names-19990114 .
URI
Uniform Resource Identifiers (URI): Generic Syntax , IETF RFC 2396. T. Berners-Lee, R. Fielding, L. Masinter. August 1998 http://www.ietf.org/rfc/rfc2396.txt.
XML
Extensible Markup Language (XML) 1.0 (Second Edition) , W3C Recommendation. eds. Tim Bray, Jean Paoli, C. M. Sperberg-McQueen and Eve Maler. 6 October 2000. http://www.w3.org/TR/2000/REC-xml-20001006 .
XML-C14N
Canonical XML Version 1.0 , W3C Recommendation. Editor/Author John Boyer. 15 March 2001. http://www.w3.org/TR/2001/REC-xml-c14n-20010315.
XML DSig
XML-Signature Syntax and Processing , IETF Draft/W3C Candidate Recommendation. D. Eastlake, J. Reagle, D. Solo, M. Bartel, J. Boyer, B. Fox, and E. Simon. 31 October 2000. http://www.w3.org/TR/2001/CR-xmldsig-core-20010419/.
XML-Enc
XPath
XML Path Language (XPath) Version 1.0 , W3C Recommendation. eds. James Clark and Steven DeRose. 16 November 1999. http://www.w3.org/TR/1999/REC-xpath-19991116.

5. Acknowledgements (Informative)

The following people provided valuable feedback that improved the quality of this specification: