Copyright © 2002 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
SOAP 1.2 intermediaries have some license when serializing messages that pass through them. This note defines a canonicalization that serializes all semantically equivalent SOAP messages identically. This canonicalization is required prior to the generation of a message digest in producing XML digital signatures that are sufficiently robust to survive passage through one or more SOAP intermediaries.
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
1. Introduction
2. The Need for SOAP Message Canonicalization
3. Specification of SOAP Message Canonicalization
4. Use in XML Security
5. References
A. Acknowledgements (Non-Normative)
1. Introduction
1.1 Notational Conventions
2. The Need for SOAP Message Canonicalization
2.1 A Simple Example
3. Specification of SOAP Message Canonicalization
4. Use in XML Security
5. References
5.1 Normative References
5.2 Informative References
A. Acknowledgements (Non-Normative)
SOAP 1.2 [SOAP Part1] intermediaries have some license when reserializing messages that pass through them. Current XML canonicalizations (see [XML C14N] and [EXCL C14N]) do not take into account the transforms that a SOAP intermediary can legally apply to messages passing through it. This note defines a canonicalization that serializes all semantically equivalent SOAP messages identically. This canonicalization is required prior to the generation of a message digest in producing XML digital signatures that are sufficiently robust to survive passage through one or more SOAP intermediaries.
An understanding of the Exclusive XML Canonicalization Recommendation [EXCL C14N] is required.
The keywords "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].
This note uses a number of namespace prefixes throughout; they are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML InfoSet]).
| Prefix | Namespace | Notes |
|---|---|---|
| env | "http://www.w3.org/2002/06/soap-envelope" | A normative XML Schema [XML Schema Part1], [XML Schema Part2] document for the "http://www.w3.org/2002/06/soap-envelope" namespace can be found at http://www.w3.org/2002/06/soap-envelope. |
Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs (see [RFC 2396]).
All parts of this note are normative, with the exception of examples and sections explicitly marked as "Non-Normative".
As a simple of example of the kind of problem a SOAP intermediary can cause for an XML signature, consider the following SOAP message:
<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <n:alertcontrol env:mustUnderstand="false" xmlns:n="http://example.org/alertcontrol"> <n:priority>1</n:priority> <n:expires>2001-06-22T14:00:00-05:00</n:expires> </n:alertcontrol> </env:Header> <env:Body> <m:alert xmlns:m="http://example.org/alert"> <m:msg>Pick up Mary at school at 2pm</m:msg> </m:alert> </env:Body> </env:Envelope>
A SOAP intermediary is at liberty to remove the
env:mustUnderstand attribute from SOAP header blocks
when its value is "false" or "0".
If the message included a signature of the header block
generated using XML Canonicalization [XML C14N] or
Exclusive XML Canonicalization [EXCL C14N] then
that signature would be invalidated if the intermediary removed
the mustUnderstand attribute. There is therefore a
requirement for a canonicalization that takes into account the
variations that a SOAP intermediary can introduce. SOAP Message
Canonicalization fulfils this requirement.
SOAP Message Canonicalization is an extension of Exclusive XML Canonicalization [EXCL C14N]. The following processing is performed prior to applying the processing defined by [EXCL C14N]:
For child element information items of the SOAP
Header element information item:
If the SOAP mustUnderstand attribute
information item is present with a value of
"0" or "false" then remove the
mustUnderstand attribute information
item.
If the SOAP mustUnderstand attribute
information item is present with a value of
"1" then change its value to
"true".
If the SOAP role attribute information
item is present with a value of
"http://www.w3.org/2002/06/soap-envelope/role/
ultimateReceiver" or "" then remove
the role attribute information item.
If the SOAP relay attribute
information item is present with a value of
"0" or "false" then remove the
relay attribute information
item.
If the SOAP relay attribute
information item is present with a value of
"1" then change its value to
"true".
Processing instruction information items that are
children of the SOAP Envelope , Header ,
Fault , Code , Subcode , Value ,
Reason , Text , Node and Role
element information items are removed.
Whitespace character information items that are
children of the SOAP Envelope , Header ,
Fault , Code , Subcode , Value ,
Reason , Node and Role element
information items are removed.
SOAP Message Canonicalization may be used as a
Transform or CanonicalizationMethod algorithm in
XML Digital Signature [XML DSig] and XML Encryption
[XML Enc]. It is identified with one of the following URIs:
"http://www.w3.org/2002/11/sm-c14n"
"http://www.w3.org/2002/11/sm-c14n#WithComments"
Just as with [EXCL C14N] one may use the "#WithComments"
parameter to include the serialization of XML comments. This
algorithm also takes an optional explicit parameter of an empty
InclusiveNamespaces element with a PrefixList attribute. The value
of this attribute is the same as specified in [EXCL C14N].