Exclusive XML Canonicalization Version 1.0 Exclusive XML Canonicalization W3C Recommendation 18 July 2002 This version: http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/ Latest version: http://www.w3.org/TR/xml-exc-c14n/ Previous version: http://www.w3.org/TR/2002/PR-xml-exc-c14n-20020524/ Authors/Editors: John Boyer, PureEdge Solutions Inc., [email protected] Donald E. Eastlake 3rd, Motorola, [email protected] Joseph Reagle, W3C, [email protected] Please see the errata translations Copyright W3C ® MIT INRIA Keio liability trademark document use software licensing Abstract Canonical XML [ XML-C14N Status of this document This document is the W3C Exclusive Canonicalization Recommendation This specification was produced by the IETF/W3C XML Signature Working Group W3C Activity Statement Interoperability Report. Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page IETF Page of Intellectual Property Rights Notices Please report errors in this document to [email protected] archive The list of known errors in this specification is available at http://www.w3.org/2002/07/xml-exc-c14n-errata The English version of this specification is the only normative version. Information about translations of this document (if any) is available http://www.w3.org/Signature/2002/02/xmldsig-translations A list of current W3C Technical Reports can be found at http://www.w3.org/TR/ Table of Contents Introduction Terminology Applications Limitations The Need for Exclusive XML Canonicalization A Simple Example General Problems with Enveloping and de-Enveloping Specification of Exclusive XML Canonicalization Constrained Implementation (non-normative) Use in XML Security Security Considerations Target Context "Esoteric" Node-sets References Acknowledgements The XML Recommendation [XML] XML-NS The node-set is minimally affected by any XML context which has been omitted. The canonicalization of a node-set representing well-balanced XML-Fragment It can be determined whether two node-sets are identical except for transformations considered insignificant by this specification under [ XML XML-NS An understanding of the Canonical XML Recommendation [ XML-C14N 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] node-set XML-C14N A document subset defined XPath parent apex node orphan node output parent apex node output parent output ancestor For example given a document tree with three generations under the root node A A,E,G Pictorial Representation: Textual Representation: A-+-b `-c-+-d `-E-+-f `-G The following characteristics apply: A E E,G E G. An element E visibly utilizes P V E E P E visibly utilizes E The namespace axis of an element contains nodes for all non-default namespace declarations made within the element as well as non-default namespace declarations inherited from ancestors of the element. The namespace axis also contains a node representing the default namespace if it is not the empty string, whether the default namespace was declared within the element or by an ancestor 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 InclusiveNamespaces PrefixList XML-C14N The exclusive canonical form XML-C14N attributes in the XML namespace, such as xml:lang xml:space namespace nodes that are not on the InclusiveNamespaces PrefixList output ancestor The term exclusive canonical XML exclusive XML canonicalization method exclusive XML canonicalization 1.2 Applications The applications of Exclusive XML Canonicalization are very similar to those for Canonical XML [ XML-C14N Note that in the case of the SignedInfo XML-DSig 1.3 Limitations Exclusive XML Canonicalization has the limitations of Canonical XML [ XML-C14N The XML being canonicalized may depend on the effect of XML namespace attributes, such as xml:lang xml:space xml:base apex nodes Applications that use the XML being canonicalized may depend on the effect of XML namespace declarations where the namespace prefix being bound is not visibly utilized QName XML-NS <number xsi:type="xsd:decimal">10.09</number> To avoid problems with such namespace declarations, the XML must be modified so that use of the namespace prefix involved is visible, or the namespace declarations must appear and be bound to the same values in every context in which the XML will be interpreted, or the prefixes for such namespaces must appear in the InclusiveNamespaces PrefixList 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 need 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 document: <n1:elem1 xmlns:n1="http://b.example"> content </n1:elem1> this is then enveloped in another document: <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 (//. | //@* | //namespace::*)[ancestor-or-self::n1: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 elem1 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::n1: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"> <n3:stuff></n3:stuff> </n1:elem2> However, although elem2 elem2 <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 n0 n3 n0 n2 n3 xml:space xml:lang n1 elem2 On the other hand, using Exclusive XML Canonicalization as specified herein, the physical form of elem2 <n1:elem2 xmlns:n1="http://example.net" xml:lang="en"> <n3:stuff xmlns:n3="ftp://example.org"></n3:stuff> </n1:elem2> in both cases. The data model, processing, input parameters, and output data for Exclusive XML Canonicalization are the same as for Canonical XML [ XML-C14N 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 xml:space omitted The Exclusive XML Canonicalization method may receive an additional, possibly null, parameter InclusiveNamespaces PrefixList XML-C14N A namespace node N InclusiveNamespaces PrefixList Its parent element is in the node-set, and it is visibly utilized the prefix has not yet been rendered by any output ancestor output ancestor visibly utilizes and N If the token representing the default namespace is not present in InclusiveNamespaces PrefixList xmlns="" E xmlns="" E visibly utilizes it has no default namespace node in the node-set, and the nearest output ancestor of E that visibly utilizes the default namespace has a default namespace node in the node-set. (This step for for xmlns="" Propagation of Default Namespace Declaration in Document Subsets XML-C14N 3.1 Constrained Implementation The following is a (non-normative) method for implementing the Exclusive XML Canonicalization method for many straightforward cases -- it assumes a well-formed subset and that if an element is in the node-set, so is all of its namespace axis; if the element is not in the subset, neither is its namespace axis. Recursively process the entire xml: apex element nodes not If the node is not in the XPath subset, continue to process its children element nodes recursively. If the element node is in the XPath subset then output the node in accordance with Canonical XML except for namespace nodes which are rendered as follows: ns_rendered state output ancestor Render each namespace node if and only if all of the conditions are met: it is visibly utilized or InclusiveNamespaces PrefixList its prefix and value do not ns_rendered Render xmlns="" The default namespace is visibly utilized InclusiveNamespaces PrefixList the element does not have a namespace node in the node-set declaring a value for the default namespace, and the default namespace prefix is present in the dictionary ns_rendered Insert all the rendered namespace nodes (including xmlns="" ns_rendered ns_rendered After the recursion returns, pop the state Exclusive Canonicalization may be used as a Transform CanonicalizationMethod XML-DSig XML-Enc Identifier: http://www.w3.org/2001/10/xml-exc-c14n# http://www.w3.org/2001/10/xml-exc-c14n#WithComments Just as with [ XML-C14N #WithComments InclusiveNamespaces PrefixList XML-C14N <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> <ec:InclusiveNamespaces PrefixList="dsig soap #default" xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"/> </ds:Transform> indicates the exclusive canonicalization transform, but that namespaces with prefix "dsig" or "soap" and default namespaces should be processed according to [ XML-C14N Schema Definition DTD 5. Security Considerations This specification is used to serialize an XPath node-set under certain assumptions given in [ XML-C14N implementations of [ XML-C14N implementations of this specification only render attributes from the "XML" namespace (e.g., xml:lang xml:space xml:base implementations of this specification do not consider the appearance of a namespace prefix within an attribute value to be visibly utilized While such choices are consistent with other XML specifications and satisfy the Working Group's application requirements it is important that an XML application carefully construct its transforms such that the result is meaningful and unambiguous in its application context. In addition to this section, the Limitations Resolutions XML-C14N Security Considerations XML-DSig 5.1 Target Context The requirement of this specification is to satisfy applications that "require a method which, to the extent practical, excludes ancestor context from a canonicalized subdocument." Given a fragment being removed from its source instance, this specification satisfies this requirement by excluding from the fragment any context from its ancestors that is not utilized. Consequently, a signature [ XML-DSig For example, if the <Foo/> <Bar/><Foo/></Bar> <Baz xmlns="http://example.org/bar"/><Foo/></Baz> <Foo/> http://example.org/bar This specification does not define mechanisms of removing, inserting, and "fixing up" a node-set. (For an example of this sort of specification, see the processing required of Creating the Result Infoset XInclude xmlns="" xml:lang xml:space xml:base 5.2 "Esoteric" Node-sets Consider an application that might use this specification or [ XML-C14N not This example is provided to caution that as one moves beyond well-formed XML well-balanced XML-Fragment 6. References Keywords RFC 2119. Key words for use in RFCs to Indicate Requirement Levels Available at http://www.ietf.org/rfc/rfc2119.txt URI RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax. Available at http://www.ietf.org/rfc/rfc2396.txt XML Extensible Markup Language (XML) 1.0 (Second Edition). Available at http://www.w3.org/TR/2000/REC-xml-20001006 XML-C14N Canonical XML. Available at http://www.w3.org/TR/2001/REC-xml-c14n-20010315 Available at http://www.ietf.org/rfc/rfc3076.txt XML-DSig XML-Signature Syntax and Processing Available at http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/ XML-Fragment XML Fragment Interchange Available at http://www.w3.org/TR/2001/CR-xml-fragment-20010212 XInclude XML Inclusions (XInclude) Version 1.0. J. Marsh, and D. Orchad. W3C Candidate Recommendation, February 2002. Available at http://www.w3.org/TR/2002/CR-xinclude-20020221/ XML-NS Namespaces in XML Available at http://www.w3.org/TR/1999/REC-xml-names-19990114/ XML-Enc XML Encryption Syntax and Processing Available at http://www.w3.org/TR/2002/CR-xmlenc-core-20020304/ XML-schema XML Schema Part 1: Structures Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ XPath XML Path Language (XPath) Version 1.0 Available at http://www.w3.org/TR/1999/REC-xpath-19991116 The following people provided valuable feedback that improved the quality of this specification: Merlin Hughes, Baltimore Thomas Maslen, DSTC Paul Denning, MITRE Christian Geuer-Pollmann, University Siegen Bob Atkinson, Microsoft