WS-CallBack Protocol (WS-CallBack) 0.91
Feb 26, 2003
Authors
Yaron Goland, BEA Systems (yaron.goland@bea.com)
Mark Nottingham, BEA Systems (mark.nottingham@bea.com)
David Orchard, BEA Systems (david.orchard@bea.com)
Copyright Notice
© 2003 BEA Systems Inc. and Microsoft Corporation. All rights reserved.
Abstract
This specification describes the WS-CallBack protocol, which consists of the CallBack SOAP header and an associated WSDL definition. WS-CallBack is used to dynamically specify where to send asynchronous responses to a SOAP request.
Notice, Disclaimer and License
© 2002-2003, BEA Systems, Inc. All rights reserved. If you would like to copy or re-distribute this specification to others, or to prepare and distribute implementations of this specification, you may do so by accepting BEA's standard, royalty-free Web Services Specification License for this specification. Please visit WS-Callback-License.jsp to review and accept the license terms and conditions. The furnishing of this specification does not grant you any rights or licenses, either expressly or by implication, in any intellectual property owned or controlled by BEA or any other party, whether necessary to implement the specification or otherwise. This specification is provided on an "AS IS" basis, with all faults. BEA hereby disclaims all warranties, WHETHER express, implied or statutory, including, but not limited to, any warranties of merchantability, fitness for a particular purpose, title OR non-infringement.
Introduction
This specification describes the WS-CallBack protocol. WS-CallBack is used to dynamically specify where to send asynchronous responses to a SOAP request.
The CallBack header is needed in cases where a web service is using asynchronous communication and the address to which to send responses is not known at deployment time. In order to enable asynchronous responses to requests the requestor must specify in the request where to send the responses. The WS-CallBack protocol provides the SOAP and WSDL 1.1 mechanisms needed to enable this behavior.
Table of Contents
Introduction
Table of Contents
1. Document Conventions
1.1 Notational Conventions
1.2 Compliance
2. The WS-CallBack Model
2.1 Terminology
2.2 Protocol
2.2 Faults
2.2.1 callbackHeaderMalformed
2.2.2 callbackLocationURISchemeUnacceptable
2.2.3 callbackLocationURILengthUnacceptable
2.2.4 callbackNotSupported
2.2.5 cannotKeepCallBackContract
2.3 Multiple callbackLocation Elements
2.4 Configuration Parameters
2.4.1 UniqueResponses
2.4.2. RepeatResponses
2.4.3 WaitTime
2.4.4 URISchemes
2.4.5 URILength
3. WSDL 1.1 Message Exchange Patterns
4. Security Considerations
4.1 Redirect Attack
4.1.1 Variations on a Theme
4.1.2 Layered Security
4.1.3 Bad Ideas
4.2 Open Port Attack
4.3 Hijacking Attack
5. Relationship to WS-MessageData
5.1 Security Considerations for WS-MessageData and WS-CallBack
6. Appendix
6.1 Schema (Normative)
6.2 Example (Non-Normative)
6.2.1 Protocol Traced
6.2.2 Joe's WSDL
6.2.3 Jane's WSDL
6.3 Use of URIs (Normative)
6.4 Processing WS-CallBack (Normative)
6.5 Extending WS-CallBack (Normative)
6.6 Future Work Items(Non-Normative)
6.7 References (Normative)
Document Conventions
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 [2].
The XML examples are formatted for readability that means in some cases white space has been added in areas where it is not actually allowed.
1.2 Compliance
An implementation is WS-CallBack compliant if it satisfies all of the MUST or REQUIRED level requirements defined in this specification.
The WS-CallBack Model
2.1 Terminology
Header - A "header block" as defined by SOAP 1.2 [12].
WS-CallBack Request - A SOAP message that contains a CallBack header.
WS-CallBack Response - A SOAP message that is sent in response to a WS-CallBack request.
WS-CallBack sender - A SOAP sender that sends a WS-CallBack request.
WS-CallBack receiver - A SOAP receiver that receives a WS-CallBack request and generates WS-CallBack responses.
2.2 Protocol
The Web Service CallBack Protocol uses the following sequence of messages:
- A WS-CallBack sender sends a WS-CallBack request containing a CallBack header with a callbackLocation element.
- The WS-CallBack receiver then sends its response(s) to the URI listed in the callbackLocation element.
In the absence of an explicit out-of-band agreement the scheme of the URI in the first callbackLocation element MUST be of the same scheme used to deliver the WS-CallBack request. E.g. if the request was delivered over HTTP and there is no explicit agreement to the contrary then the URL in the callbackLocation element must be of type "http".
It is possible that the WS-CallBack receiver may have the WSDL for the WS-CallBack sender and that WSDL may contain a soap:address element in the binding. This situation could cause confusion as the WS-CallBack receiver wouldn't know if they should send the response to the address specified in the CallBack header or to the address in the soap:address element in the WSDL. In order to resolve this confusion the call back location in the CallBack header MUST take precedence over the value in the soap:address.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<wscb:CallBack
xmlns:wscb="http://www.openuri.org/2003/02/soap/callback/"
s:mustUnderstand="1">
<wscb:callbackLocation>
http://example.com/foo/CallBackService
</wscb:callbackLocation>
</wscb:CallBack>
</s:Header>
<s:Body> <!-- contents omitted --> </s:Body>
</s:Envelope>
|
Example 1. - WS-CallBack Request
2.2 Faults
WS-CallBack faults are expressed as XML elements in the detail element of a SOAP fault element. All listed faults are part of the http://www.openuri.org/2003/02/soap/callback/ namespace.
Depending on the particular transport binding being used it may not always be possible to return the callbackNotSupported, callbackLocationURISchemeUnacceptable or cannotKeepCallBackContract faults in which case the faults must be dropped.
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
xmlns="http://www.openuri.org/2003/02/soap/callback/">
<s:Body>
<s:Fault>
<s:faultcode>s:Client</s:faultcode>
<s:faultstring>callbackLocation MUST be a HTTP URL
</s:faultstring>
<s:detail>
<callbackLocationURIUnacceptable/>
</s:detail>
</s:Fault>
</s:Body>
</s:Envelope>
|
Example 2. - An example of a SOAP callbackLocationURISchemeUnacceptable fault
2.2.1 callbackHeaderMalformed
The callbackHeader failed schema validation. This fault SHOULD be marked as a SOAP client fault.
2.2.2 callbackLocationURISchemeUnacceptable
Specifies that the URI scheme in the first callbackLocation element is not acceptable to the WS-CallBack receiver. This fault SHOULD be marked as a SOAP client fault.
2.2.3 callbackLocationURILengthUnacceptable
Specifies that the length of the URI in the first callbackLocation element is not acceptable to the WS-CallBack receiver. This fault SHOULD be marked as a SOAP client fault.
2.2.4 callbackNotSupported
The WS-CallBack receiver is not willing to use WS-CallBack messaging for this operation. The WS-CallBack receiver MUST be able to return this fault synchronously if a synchronous transport is being used. This fault SHOULD be marked as a SOAP client fault.
2.2.5 cannotKeepCallBackContract
The WS-CallBack receiver is not able to keep to the negotiated out-of-band contract (see section 4.3) and so will not process the WS-CallBack request. For example, the WS-CallBack sender and receiver may have agreed that the sender will wait no more than 20 seconds for a response but due to system problems the WS-CallBack receiver now needs more time then that and so cannot process the request. The SOAP fault SHOULD contain human readable information on the nature of the contract violation. This fault SHOULD be marked as a SOAP client fault.
2.3 Multiple callbackLocation Elements
The definition of the CallBack header schema is such that it is possible to place more than one callbackLocation element inside of the CallBack header. It is expected that future versions of this specification will specify how to take advantage of this extensibility.
However, WS-CallBack senders that are compliant with this version of the WS-CallBack specification MUST NOT send more than one callbackLocation element inside of the CallBack header.
WS-CallBackreceivers that are compliant with this version of the WS-CallBack specification MUST be able to successfully process CallBack headers with multiple callbackLocation elements but MUST ignore all elements but the first one.
A WS-CallBack receiver receiving the WS-CallBack request in Example 3 must treat it as if it were identical to the WS-CallBack request in Example 1 because it would ignore the second callbackLocation element.
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<wscb:CallBack
xmlns:wscb="http://www.openuri.org/2003/02/soap/callback/"
s:mustUnderstand="1">
<wscb:callbackLocation>
http://example.com/foo/CallBackService
</wscb:callbackLocation>
<wscb:callbackLocation>
ftp://example.org/bar/Backy
</wscb:callbackLocation>
</wscb:CallBack>
</s:Header>
<s:Body> <!-- contents omitted --> </s:Body>
</s:Envelope>
|
Example 3. - A WS-CallBack request with multiple callbackLocation values
2.4 Configuration Parameters
The WS-CallBack sender and WS-CallBack receiver using out-of-band mechanisms must agree upon the following parameters.
2.4.1 UniqueResponses
WSDL 1.1 only directly understands two types of message exchange patterns, 1:0 and 1:1. That is, one request results in either no responses or exactly one response. But in practice, especially in asynchronous systems such as those enabled by WS-CallBack, a single request may potentially produce multiple responses.
For example, one can easily imagine a 1:3 message exchange pattern where a single request may result in three responses. The first response would confirm delivery of the message. The second response would confirm that the message has been processed. The third response would deliver the output of the processing.
Another common example is a 1:N message exchange pattern. For example, if someone sends in a subscription to a notification channel then the subscriber may potentially receive an unbounded number of responses.
In practice message patterns such as those described previously have been implemented by defining multiple WSDL operations but not explicitly expressing the relationship between those operations. This lack of explicitness leads to interoperability problems, as both sides of the conversation may not necessarily share the same expectations regarding what message exchange pattern to use.
This is an area currently being investigated by the WSDL 1.2 working group and will almost certainly be investigated by the new W3C choreography working group.
In the meantime WS-CallBack implementers need to recognize that WSDL 1.1 cannot fully express many of their message exchange patterns and so it is necessary for them to use some alternate mechanism to come to agreement with their partners as to what message exchange pattern to use.
2.4.2 RepeatResponses
Thevast majority of Web Services communications have occurred over HTTP where SOAP requests are sent in HTTP requests and SOAP responses are sent in HTTP responses. In this framework it is quite literally impossible to repeat a response.
However in the asynchronous world enabled by WS-CallBack there are a number of reasons why an asynchronous response may be repeated.
For example, if SMTP is being used as the transport then it is possible for a message to be duplicated in route due to malfunctioning or improperly configured mail forwarding software. It is also possible for messages to be intentionally repeated for reliability reasons.
WS-CallBack does not directly address issues of duplicate detection or reliable messaging. These are felt to be largely orthogonal to WS-CallBack's feature set. But implementers must be aware of these issues and must agree with their communication partners as to how they are to be addressed. Implementers are encouraged to look at WS-Acknowledgement as a mechanism to address both concerns.
2.4.3 WaitTime
A WS-CallBack sender cannot assume that a WS-CallBack Request will necessarily result in receiving a WS-CallBack Response. Any number of problems may occur from network failures to a system failure of the WS-CallBack receiver.
Assuch, in almost every case, both parties to a WS-CallBack communication will use timeouts.
For example, if after a certain period of time a WS-CallBack response is not received then the WS-CallBack sender will assume that a response will never be received and will take alternate action.
In order to prevent potentially expensive misunderstandings it is critical that the WS-CallBack sender and the WS-CallBack receiver agree as to the timeouts they will use. Otherwise situations can arise where the WS-CallBack receiver thinks they have time N to respond and the WS-CallBack sender expects a response in time M and N > M.
To prevent these types of misunderstandings the optional WaitTime configuration parameter is introduced. It specifies the amount of time the WS-CallBack sender is willing to wait for a response from the WS-CallBack receiver. After the expiration of WaitTime the WS-CallBack receiver MUST assume that the WS-CallBack sender MAY no longer accept a response and so the WS-CallBack sender MAY silently discard any responses it receives.
It is possible in the case of complicated message exchange patterns that each response may have its own unique WaitTime value.
2.4.4 URISchemes
URISchemes is a list of URI schemes that the WS-CallBack receiver is willing to accept in a callbackLocation value. It is possible that the URIs may be further qualified with information such as acceptable domain names, IP addresses, paths, etc.
2.4.5 URILength
The maximum acceptable length for a URI listed in the callbackLocation element.
3. WSDL 1.1 Message Exchange Patterns
This specification focuses exclusively on WSDL 1.1 related message exchange patterns (MEPs) as implemented by widely deployed WSDL 1.1 systems. Unfortunately the available MEPs are not able to describe the full range of message flows enabled by WS-CallBack. As such WS-CallBack assumes that at the WSDL level WS-CallBack requests and responses will be modeled as one-way operations.
For example, imagine a Web Service that sends a GetQuote request message and expects to get back two responses, an Acknowledgement message confirming delivery and a GetQuoteResponse or SOAP fault message with the response/fault
WS-CallBack sender WS-CallBack receiver
WS-CallBack GetQuote Request
---------------------------------------------------------------------->
WS-CallBack Acknowledgement Response
<----------------------------------------------------------------------
WS-CallBack GetQuoteResponse Response or Fault
<----------------------------------------------------------------------
|
Example 4. - Example of a 1 request/2 response WS-CallBack message pattern.
This pattern involves 1 request and 2 responses. This isn't a message pattern that existing WSDL 1.1 deployments can directly express. WSDL 1.2 is expected to resolve this problem.
All WS-CallBack implementations that use WSDL 1.1 and support HTTP MUST support the one-way operation bound to the HTTP transport. By common convention this involves sending a SOAP message in the HTTP request and a 202 HTTP response with no HTTP message body.
Therefore if Example 4 were implemented using WSDL 1.1 and HTTP then its on the wire behavior would be:
WS-CallBack sender WS-CallBack receiver
HTTP Request + WS-CallBack GetQuote Request
---------------------------------------------------------------------->
HTTP 202 Response
<----------------------------------------------------------------------
WS-CallBack Acknowledgement Response
<----------------------------------------------------------------------
WS-CallBack GetQuoteResponse Response or Fault
<----------------------------------------------------------------------
HTTP 202 Response
---------------------------------------------------------------------->
HTTP 202 Response
---------------------------------------------------------------------->
|
Example 5 - HTTP Binding of Example 4
Note that Example 5. uses the HTTP/1.1 pipelining feature to maximize performance.
WSDL 1.1 also contains the ability to specify both solicit/response and notification operations but neither will be used here as in practice the majority of widely used WSDL 1.1 implementations do not support these operations.
One peculiarity of the interaction between WS-CallBack and WSDL 1.1 is the handling of SOAP faults. One-Way operations in WSDL 1.1 are defined by an input element and inputs are intended for handling SOAP requests. The intention appears to be that the input would handle the SOAP request, output the SOAP response and fault the SOAP faults. In theory one could specify a one-way operation with an input and fault element but in practice it isn't clear how widely this behavior would be supported.
However if a WS-CallBack response is a SOAP fault then there must be a way to return the SOAP fault in a one-way operation. To get around this problem WS-CallBack senders that wish to be able to receive WS-CallBack responses containing a SOAP fault must define at least one one-way operation whose input element's message definition is a SOAP fault.
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:s="http://www.w3.org/2001/XMLSchema"
xmlns:soapenvelope="http://schemas.xmlsoap.org/soap/envelope/"
user="..." targetNamespace="...">
<types>
<s:schema attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">
<s:import namespace="http://schemas.xmlsoap.org/soap/envelope"
schemaLocation="http://schemas.xmlsoap.org/soap/envelope/"/>
</s:schema>
</types>
<message name="Fault">
<part name="parameters" element="soapenvelope:Fault"/>
</message>
<portType name="...">
...
<operation name="Fault">
<input message="user:Fault"/>
</operation>
...
</portType>
...
</definitions>
|
Example 6. - Example of a SOAP fault one-way operation
Only one Fault operation is needed per WS-CallBack sender portType.
The WS-CallBack sender's WSDL (v 1.1) will have the following form:
PortType
AsynchResponse1 - One-Way Operation
....
AsynchResponseN - One-Way Operation
Fault - One-Way Operation
|
Figure 1. - WS-CallBack sender's WSDL pattern
For every unique WS-CallBack request the WS-CallBack sender wants to send there must be a one-way operation to accept back the response. In addition there must be a Fault one-way operation on the PortType to accept any asynchronous SOAP faults.
The WS-CallBack receiver's WSDL will have the following form:
PortType
AsynchRequest1 - One-Way Operation + CallBack Header
...
AsynchRequestN - One-Way Operation + CallBack Header
|
Figure 2. - WS-CallBack receiver's WSDL pattern
4. Security Considerations
4.1 Redirect Attack
WS-CallBack allows a sender to instruct a receiver to send the results of a command to some arbitrary destination. The typical attack used in such a situation is called a redirect attack. Its general form is:
Step 1. - The Black Hat machine makes an authorized request to the Naive machine.
Step 2. - The Naive machine sends the response to the destination specified by the Black Hat machine. The destination is either a Victim machine or a confederate of the Black Hat machine.
4.1.1 Variations on a Theme
Below are a few examples of how a redirect attack could be used. This list is not intended to be exhaustive but rather to give the reader a sense of the type of vulnerabilities one is likely to encounter when using WS-CallBack.
If the Black Hat machine wants to leak data but is restricted in whom it can send information to it could use a redirect attack to have the Naive machine send the data to the Black Hat's confederate. The Black Hat can use the callback URL itself or even a Message ID to encode the information it wishes to leak out.
If the Black Hat machine wants to launch an attack on a Victim machine but wants to cover its tracks then it can use a redirect attack to cause an attack message to be sent to the Victim machine. For example, the Victim machine may have buffer overflow problems somewhere in its XML Data handling routines so the Black Hat machine could send a request with a very large callbackLocation URL or RefToMessageId (if one is used). A variation on this attack is to use the Naive machine to launch a denial of service attack. For example, the Black Hat could send in a query to the Naive machine that would generate an enormous response that would then be directed at the Victim machine.
If the Black Hat machine wants to launch an attack on a Victim machine but the Victim machine doesn't trust the Black Hat machine but does trust the Naive Machine then the redirect attack would effectively allow the Black Hat machine to masquerade as the Naive Machine. This attack is particularly effective when systems use IP or DNS based authorization mechanisms.
4.1.2 Layered Security
Dealing with redirection attacks requires multiple layers of security both to try and stop the attack and to be able to catch the attackers after the fact. The following are some examples of the type of security one should implement alongside of a WS-CallBack system.
- Only enable access to WS-CallBack for authenticated requestors. Everyone has a general responsibility for the well-being of the Internet and allowing 'open' machines to accept WS-CallBack requests from arbitrary requestors directly threatens that well-being. Public machines SHOULD only use synchronous communication or polling even though both techniques are significantly less effective than true asynchronous communication.
- Enhance one's access control lists to not only include who is authorized to access a machine but also where that requestor is authorized to have responses sent to.
- Authenticate the machine that the response is being sent to before sending the entire message. This helps to prevent accidents and may help to reduce the effectiveness of some denial of service attacks.
- Enable real time monitoring of the network in order to detect any odd patterns. Leak attacks in particular often require large numbers of messages to be effective.
- Log all requests and the redirected responses along with as much network and authentication information as possible. This will enable post-attack analysis. Such analysis can enable everything from improving security to providing an audit trail for use in convicting the attacker. Issues related to creating and maintaining logs that can be successfully used in a court of law are outside the scope of this specification. Administrators need to also be sensitive to the user privacy implications of logs and so put into place appropriate data retention policies.
Experience teaches that some systems in lieu of implementing the previous security measures will decide to use IP or DNS based authentication in order to ensure that responses are sent to the same machine that sent the request. Typically this type of authentication causes more problems than it solves and is not very secure.
For example, a system may check the IP address used in a request and then only be willing to send responses to a call back URL that uses the same IP address. However many systems operate behind a firewall so the IP address used on an outgoing request will almost certainly not match the IP address used to accept an asynchronous response. SOAP systems in particular seem to be moving toward an intermediary based model where messages may pass through multiple SOAP intermediaries before finally being delivered. There will therefore often be situations where the intermediary accepting the asynchronous response is different than the one that passed on the request. In addition IP spoofing attacks can be used to get around this sort of security.
Some systems try to use DNS authentication. The receiver of the message performs a reverse DNS lookup on the IP address used in the request and then is only willing to send responses to call back URLs that come from the same DNS address or perhaps the same DNS domain. As HTTP cookies so eloquently demonstrated DNS based authentication just doesn't work in practice. For example, if the incoming IP address maps to a.example.com then what DNS address should the CallBack URL be allowed to have? Only a.example.com? That probably won't work as the pool of request and response IP addresses (and the DNS addresses they map to) are likely to be different for security and routing reasons. How about *.example.com? Example.com could be a hosting system and so the owner of a.example.com and b.example.com may be completely different. In which case accepting *.example.com would let a.example.com launch an attack against b.example.com. Etc. In addition the requesting IP address may not necessarily be mapped into DNS for security and ease of administration reasons. Finally, DNS is generally not terribly secure so relying on DNS for security is generally a bad idea.
4.2 Open Port Attack
Most systems go to great lengths to prevent incoming messages for security reasons. For example, most networks are configured such that machines able to receive externally initiated network connections are placed outside of the firewall while machines inside of the firewall are only allowed to send outgoing messages and receive synchronous replies. In cases where machines inside of the firewall need to be able to receive externally initiated connections systems will usually try to obscure the exact location (e.g. IP address, DNS address, port, path, etc.) of any open ports used to receive those externally initiated communications.
However all this security is for naught if the receiver of a WS-CallBack request is a Black Hat machine as the callback URI will identify an open port on the requestor's system.
In general security through obscurity is a long outmoded concept that has been repeatedly proven not to work. Any system that exposes an externally addressable port should take it as a given that the address is available to everyone. While this doesn't mean that a system should go out of its way to advertise such addresses neither should it rely on their secrecy.
The threats against an open port are well known and the techniques to deal with them are outside the scope of this specification. One suggestion worth mentioning is that call back URLs should be short lived and should be able to authenticate any incoming messages so as to ensure they are coming from the expected source.
4.3 Hijacking Attack
WS-CallBack, if improperly deployed, can be extremely vulnerable to hijacking and man-in-the-middle (MIM) attacks.
For example, a sender sends a request to the responder with a CallBack header. The request is sent over a SSL connection using mutual authentication. Since the responder had already authenticated the sender it wasn't felt necessary to re-authenticate the sender when sending the response.
The problem with the previous logic is that because the response is being sent asynchronously it is almost certainly being sent on a completely new connection. Therefore any previous authentications are irrelevant.
The Black Hat can let the sender and responder mutually authenticate each other on the request and then intercept the unprotected response. They can even launch a MIM attack so that neither the sender nor the responder will realize what happened.
To prevent this sort of attack one must not only use mutual authentication on the request but also the response.
5. Relationship to WS-MessageData
WS-MessageData can play a very useful role when used in conjunction with WS-CallBack. For example, if a response contains the RefToMessageId element in a WS-MessageData header then debugging can be made easier as one can trace a message and its response between two systems. WS-MessageData is also very useful in building systems that enable duplicate messages to be transmitted and processed reasonably.
WS-MessageData can also be useful as a correlation mechanism. In those cases where the correlation ID cannot be encoded in the call back URI one can instead rely on the messageID provided by WS-MessageData.
5.1 Security Considerations for WS-MessageData and WS-CallBack
Implementers must be careful in relying on the data in a MessageData header. As described in the security considerations section of WS-MessageData a MessageId or RefToMessageId value could be wrong, either accidentally or maliciously.
Implementers must be especially careful when attempting to use the combination of WS-MessageData and WS-CallBack to establish a non-reputable correlation between the request and response.
For example, imagine Eve sends a signed message ordering 2 widgets with Message ID FOO to Bob. Bob then sends a signed response that contains an 'order approved' message and a RefToMessageId of FOO. Eve then sends a second signed message to Bob ordering 10,000 widgets, which is more than Eve is authorized to order, and also uses Message ID FOO.
There now exists an ambiguity, even if Bob catches the repeated message ID and issues an error Eve can still claim that his original approval was for the 10,000 widget request, not the 2 widget request.
Just having a RefToMessageId value inside of a signed message is not enough to prove the correlation between the response and the original request. One needs to repeat the entire contents of the request in the response in order to prove correlation. The contents can either be repeated indirectly, e.g. Bob's original response would say "This is an approval of an order for 2 widgets issues on this date for this person in response to request RefToMessageId" and/or the response could contain a complete copy or a cryptographically secure hash of the original request.
This specification does not currently provide a mechanism to include a copy/hash of the original request inside the response although this would be a fairly obvious extension to make in the future.
6. Appendix
6.1 Schema (Normative)
The schema for the CallBack header is defined using XML-Schema [14][15].
<s:schema
>targetNamespace="http://www.openuri.org/2003/02/soap/callback/" <pre
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" <pre
xmlns:s="http://www.w3.org/2001/XMLSchema" <pre
xmlns:asynch="http://www.openuri.org/2003/02/soap/callback/" <pre
elementFormDefault="qualified"<pre
attributeFormDefault="qualified"><pre
<s:import namespace="http://schemas.xmlsoap.org/soap/envelope"<pre
schemaLocation="http://schemas.xmlsoap.org/soap/envelope/"/><pre
<s:element name="CallBack" type="asynch:CallBackType"/><pre
<s:complexType name="CallBackType"><pre
<s:sequence><pre
<s:any processContents="lax" minOccurs="0"<pre
maxOccurs="unbounded"/><pre
<s:element name="callbackLocation" type="s:anyURI"<pre
maxOccurs="unbounded"/><pre
<s:any processContents="lax" minOccurs="0" <pre
maxOccurs="unbounded"/><pre
</s:sequence><pre
<s:anyAttribute/><pre
</s:complexType><pre
<s:complexType name="callbackErrors"><pre
<s:choice><pre
<s:element name="callbackHeaderMalformed"/><pre
<s:element name="callbackLocationURISchemeUnacceptable"/><pre
<s:element name="callbackLocationURILengthUnacceptable"/><pre
<s:element name="callbackNotSupported"/><pre
<s:element name="cannotKeepCallBackContract"/><pre
</s:choice><pre
</s:complexType><pre
</s:schema>
|
6.2 Example (Non-Normative)
Joe and Jane wish to implement a Web Service using WS-CallBack and WSDL 1.1 over HTTP. The Web Service consists of two separate requests, GetQuote and stockSymbolToCompanyName. Below are protocol traces of exchanges between Joe and Jane as well as the WSDLs they used.
In these examples Joe is the WS-CallBack sender and Jane is the WS-CallBack receiver.
6.2.1 Protocol Trace
6.2.1.1 Successful getQuote
Joe ---getQuote + HTTP Request ------------------> Jane
<----------202 HTTP Response------------------
<--getQuoteResponse + HTTP Request------------
-----------202 HTTP Response----------------->
|
Example 7. - Jane successfully responds to Joe's WS-CallBack getQuote request
POST /quoteservice HTTP/1.1
Host: jane.example.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<wscb:CallBack
xmlns:wscb="http://www.openuri.org/2003/02/soap/callback/"
s:mustUnderstand="1">
<wscb:callbackLocation>
http://joe.example.com/quotecallback?xyz123
</wscb:callbackLocation>
</wscb:CallBack>
</s:Header>
<s:Body>
<GetQuote xmlns="http://example.com/quoteservice">
BEAS
</GetQuote>
</s:Body>
</s:Envelope>
HTTP/1.1 202 Accepted
Content-Length: 0
|
Example 8. - Joe's getQuote request
POST /quotecallback?xyz123 HTTP/1.1
Host: joe.example.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="UTF-8"?><
s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<GetQuoteResponse xmlns="http://example.com/quoteservice">
9999
</GetQuoteResponse>
</s:Body>
</s:Envelope>
HTTP/1.1 202 Accepted
Content-Length: 0
|
Example 9. - Jane's GetQuoteResponse
6.2.1.2 Failed stockSymbolToCompanyName
Joe ---getQuote + HTTP Request ------------------> Jane
<----------202 HTTP Response------------------
<--SOAP Fault + HTTP Request------------------
-----------202 HTTP Response----------------->
|
Example 10. - Jane responds with a SOAP fault to Joe's WS-CallBack stockSymbolToCompanyName request
POST /quoteservice HTTP/1.1
Host: jane.example.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<wscb:CallBack
xmlns:wscb="http://www.openuri.org/2003/02/soap/callback/"
s:mustUnderstand="1">
<wscb:callbackLocation>
http://joe.example.com/quotecallback?230238a
</wscb:callbackLocation>
</wscb:CallBack>
</s:Header>
<s:Body>
<stockSymbolToCompanyNameRequest
xmlns="http://example.com/quoteservice">
BEAS
</stockSymbolToCompanyNameRequest>
</s:Body>
</s:Envelope>
HTTP/1.1 200 O.K.
Content-Length: 0
|
Example 11. - Joe's stockSymbolToCompanyNameRequest
POST /quotecallback?230238a HTTP/1.1
Host: joe.example.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body xmlns:wsc="http://www.openuri.org/2003/02/soap/callback/">
<s:Fault>
<s:Faultcode>s:Server</s:Faultcode>
<s:Faultstring>Can't guarantee a reply within the agreed time limit
due to internal system issues.
</s:Faultstring>
</s:Fault>
<s:Detail>
<wsc:cannotKeepCallBackContract/>
</s:Detail>
</s:Body>
</s:Envelope>
HTTP/1.1 202 Accepted
Content-Length: 0
|
Example 12. - Jane's SOAP Fault response
6.2.2 Joe's WSDL
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:s="http://www.w3.org/2001/XMLSchema"
xmlns:user="http://www.example.com/quoteservice/"
xmlns:soapenvelope="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
targetNamespace="http://www.example.com/quoteservice/">
<types>
<s:schema attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">
<s:import namespace="http://schemas.xmlsoap.org/soap/envelope"
schemaLocation="http://schemas.xmlsoap.org/soap/envelope/"/>
</s:schema>
<s:schema attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="http://www.example.com/quoteservice/">
<s:element name="GetQuoteResponse" type="s:decimal"/>
<s:element name="stockSymbolToCompanyNameResponse"
type="s:string"/>
</s:schema>
</types>
<message name="GetQuoteResponse">
<part name="GetQuoteResponse" element="user:GetQuoteResponse"/>
</message>
<message name="stockSymbolToCompanyNameResponse">
<part name="stockSymbolToCompanyNameResponse"
element="user:stockSymbolToCompanyNameResponse"/>
</message>
<message name="Fault">
<part name="Fault" element="soapenvelope:Fault"/>
</message>
<portType name="JoeWSCallBackSender">
<operation name="GetQuoteResponse">
<input message="user:GetQuoteResponse"/>
</operation>
<operation name="stockSymbolToCompanyNameResponse">
<input message="user:stockSymbolToCompanyNameResponse"/>
</operation>
<operation name="Fault">
<input message="user:Fault"/>
</operation>
</portType>
<binding name="JoeWSCallBackSender" type="user:JoeWSCallBackSender">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="GetQuoteResponse">
<soap:operation style="document"/>
<input>
<soap:body use="literal"/>
</input>
</operation>
<operation name="stockSymbolToCompanyNameResponse">
<soap:operation style="document"/>
<input>
<soap:body use="literal"/>
</input>
</operation>
<operation name="Fault">
<soap:operation style="document"/>
<input>
<soap:body use="literal"/>
</input>
</operation>
</binding>
<service name="JoeWSCallBackSender">
<port name="JoeWSCallBackSender"
binding="user:JoeWSCallBackSender">
<soap:address
location="http://joe.example.com/quotecallback"/>
</port>
</service>
</definitions>
|
6.2.3 Jane's WSDL
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:s="http://www.w3.org/2001/XMLSchema"
xmlns:user="http://www.example.com/quoteservice/"
xmlns:soapenvelope="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:callback="http://www.openuri.org/2003/02/soap/callback/"
targetNamespace="http://www.example.com/quoteservice/">
<types>
<s:schema
targetNamespace="http://www.openuri.org/2003/02/soap/callback/"
elementFormDefault="qualified"
attributeFormDefault="qualified">
<s:import
namespace="http://www.openuri.org/2003/02/soap/callback/"
schemaLocation="callback.xsd"/>
</s:schema>
<s:schema attributeFormDefault="qualified"
elementFormDefault="qualified"
targetNamespace="http://www.example.com/quoteservice/">
<s:element name="GetQuote" type="s:string"/>
<s:element name="stockSymbolToCompanyNameRequest"
type="s:string"/>
</s:schema>
</types>
<message name="GetQuoteIn">
<part name="body"element="user:GetQuote"/>
</message>
<message name="stockSymbolToCompanyNameIn">
<part name="body"
element="user:stockSymbolToCompanyNameRequest"/>
</message>
<message name="callbackheader">
<part name="callbackheaderpart" element="callback:CallBack"/>
</message>
<portType name="JaneWSCallBackReceiver">
<operation name="GetQuote">
<input message="user:GetQuoteIn"/>
</operation>
<operation name="stockSymbolToCompanyName">
<input message="user:stockSymbolToCompanyNameIn"/>
</operation>
</portType>
<binding name="JaneWSCallBackReceiver"
type="user:JaneWSCallBackReceiver">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="GetQuote">
<soap:operation style="document"/>
<input>
<soap:header message="user:callbackheader"
part="callbackheaderpart" use="literal"/>
<soap:body parts="body" use="literal"/>
</input>
</operation>
<operation name="stockSymbolToCompanyName">
<soap:operation style="document"/>
<input>
<soap:header message="user:callbackheader"
part="callbackheaderpart" use="literal"/>
<soap:body parts="body" use="literal"/>
</input>
</operation>
</binding>
<service name="JaneWSCallBackReceiver">
<port name="JaneWSCallBackReceiver"
binding="user:JaneWSCallBackReceiver">
<soap:address location="http://jane.example.com/quoteservice"/>
</port>
</service>
</definitions>
|
6.3 Use of URIs (Normative)
WS-CallBack uses URIs for all identifiers. To WS-CallBack, a URI is simply a formatted string that identifies-via name, location, or any other characteristic-a resource on the Web.
This section defines the rules and conventions governing the URIs as values.
The use of IP addresses in URIs SHOULD be avoided whenever possible (see RFC 1900 [1]). However, when used, the literal format for IPv6 addresses in URI's as described by RFC 2732 [6] MUST be supported.
All URIs used in WS-CallBack MAY be either absolute or relative. WS-CallBack does not define a base URI but relies on the mechanisms defined in XML Base[13] and RFC 2396[3] for establishing a base URI against which relative URIs can be made absolute.
SOAP 1.1 does not explicitly support XML Base. Therefore, the BASE URI infoset item may not be explicitly set by a SOAP 1.1 processor. A WS-CallBack processor MAY be required to determine the Base URI as per the rules for resolving URIs in XML Base. An example of this is examining the xml:base attribute in the SOAP 1.1 envelope.
SOAP 1.2 [12] explicitly supports XML Base. A WS-CallBack node MUST use the Base URI as set by a SOAP 1.2 processor
WS-CallBack does not define equivalence rules for URIs as these are defined by the individual URI schemes and by RFC 2396 [3] (also see the W3C TAG's [16] work on the use of URIs for comparison [17]). It is recommended that WS-CallBack senders do not rely upon the WS-CallBack receiver to determine equivalence rules in addition to URI schemes and RFC 2396.
WS-CallBack does not place an a priori limit on the length of a URI but all WS-CallBack compliant receivers MUST support URI values in the callbackLocation element of at least 2048 bytes in length.
6.4 Processing WS-CallBack (Normative)
WS-CallBack is designed to be extended such that new elements and attributes in the CallBack header can be added without requiring central registration. However this means that a WS-CallBack sender could add in values to the CallBack header that the WS-CallBack receiver may not understand.
To deal with this possibility, upon receiving a CallBack header the WS-CallBack receiver MUST ignore any unrecognized elements/attributes of the CallBack header for purposes of CallBack header processing. Ignoring an element means acting as if the element and its progeny had not been sent in the message. Ignoring an attribute means acting as if the attribute had not been sent in the message. Note that this does not require that the elements be physically removed, only ignored for CallBack header processing purposes.
If a message is received with unrecognized elements in the CallBack header it is reasonable to expect that if the message is logged the serialized version would include the unrecognized elements.
For example, imagine that a WS-CallBack receiver that is only compliant with this specification (e.g. it has not been enhanced to support extended elements) received the following WS-CallBack request:
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
<wscb:CallBack
xmlns:wscb="http://www.openuri.org/2003/02/soap/callback/"
xmlns:ncs="http://www.example.net/newcallbackstuff"
s:mustUnderstand="1" ncs:foo="bar">
<ncs:conf>
<ncs:lk3>15</ncs:lk3>
</ncs:conf>
<wscb:callbackLocation>
http://example.com/foo/CallBackService
<ncs:acksetting>ncs:securitylevel4</ncs:acksetting>
</wscb:callbackLocation>
<wscb:multiresponse><wscb:alwed/></wscb:multiresponse>
</wscb:CallBack>
</s:Header>
<s:Body> <!-- contents omitted --> </s:Body>
</s:Envelope>
|
Example 13. - A WS-CallBack request with extended elements
The message in the previous example should 'look' to the WS-CallBack receiver as if it were identical to the message in Example 1. The various highlighted entries would be ignored. The ncs:foo attribute would be ignored because it is unrecognized. The WS-CallBack receiver never even has to look at the ncs:lk3 element because it would automatically be removed as a consequence of its parent, ncs:conf, not being recognized. The same goes for ncs:acksetting.
The multiresponse is interesting because it comes from the WS-CallBack namespace. But there is no multiresponse defined in this specification and as previously stated the WS-CallBack receiver is only compliant with this specification. The WS-CallBack receiver is to ignore elements not because of their namespace but because they are not defined in this specification. So even though multiresponse comes from the WS-CallBack namespace, it wasn't defined in this specification and therefore would be ignored. In a sense the alwed element, much like the ncs:lk3 element, would never be 'seen' because its parent, multiresponse, was pruned.
6.5 Extending WS-CallBack (Normative)
A new child element to be added to WS-CallBack can be defined by a specification that makes a normative reference to this specification and then defines the new element.
However implementers MUST NOT define extension elements that come from XML namespaces [9] they do not own.
The only requirement on an extension is that its syntax and semantics MUST be backwards compatible with the syntax and semantics defined in this specification.
The term 'backwards compatible' in this context means that the extended version of CallBack would be encoded such that an implementation based exclusively on this specification would be able to successfully process the incoming CallBack header in the manner defined by this specification.
6.6 Future Work Items (Non-Normative)
Write an appendix explaining why we choose not to allow asynchronous responses to optionally be sent synchronously when SOAP messages are transmitted on a synchronous transport. Make sure to explain that outside of a very small number of cases that do not seem generally relevant to Web Services this optimization doesn't actually provide much performance advantage. Then illustrate the problems implementing such a mechanism over WSDL 1.1 and the bogus 'not a response' SOAP faults one has to introduce to make it work. It's a classic case of a lot of complexity for very little advantage.
Investigate using wsu:PortReference, or newer version for the Address/reference structure.
6.7 References (Normative)
[1] B. Carpenter, Y. Rekhter, "Renumbering Needs Work", RFC 1900, IAB, February 1996.
[2] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels," Harvard University, March 1997.
[3] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax," MIT/LCS, U.C. Irvine, Xerox Corporation, August 1998.
[4] Y. Goland, E. Whitehead, A. Faizi, S. Carter, D. Jensen, " HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, Microsoft, UC Irvine, Netscape, Novell, February 1999.
[5] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1," U.C. Irvine, DEC W3C/MIT, DEC, W3C/MIT, W3C/MIT, January 1997.
[6] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6 Addresses in URL's," Nokia, IBM, AT&T, December 1999.
[7] OASIS ebXML Messaging Services Technical Committee, "Message Service Specification Version 2.0", April 2002.
[8] W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000, http://www.w3.org/TR/2000/REC-xml-20001006
[9] W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999, http://www.w3.org/TR/1999/REC-xml-names-19990114/,
[10] W3C Note "Simple Object Access Protocol (SOAP) 1.1"
[11] W3C Note "Web Services Description Language (WSDL) 1.1"
[12] W3C Working Draft "Simple Object Access Protocol (SOAP) 1.2 Part 1"
[13] W3C Recommendation "XML Base", Jonathan Marsh, 27 June 2001, "http://www.w3.org/TR/2001/REC-xmlbase-20010627/
[14] W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001, " http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/"
[15] W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001, "http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/"
[16] W3C Technical Architecture Group, " http://www.w3.org/2001/tag/"
[17] Architecture of the World-Wide Web, URI uses chapter, http://www.w3.org/TR/webarch/#uri-use
[18] BEA Proposal "Web Services Message Data (WS-MessageData)", to be published.
