W3C Web Services Addressing 1.0 - SOAP Binding W3C Working Draft 15 February 2005 This version: http://www.w3.org/TR/2005/WD-ws-addr-soap-20050215 Latest version: http://www.w3.org/TR/ws-addr-soap Previous versions: http://www.w3.org/TR/2004/WD-ws-addr-soap-20041208 Editors: Martin Gudgin, Microsoft Corp Marc Hadley, Sun Microsystems, Inc This document is also available in these non-normative formats: postscript, PDF , XML, and plain text. Copyright © 2005 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Abstract Web Services Addressing provides transport-neutral mechanisms to address Web services and messages. Web Services Addressing 1.0 - SOAP Binding (this document) defines the binding of the abstract properties defined in Web Services Addressing 1.0 - Core to SOAP Messages. Status of this Document This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/. This is the second Public Working Draft of the Web Services Addressing 1.0 - SOAP Binding specification for review by W3C members and other interested parties. It has been produced by the Web Services Addressing Working Group (WG), which is part of the W3C Web Services Activity. This Working Draft reflects the current position of the Working Group. A diff-marked version against the previous version of this document is available. For a detailed list of changes since the last publication of this document, please refer to appendix B. Change Log. A list of remaining issues is also available. Discussion of this document takes place on the public-ws-addressing@w3.org mailing list (public archive). Comments on this specification should be sent to this mailing list. This document was produced under the 5 February 2004 W3C Patent Policy. The Working Group maintains a public list of patent disclosures relevant to this document; that page also includes instructions for disclosing [and excluding] a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy. Per section 4 of the W3C Patent Policy, Working Group participants have 150 days from the title page date of this document to exclude essential claims from the W3C RF licensing requirements with respect to this document series. Exclusions are with respect to the exclusion reference document, defined by the W3C Patent Policy to be the latest version of a document in this series that is published no later than 90 days after the title page date of this document. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress. ┌──────────────────────────────────────┬──────────────────────────────────────┐ │Editorial note │ │ ├──────────────────────────────────────┴──────────────────────────────────────┤ │The Web Services Addressing Working Group has decided to use XML Schema, │ │where appropriate, to describe constructs defined in this specification. Note│ │that this restricts use of Web Services Addressing to XML 1.0. │ └─────────────────────────────────────────────────────────────────────────────┘ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Short Table of Contents 1. Introduction 2. Binding Endpoint References 3. Faults 4. Security Considerations 5. References A. Acknowledgements (Non-Normative) B. Change Log (Non-Normative) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Table of Contents 1. Introduction 1.1 Notational Conventions 1.2 Namespaces 2. Binding Endpoint References 3. Faults 3.1 Invalid Message Information Header 3.2 Message Information Header Required 3.3 Destination Unreachable 3.4 Action Not Supported 3.5 Endpoint Unavailable 4. Security Considerations 5. References Appendices A. Acknowledgements (Non-Normative) B. Change Log (Non-Normative) B.1 Changes Since First Working Draft B.2 Changes Since Submission ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. Introduction Web Services Addressing 1.0 - Core[WS-Addressing-Core] defines a set of abstract properties and an XML Infoset [XML Information Set] representation thereof to reference Web service endpoints and to facilitate end-to-end addressing of endpoints in messages. Web Services Addressing 1.0 - SOAP Binding (this document) defines the binding of the abstract properties defined in Web Services Addressing 1.0 - Core to SOAP Messages. The following example illustrates the use of these mechanisms in a SOAP 1.2 message being sent from http://example.com/business/client1 to http:// example.com/fabrikam/Purchasing: Example 1-1. Use of message addressing properties in a SOAP 1.2 message. (001) (002) (003) (004) http://example.com/6B29FC40-CA47-1067-B31D-00DD010662DA (005) (006) (007) http://example.com/business/client1 (008) (009) http://example.com/fabrikam/Purchasing (010) http://example.com/fabrikam/SubmitPO (011) (012) (013) ... (014) (015) Lines (002) to (011) represent the header of the SOAP message where the mechanisms defined in the specification are used. The body is represented by lines (012) to (014). Lines (003) to (010) contain the message information header blocks. Specifically, lines (003) to (005) specify the identifier for this message and lines (006) to (008) specify the endpoint to which replies to this message should be sent as an Endpoint Reference. Line (009) specifies the address URI of the ultimate receiver of this message. Line (010) specifies an Action URI identifying expected semantics. 1.1 Notational Conventions 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 [IETF RFC 2119]. When describing abstract data models, this specification uses the notational convention used by XML Infoset [XML Information Set]. Specifically, abstract property names always appear in square brackets (e.g., [some property]). When describing concrete XML schemas [XML Schema Structures, XML Schema Datatypes], this specification uses the notational convention of WS-Security [ WS-Security]. Specifically, each member of an element's [children] or [attributes] property is described using an XPath-like notation (e.g., / x:MyHeader/x:SomeProperty/@value1). The use of {any} indicates the presence of an element wildcard (). The use of @{any} indicates the presence of an attribute wildcard (). 1.2 Namespaces This specification uses a number of namespace prefixes throughout; they are listed in Table 1-1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Namespaces ]). Table 1-1. Prefixes and Namespaces used in this specification ┌──────┬────────────────────────────────────────┐ │Prefix│Namespace │ ├──────┼────────────────────────────────────────┤ │S │http://www.w3.org/2003/05/soap-envelope │ ├──────┼────────────────────────────────────────┤ │S11 │http://schemas.xmlsoap.org/soap/envelope│ ├──────┼────────────────────────────────────────┤ │wsa │http://www.w3.org/2005/02/addressing │ ├──────┼────────────────────────────────────────┤ │xs │http://www.w3.org/2001/XMLSchema │ └──────┴────────────────────────────────────────┘ WS-Addressing is defined in terms of the XML Information Set [XML Information Set]. WS-Addressing is conformant to the SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework] processing model and is also compatible with SOAP 1.1[SOAP 1.1] for backwards compatibility. WS-Addressing may be used with WSDL [WSDL 2.0] described services as described in Web Services Addressing 1.0 - WSDL Binding[ WS-Addressing-WSDL]. The examples in this specification use an XML 1.0 [XML 1.0 ] representation but this is not a requirement. All information items defined by WS-Addressing are identified by the XML namespace URI [XML Namespaces] "http://www.w3.org/2005/02/addressing". A normative XML Schema [XML Schema Structures, XML Schema Datatypes] document can be obtained by dereferencing the XML namespace URI. 2. Binding Endpoint References This section defines the binding of Endpoint references to SOAP messages. When a message needs to be addressed to the endpoint, the information contained in the endpoint reference is mapped to the message according to a transformation that is dependent on the protocol and data representation used to send the message. Protocol-specific mappings (or bindings) will define how the information in the endpoint reference is copied to message and protocol fields. This specification defines the SOAP binding for endpoint references. This mapping MAY be explicitly replaced by other bindings (defined as WSDL bindings or as policies); however, in the absence of an applicable policy stating that a different mapping must be used, the SOAP binding defined here is assumed to apply. To ensure interoperability with a broad range of devices, all conformant implementations MUST support the SOAP binding. The SOAP binding for endpoint references is defined by the following three rules: • The [address] property in the endpoint reference is copied in the [destination] message information property. The infoset representation of the [destination] property becomes a header block in the SOAP message. • Each [reference parameter] element becomes a header block in the SOAP message. The element information item of each [reference parameter] (including all of its [children], [attributes] and [in-scope namespaces]) is to be added as a header block in the new message. • Each header block added as a result of the above rule is annotated with a wsa:Type attribute whose value is "parameter". The next example shows how the default SOAP binding for endpoint references is used to construct a message addressed to the endpoint: Example 2-1. Example endpoint reference. http://example.com/fabrikam/acct fabrikam:Inventory 123456789 ABCDEFG According to the mapping rules stated above, the address value is copied in the "To" header and the "CustomerKey" and "ShoppingCart" elements should be copied literally as a header in a SOAP message addressed to this endpoint. The SOAP message would look as follows: Example 2-2. Example endpoint reference mapped to SOAP message header blocks. ... http://example.com/fabrikam/acct 123456789 ABCDEFG ... ... 3. Faults The faults defined in this section are generated if the condition stated in the preamble in each subsection is met. Endpoints compliant with this specification MUST include required message information headers on all fault messages. Fault messages are correlated as replies using the [relationship] property as defined in Section 3. The [action] property below designates WS-Addressing fault messages: http://www.w3.org/2005/02/addressing/fault The definitions of faults use the following properties: [Code] The fault code. [Subcode] The fault subcode. [Reason] The English language reason element. [Detail] The detail element. If absent, no detail element is defined for the fault. The properties above bind to a SOAP 1.2 fault as follows: Example 3-1. Binding of fault properties to SOAP 1.2 messages. http://www.w3.org/2005/02/addressing/fault [Code] [Subcode] [Reason] [Detail] The SOAP 1.1 fault is less expressive and map only [Subcode] and [Reason]. These the properties bind to a SOAP 1.1 fault as follows: Example 3-2. Binding of fault properties to SOAP 1.1 messages. [Subcode] [Reason] 3.1 Invalid Message Information Header A message information header cannot be processed. [Code] S:Sender [Subcode] wsa:InvalidMessageInformationHeader [Reason] A message information header is not valid and the message cannot be processed. The validity failure can be either structural or semantic, e.g. a [destination] that is not a URI or a [relationship] to a [message id] that was never issued. [Detail] [invalid header] 3.2 Message Information Header Required A required message information header is absent. [Code] S:Sender [Subcode] wsa:MessageInformationHeaderRequired [Reason] A required message information header, To, MessageID, or Action, is not present. [Detail] [Missing Header QName] 3.3 Destination Unreachable No endpoint can be found capable of acting in the role of the [destination] property. [Code] S:Sender [Subcode] wsa:DestinationUnreachable [Reason] No route can be determined to reach the destination role defined by the WS-Addressing To. [Detail] empty 3.4 Action Not Supported The [action] property in the message is not supported at this endpoint. The contents of this fault are as follows: [Code] S:Sender [Subcode] wsa:ActionNotSupported [Reason] The [action] cannot be processed at the receiver. [Detail] [action] 3.5 Endpoint Unavailable The endpoint is unable to process the message at this time either due to some transient issue or a permanent failure. The endpoint may optionally include a RetryAfter parameter in the detail. The source should not retransmit the message until this duration has passed. [Code] S:Receiver [Subcode] wsa:EndpointUnavailable [Reason] The endpoint is unable to process the message at this time. [Detail] [xs:NonNegativeInteger] The following describes the attributes and elements listed above: /wsa:RetryAfter This element (of type xs:NonNegativeInteger) is a suggested minimum duration in milliseconds to wait before retransmitting the message. If this element is omitted from the detail, the value is infinite. /wsa:RetryAfter/@{any} These optional extensibility attributes do not affect processing. 4. Security Considerations It is strongly recommended that the communication between services be secured using the mechanisms described in WS-Security [WS-Security]. In order to properly secure messages, the body and all relevant headers need to be included in the signature. Specifically, the message information headers described in this specification (e.g. ) need to be signed with the body in order to "bind" the two together. It should be noted that for messages traveling through intermediaries, it is possible that some or all of the message information headers may have multiple signatures when the message arrives at the ultimate receiver. It is strongly recommended that the initial sender include a signature to prevent any spoofing by intermediaries. Whenever an address is specified (e.g. , , , ...), the processor should ensure that a signature is provided with claims allowing it to speak for the specified target in order to prevent certain classes of attacks (e.g. redirects). As well, care should be taken if the specified endpoint contains reference parameters as unverified endpoint references could cause certain classes of header insertion attacks. The message information headers blocks may have their contents encrypted in order to obtain end-to-end privacy, but care should be taken to ensure that intermediary processors have access to required information (e.g. ). Some processors may use message identifiers () as part of a uniqueness metric in order to detect replays of messages. Care should be taken to ensure that a unique identifier is actually used. For example, it may be appropriate in some scenarios to combine the message identifier with a timestamp. The following list summarizes common classes of attacks that apply to this protocol and identifies the mechanism to prevent/mitigate the attacks: • Message alteration – Alteration is prevented by including signatures of the message information using WS-Security. • Message disclosure – Confidentiality is preserved by encrypting sensitive data using WS-Security. • Address spoofing – Address spoofing is prevented by ensuring that all address are signed by a party authorized to speak for (or on behalf of) the address. • Key integrity – Key integrity is maintained by using the strongest algorithms possible (by comparing secured policies. • Authentication – Authentication may be established using the mechanisms described in WS-Security. • Accountability – Accountability is a function of the type of and strength of the key and algorithms being used. In many cases, a strong symmetric key provides sufficient accountability. However, in some environments, strong PKI signatures are required. • Availability – All reliable messaging services are subject to a variety of availability attacks. Replay detection is a common attack and it is recommended that this be addressed by the mechanisms described in WS-Security and/or caching of message identifiers. Other attacks, such as network-level denial of service attacks are harder to avoid and are outside the scope of this specification. That said, care should be taken to ensure that minimal state is saved prior to any authenticating sequences. • Replay – Messages may be replayed for a variety of reasons. To detect and eliminate this attack, mechanisms should be used to identify replayed messages such as the timestamp/nonce outlined in WS-Security. Alternatively, and optionally, other technologies, such as sequencing, can also be used to prevent replay of application messages. 5. References [WS-Addressing-Core] Web Services Addressing 1.0 - Core, M. Gudgin, M. Hadley, Editors. [WS-Addressing-WSDL] Web Services Addressing 1.0 - WSDL Binding, M. Gudgin, M. Hadley, Editors. [WSDL 2.0] Web Services Description Language 2.0, R. Chinnici, M. Gudgin, J. J. Moreau, J. Schlimmer, S. Weerawarana, Editors. World Wide Web Consortium, 3 August 2004. This version of the WSDL 2.0 specification is http:// www.w3.org/TR/2004/WD-wsdl20-20040803. The latest version of WSDL 2.0 is available at http://www.w3.org/TR/wsdl20. [IETF RFC 2119] Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Author. Internet Engineering Task Force, June 1999. Available at http:// www.ietf.org/rfc/rfc2119.txt. [RFC 3986] T. Berners-Lee, et al, "Uniform Resource Identifier (URI): Generic Syntax,", W3C/MIT, January 2005. (See http://www.ietf.org/rfc/rfc3986.txt.) [XML 1.0] Extensible Markup Language (XML) 1.0 (Second Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 10 February 1998, revised 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2000/REC-xml-20001006. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml. [XML Namespaces] Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the XML Information Set Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/ REC-xml-names. [XML Information Set] XML Information Set, J. Cowan and R. Tobin, Editors. World Wide Web Consortium, 24 October 2001. This version of the XML Information Set Recommendation is http://www.w3.org/TR/2001/REC-xml-infoset-20011024. The latest version of XML Information Set is available at http://www.w3.org/TR/ xml-infoset. [XML Schema Structures] XML Schema Part 1: Structures, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Schema Part 1 Recommendation is http://www.w3.org/TR/2001/ REC-xmlschema-1-20010502. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1. [XML Schema Datatypes] XML Schema Part 2: Datatypes, P. Byron and A. Malhotra, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Schema Part 2 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-2-20010502. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/ xmlschema-2. [SOAP 1.2 Part 1: Messaging Framework] SOAP Version 1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World Wide Web Consortium, 24 June 2003. This version of the "SOAP Version 1.2 Part 1: Messaging Framework" Recommendation is http://www.w3.org/TR/2003/ REC-soap12-part1-20030624/. The latest version of "SOAP Version 1.2 Part 1: Messaging Framework" is available at http://www.w3.org/TR/soap12-part1/. [WSDL 1.1] E. Christensen, et al, Web Services Description Language (WSDL) 1.1, March 2001. [SOAP 1.1] Don Box, et al, Simple Object Access Protocol (SOAP) 1.1, May 2000. [WS-Security] OASIS, Web Services Security: SOAP Message Security, March 2004. A. Acknowledgements (Non-Normative) This document is the work of the W3C Web Service Addressing Working Group. Members of the Working Group are (at the time of writing, and by alphabetical order): Abbie Barbir (Nortel Networks), Rebecca Bergersen (IONA Technologies, Inc.), Andreas Bjärlestam (ERICSSON), Ugo Corda (SeeBeyond Technology Corporation), Francisco Curbera (IBM Corporation), Glen Daniels (Sonic Software), Paul Downey (BT), Jacques Durand (Fujitsu Limited), Michael Eder (Nokia), Robert Freund (Hitachi, Ltd.), Yaron Goland (BEA Systems, Inc.), Martin Gudgin (Microsoft Corporation), Arun Gupta (Sun Microsystems, Inc.), Hugo Haas (W3C/ERCIM), Marc Hadley (Sun Microsystems, Inc.), David Hull (TIBCO Software, Inc.), Yin-Leng Husband (HP), Anish Karmarkar (Oracle Corporation), Paul Knight (Nortel Networks), Philippe Le Hégaret (W3C/MIT), Mark Little (Arjuna Technologies Ltd.), Jonathan Marsh (Microsoft Corporation), Jeff Mischkinsky (Oracle Corporation), Nilo Mitra (ERICSSON), Eisaku Nishiyama (Hitachi, Ltd.), Mark Nottingham (BEA Systems, Inc.), Ales Novy (Systinet Inc.), David Orchard (BEA Systems, Inc.), Mark Peel (Novell, Inc.), Harris Reynolds (webMethods, Inc.), Tony Rogers (Computer Associates), Tom Rutt (Fujitsu Limited), Rich Salz (DataPower Technology, Inc.), Davanum Srinivas (Computer Associates), Jiri Tejkl (Systinet Inc.), Greg Truty (IBM Corporation), Steve Vinoski (IONA Technologies, Inc.), Pete Wenzel (SeeBeyond Technology Corporation), Steve Winkler (SAP AG), Ümit Yalçınalp (SAP AG). Previous members of the Working Group were: @@@. The people who have contributed to discussions on public-ws-addressing@w3.org are also gratefully acknowledged. B. Change Log (Non-Normative) B.1 Changes Since First Working Draft ┌──────────┬───────┬──────────────────────────────────────────────────────────┐ │ Date │Editor │ Description │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2005-01-24│mgudgin│Removed spurious reference to section 3.3.2 from Section 3│ │@ 20:22 │ │ │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2005-01-23│mgudgin│Incorporated resolution of issue i008; added wsa:Type │ │@ 21:11 │ │attribute to reference parameters │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2005-01-20│mgudgin│Removed text from first paragraph of section 3 per │ │@ 13:10 │ │resolution of issue i040 │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2005-01-16│mgudgin│s/PortType/InterfaceName in certain examples │ │@ 22:41 │ │ │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-12-16│mhadley│Added resolution to issue 19 - WSDL version neutrality │ │@ 18:20 │ │ │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-12-16│mhadley│Added issue 33 resolution │ │@ 16:50 │ │ │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-12-14│mhadley│Switched back to edcopy formatting │ │@ 20:10 │ │ │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │ │ │Enhanced auto-changelog generation to allow specification │ │2004-12-14│mhadley│of data ranges for logs. Split change log to show changes │ │@ 20:02 │ │between early draft and first working draft and changes │ │ │ │since first working draft. │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-12-14│ │Added resolutions for issues 12 (EPR lifecycle), 37 │ │@ 18:13 │mhadley│(relationship from QName to URI) and 39 (spec name │ │ │ │versioning) │ └──────────┴───────┴──────────────────────────────────────────────────────────┘ B.2 Changes Since Submission ┌──────────┬───────┬──────────────────────────────────────────────────────────┐ │ Date │Editor │ Description │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-11-24│mhadley│Added note that addressing is backwards compatible with │ │@ 15:32 │ │SOAP 1.1 │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-11-23│ │Updated titles of examples. Fixed table formatting and │ │@ 21:38 │mhadley│references. Replaced uuid URIs with http URIs in examples.│ │ │ │Added document status. │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │ │ │Second more detailed run through to separate core, SOAP │ │2004-11-07│mhadley│and WSDL document contents. Removed dependency on │ │@ 02:03 │ │WS-Policy. Removed references to WS-Trust and │ │ │ │WS-SecurityPolicy │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-11-02│mhadley│Removed static change log and added dynamically generated │ │@ 22:25 │ │change log from cvs. │ ├──────────┼───────┼──────────────────────────────────────────────────────────┤ │2004-10-28│mhadley│Initial cut of separating specification into core, soap │ │@ 17:05 │ │and wsdl │ └──────────┴───────┴──────────────────────────────────────────────────────────┘