This document specifies the syntax and processing rules of a SOAP header entry to carry digital signature information within a SOAP 1.1 Envelope.
This document is a submission to the World Wide Web Consortium (see Submission Request, W3C Staff Comment). For a full list of all acknowledged Submissions, please see Acknowledged Submissions to W3C.
This document is a NOTE made available by the W3C for discussion only. Publication of this Note by the W3C indicates no endorsement by W3C or the W3C Team, or any W3C Members. The W3C has had no editorial control over the preparation of this Note. This document is a work in progress and may be updated, replaced, or rendered obsolete by other documents at any time.
A list of current W3C technical documents can be found at the Technical Reports page.
The motivation for this Note is to propose a standard way to use the XML Digital Signature syntax [XML-Signature] to sign SOAP 1.1 messages [SOAP]. We define a SOAP header entry <SOAP-SEC:Signature> for this purpose.
We also propose the definition of an extensible namespace for adding security features to the SOAP header. By extensible we mean that new elements can be added to the schema overtime but elements in the schema will not change. It is our intention that other security features, such as confidentiality of SOAP 1.1 messages, will be added within this namespace as appropriate standards, such as forthcoming XML Encryption, become available. What we specifically defer to another Note or working group is the definition of an authentication protocol for SOAP. By "protocol", we mean any expectation of processing by the recipient of a signed/encrypted message.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALLNOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 [KEYWORDS].
Namespace URIs of the general form "some-URI" represent some application-dependent or context-dependent URI as defined in RFC2396 [URI]. The namespace prefixes "SOAP-ENV" and "ds" used in this document are associated with the namespaces "http://schemas.xmlsoap.org/soap/envelope/" and "http://www.w3.org/2000/09/xmldsig#", respectively.
The XML namespace [XML-ns] URI that MUST be used by implementations of this specification is:
The namespace prefix "SOAP-SEC" used in this specification is associated with this URI.
The header entry <SOAP-SEC:Signature> is defined by the following schema [XML-Schema1], [XML-Schema2]. The <SOAP-SEC:Signature> element contains a single digital signature conforming to the XML-Signature specification [XML-Signature].
<schema xmlns="http://www.w3.org/1999/XMLSchema" xmlns:SOAP-SEC="http://schemas.xmlsoap.org/soap/security/2000-12" targetNamespace="http://schemas.xmlsoap.org/soap/security/2000-12" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <import namespace="http://www.w3.org/2000/09/xmldsig#"/> <import namespace="http://schemas.xmlsoap.org/soap/envelope/"/> <element name="Signature" final="restriction"> <complexType> <sequence> <element ref="ds:Signature" minOccurs="1" maxOccurs="1"/> </sequence> <attribute name="id" type="ID" use="optional"/> <attribute ref="SOAP-ENV:actor" use="optional"/> <attribute ref="SOAP-ENV:mustUnderstand" use="optional"/> </complexType> </element> <attribute name="id" type="ID"/> </schema>
The <ds:Reference> element needs to refer to the signed part of the SOAP Envelope. This can be achieved through the use of XML identifiers. Applications are responsible for determining which attributes are of the type ID. To help applications to identify attributes of the type ID, this specification defines the SOAP-SEC:id global attribute. This attribute MAY be used for referencing the signed part of the SOAP Envelope.
Here is an example of a SOAP message with a signature header entry, where the SOAP Body is signed and the resulting signature <ds:Signature> is added to the <SOAP-SEC:Signature> header entry. Note that the "URI" attribute of the <ds:Reference> element refers to the <SOAP-ENV:SOAP-Body> element.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header> <SOAP-SEC:Signature xmlns:SOAP-SEC="http://schemas.xmlsoap.org/soap/security/2000-12" SOAP-ENV:actor="some-URI" SOAP-ENV:mustUnderstand="1"> <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:SignedInfo> <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2000/CR-xml-c14n-20001026"> </ds:CanonicalizationMethod> <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/> <ds:Reference URI="#Body"> <ds:Transforms> <ds:Transform Algorithm="http://www.w3.org/TR/2000/CR-xml-c14n-20001026"/> </ds:Transforms> <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <ds:DigestValue>j6lwx3rvEPO0vKtMup4NbeVu8nk=</ds:DigestValue> </ds:Reference> </ds:SignedInfo> <ds:SignatureValue>MC0CFFrVLtRlk=...</ds:SignatureValue> </ds:Signature> </SOAP-SEC:Signature> </SOAP-ENV:Header> <SOAP-ENV:Body xmlns:SOAP-SEC="http://schemas.xmlsoap.org/soap/security/2000-12" SOAP-SEC:id="Body"> <m:GetLastTradePrice xmlns:m="some-URI"> <m:symbol>IBM</m:symbol> </m:GetLastTradePrice> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
The Signature header entry is used to carry a signature compliant with the XML-Signature specification [XML-Signature] within a SOAP Envelope for the purpose of signing one or more elements in the SOAP Envelope. Multiple signature header entries MAY be added into a single SOAP Envelope with either disjoint or overlapping signed elements. A future version of this specification may allow signature syntax other than the XML-Signature through extension [XML-Schema1] of the content model of <SOAP-SEC:Signature>.
SOAP applications conforming to this specification MUST satisfy the following conditions:
mustUnderstand="1"attribute or voluntarily),
Note that XML Canonicalization [XML-C14N] of <ds:SignedInfo> and other signed resources MUST each be done within its own context. This means, among other things, that the Canonical form [XML-C14N] of <ds:SigndInfo> always inherits the namespace declarations for SOAP-ENV and SOAP-SEC.
The rest of this section describes the operations to be performed for the signature header entry.
One way to create a <SOAP-SEC:Signature> header entry is as follows.
XPath filtering can be used to specify objects to be signed, as described in the XML-Signature specification [XML-Signature]. However, since the SOAP message exchange model allows intermediate applications to modify the Envelope (add or delete a header entry, for example), XPath filtering does not always result in the same objects after message delivery. Care should be taken in using XPath filtering so that there is no subsequent validation failure due to such modifications.
http://www.w3.org/2000/09/xmldsig#enveloped-signature defined in the
XML-Signature specification [XML-Signature] may
be useful when signing the entire Envelope including other header entries, if
The validation of a <SOAP-SEC:Signature> header entry fails if
If the validation of the signature header entry fails, applications MAY report the failure to the sender. It is out of the scope of this specification how to deal with it.
This specification defines the use of XML Signature in SOAP 1.1 headers. As one of building blocks for securing SOAP messages, it is intended to be used in conjunction with other security techniques. Digital signatures need to be understood in the context of other security mechanisms and the threats to an entity. Digital signatures are, according to the IETF RFC 2828[DIGSIG],
"A value computed with a cryptographic algorithm and appended to a data object in such a way that any recipient of the data can use the signature to verify the data's origin and integrity. (See:data origin authentication service, data integrity service,digitized signature, electronic signature, signer.)"
"Data appended to, or a cryptographic transformation of, a data unit that allows a recipient of the data unit to prove the source and integrity of the data unit and protect against forgery, e.g. by the recipient." [I7498Part2]
For example, digital signatures alone do not provide message authentication. One can record a signed message and resend it (replay attack). To prevent this type of attack, digital signatures must be combined with an appropriate means to ensure the uniqueness of the message, such as nonces or time stamps. One way to add this information is to place an extra <ds:Object> element that is a child of the <ds:Signature>.
When digital signatures are used for verifying the identity of the sending party, the sender must prove the possession of the private key. One way to achieve this is to use a challenge-response type of protocol.
Implementers should also be aware of all the security implications resulting from the use of digital signatures in general and XML Signature in particular. In building trust into an application based on a digital signature there are other pieces of technology that must be identified in relation to the signature. There needs to be a certificate trust model, whether hierarchical or peer-to-peer. There needs to be a way to generate and maintain trusted key pairs and certificates. And there must be a way to validate that the certificate has not been revoked.