Web Services Extension Framework

1 Introduction

Feature

An abstract piece of functionality typically associated with the exchange of messages between communicating SOAP nodes (see 2 Web Services Extensibility Model).

An optional extension of the SOAP messaging framework (see 2 Web Services Extensibility Model).

Examples of features include "reliability", "security", "correlation", "routing", and

"Message Exchange Patterns" (MEPs)

the concept of message exchange patterns.

Message exchange pattern (MEP)

A template for the exchange of SOAP messages between SOAP nodes enabled by one or more underlying SOAP protocol bindings (see 3 Web Services Protocol Binding Framework). A SOAP MEP is an example of a SOAP feature (see 2.3 Message Exchange Patterns (MEPs)).

2 Web Services Extensibility Model

SOAP provides a simple messaging framework whose core functionality is concerned with providing extensibility. The extensibility mechanisms described below can be used to add capabilities found in richer messaging environments.

2.1 Web Services Features

For the purpose of this specification, the term "feature" is used to identify an extension of the SOAP messaging framework typically associated with the exchange of messages between communicating SOAP nodes. Although SOAP poses no constraints on the potential scope of such features, example features include "reliability", "security", "correlation", and "routing". In addition, the communication might require a variety of message exchange patterns (MEPs) such as one-way messages, request/response interactions, and peer-to-peer conversations. MEPs are considered to be a type of feature, and unless otherwise stated, references in this specification to the term "feature" apply also to MEPs. The request-response MEP specified in [SOAP Part2] illustrates the specification of a MEP feature.

The SOAP extensibility model provides two mechanisms through which features can be expressed: the SOAP Processing Model and the SOAP Protocol Binding Framework. The former describes the behavior of a single SOAP node with respect to the processing of an individual message. The latter mediates the act of sending and receiving SOAP messages by a SOAP node via an underlying protocol.

The SOAP Processing Model enables SOAP nodes that include the mechanisms necessary to implement one or more features to express such features within the SOAP envelope as SOAP header blocks. Such header blocks can be intended for any SOAP node or nodes along a SOAP message path.

A feature expressed as SOAP header blocks is known as a SOAP module, and each module is specified according to the rules in 2.2 SOAP Modules.

When a feature is expressed this way, the combined syntax and semantics of such SOAP header blocks are known as a SOAP Module, and are specified according to the rules in 2.2 SOAP Modules.

In contrast, a SOAP protocol binding operates between two adjacent SOAP nodes along a SOAP message path. There is no requirement that the same underlying protocol is used for all hops along a SOAP message path. In some cases, underlying protocols are equipped, either directly or through extension, with mechanisms for providing certain features. The SOAP Protocol Binding Framework provides a scheme for describing these features and how they relate to SOAP nodes through a binding specification (see 3 Web Services Protocol Binding Framework).

Certain features might require end-to-end as opposed to hop-to-hop processing semantics. While the SOAP Protocol Binding Framework provides for the possibility that such features could be expressed outside the SOAP envelope, it does not define a specific architecture for the processing or error handling of these externally expressed features by a SOAP intermediary. Although the SOAP Protocol Binding Framework allows end-to-end features to be expressed outside the SOAP envelope, no standard mechanism is provided for the processing by intermediaries of the resulting messages. A binding specification that expresses such features external to the SOAP envelope needs to define its own processing rules to which a SOAP node is expected to conform (for example, describing what information is passed along with the SOAP message as it leaves the intermediary). It is recommended that, where practical, end-to-end features be expressed as SOAP header blocks, so that the rules defined by the SOAP Processing Model can be employed.

Certain features might require end-to-end as opposed to hop-to-hop processing semantics. Although the SOAP Protocol Binding Framework allows end-to-end features to be expressed outside the SOAP envelope, no standard mechanism is provided for the processing by intermediaries of the resulting messages. A binding specification that expresses such features external to the SOAP envelope needs to define its own processing rules for those externally expressed features. A SOAP node is expected to conform to these processing rules (for example, describing what information is passed along with the SOAP message as it leaves the intermediary). The processing of SOAP envelopes in accordance with the SOAP Processing Model MUST NOT be overridden by binding specifications.

It is recommended that, where practical, end-to-end features be expressed as SOAP header blocks, so that the rules defined by the SOAP Processing Model can be employed.

2.1.1 Requirements on Features

The specification of a feature MUST include the following:

A URI used to name the feature. This enables the feature to be unambiguously referenced in description languages or during negotiation.
The information (state) required at each node to implement the feature.
The processing required at each node in order to fulfill the obligations of the feature including any handling of communication failures that might occur in the underlying protocol (see also 3.2 Binding Framework).
The information to be transmitted from node to node.
In the case of MEPs:
Any requirements to generate additional messages (such as responses to requests in a request/response MEP).
1. Rules for the delivery or other disposition of SOAP faults generated during the operation of the MEP.
2. The request-response MEP specified in SOAP 1.2 Part 2 [1] illustrates the specification of a MEP feature.

See 2.3 Message Exchange Patterns (MEPs) for additional requirements on MEP features.

2.2 SOAP Modules

A SOAP module is a feature which is expressed as SOAP header blocks.

A module specification follows the following rules. It:

The term 'SOAP Module' refers to the set of syntax and semantics associated with implementing a particular feature (see 2.1 Web Services Features) as SOAP header blocks. A Module is described in a Module Specification, which adheres to the following rules. It:

MUST identify itself with a URI. This enables the module to be unambiguously referenced in description languages or during negotiation.
MUST, if the Module implements a Feature which has already been defined elsewhere, clearly refer to that Feature's URI. Note that a Module may EITHER explicitly refer to a separate Feature in this way OR may implicitly define a Feature simply by describing the semantics of the Module.
MUST clearly and completely specify the content and semantics of the SOAP header blocks used to implement the behavior in question, including if appropriate any modifications to the SOAP Processing model.
The SOAP extensibility model does not limit the extent to which SOAP can be extended. Nor does it prevent extensions from modifying the SOAP processing model from that described in @@@
MAY utilize the property conventions defined in [SOAP Part2], section A Convention for Describing Features and Bindings, in describing the functionality that the module provides. If these conventions are followed, the module specification MUST clearly describe the relationship between the abstract properties and their representations in the SOAP envelope. Note that it is possible to write a feature specification purely in terms of abstract properties, and then write a separate module specification which implements that feature, mapping the properties defined in the feature specification to SOAP header blocks in the SOAP module.
MUST clearly specify any known interactions with or changes to the interpretation of the SOAP body. Furthermore, it MUST clearly specify any known interactions with or changes to the interpretation of other SOAP features (whether or not those features are themselves modules). For example, we can imagine a module which encrypts the SOAP body and inserts a SOAP header block containing a checksum and an indication of the encryption mechanism used. The specification for such a module would indicate that the decryption algorithm on the receiving side is to be run prior to any other modules which rely on the contents of the SOAP body.

2.3 Message Exchange Patterns (MEPs)

A MEP is a template that establishes a pattern for the exchange of messages between SOAP nodes. In general the definition of a message exchange pattern:

A Message Exchnage Pattern (MEP) is a template that establishes a pattern for the exchange of messages between SOAP nodes. The specification of a message exchange pattern MUST:

Is named by a URI.
As mandated by 2.1.1 Requirements on Features, provide a URI to name the MEP.
Describes the life cycle of a message exchange conforming to the pattern.
Describe the life cycle of a message exchange conforming to the pattern.
Describes the temporal/causal relationships of multiple messages exchanged in conformance with the pattern.
Describe the temporal/causal relationships, if any, of multiple messages exchanged in conformance with the pattern (e.g. responses follow requests and are sent to the originator of the request.)
Describes the normal and abnormal termination of a message exchange conforming to the pattern.
Describe the normal and abnormal termination of a message exchange conforming to the pattern.

Underlying protocol binding specifications can declare their support for one or more named MEPs.

In addition to the requirements on all features (see 2.1.1 Requirements on Features), the specification of an MEP feature MUST also include the following:

MEPs are SOAP features, so an MEP specification MUST conform to the requirements for SOAP feature specifications (see 2.1.1 Requirements on Features). An MEP specification MUST also include:

Any requirements to generate additional messages (such as responses to requests in a request/response MEP).
Rules for the delivery or other disposition of SOAP faults generated during the operation of the MEP.

3 Web Services Protocol Binding Framework

SOAP enables exchange of SOAP messages using a variety of underlying protocols. The formal set of rules for carrying a SOAP message within or on top of another protocol (underlying protocol) for the purpose of exchange is called a binding. The SOAP Protocol Binding Framework provides general rules for the specification of protocol bindings; the framework also describes the relationship between bindings and SOAP nodes that implement those bindings. The HTTP binding in [SOAP Part2] illustrates the specification of a binding. Additional bindings can be created by specifications that conform to the binding framework introduced in this chapter.

A SOAP binding specification:

Declares the features provided by a binding.
Describes how the services of the underlying protocol are used to transmit SOAP envelope infosets.
Describes how the services of the underlying protocol are used to honor the contract formed by the features supported by that binding.
Describes the handling of all potential failures that can be anticipated within the binding.
Defines the requirements for building a conformant implementation of the binding being specified.

A binding does not provide a separate processing model and does not constitute a SOAP node by itself. Rather a SOAP binding is an integral part of a SOAP node.

3.1 Goals of the Binding Framework

The goals of the binding framework are:

To set out the requirements and concepts that are common to all binding specifications.
To facilitate homogeneous description in situations where multiple bindings support common features, promoting reuse across bindings.
To facilitate consistency in the specification of optional features.

Two or more bindings can offer a given optional feature, such as reliable delivery, using different means. One binding might exploit an underlying protocol that directly facilitates the feature (e.g., the protocol is reliable), and the other binding might provide the necessary logic itself (e.g., reliability is achieved via logging and retransmission). In such cases, the feature can be made available to applications in a consistent manner, regardless of which binding is used.

3.2 Binding Framework

The creation, transmission, and processing of a SOAP message, possibly through one or more intermediaries, is specified in terms of a distributed state machine. The state consists of information known to a SOAP node at a given point in time, including but not limited to the contents of messages being assembled for transmission or received for processing. The state at each node can be updated either by local processing, or by information received from an adjacent node.

Section @@@ of this specification describes the processing that is common to all SOAP nodes when receiving a message. The purpose of a binding specification is to augment those core SOAP rules with additional processing that is particular to the binding, and to specify the manner in which the underlying protocol is used to transmit information between adjacent nodes in the message path.

The distributed state machine that manages the transmission of a given SOAP message through its message path is the combination of the core SOAP processing operating at each node, in conjunction with the binding specifications connecting each pair of nodes. A binding specification MUST enable one or more

MEP.

MEPs.

In cases where multiple features are supported by a binding specification the specifications for those features MUST provide any information necessary for their successful use in combination. Similarly if a certain feature cannot be used if another feature is present this MUST be specified.

; this binding framework does not provide any explicit mechanism for ensuring such compatibility of multiple features.

In cases where multiple features are supported by a binding specification, the specifications for those features MUST provide any information necessary for their successful use in combination. Similarly, any dependencies of one feature on another (i.e. if successful use of one feature depends on use or non-use of another) MUST be specified. This binding framework does not provide any explicit mechanism for controlling the use of such interdependent features.

The binding framework provides no fixed means of naming or typing the information comprising the state at a given node. Individual feature and binding specifications are free to adopt their own conventions for specifying state. Note, however, that consistency across bindings and features is likely to be enhanced in situations where multiple feature specifications adopt consistent conventions for representing state. For example, multiple features might benefit from a consistent specification for an authentication credential, a transaction ID, etc. The HTTP binding in [SOAP Part2] illustrates one such convention.

As described in, each SOAP message is modeled as an XML Infoset that consists of a document information item with exactly one child: the envelope element information item. Therefore, the minimum responsibility of a binding in transmitting a message is to specify the means by which the SOAP XML Infoset is transferred to and reconstituted by the binding at the receiving SOAP node and to specify the manner in which the transmission of the envelope is effected using the facilities of the underlying protocol.

The binding framework does NOT require that every binding use the XML 1.0 [XML 1.0] serialization as the "on the wire" representation of the Infoset; compressed, encrypted, fragmented representations and so on can be used if appropriate. A binding, if using XML 1.0 serialization of the infoset, MAY mandate that a particular character encoding or set of encodings be used.

Bindings MAY provide for streaming when processing messages. That is, SOAP nodes MAY begin processing a received SOAP message as soon as the necessary information is available. SOAP processing is specified in terms of Envelope XML infosets. Although streaming SOAP receivers will acquire such Infosets incrementally, SOAP processing MUST yield results identical to those that would have been achieved if the entire SOAP envelope were available prior to the start of processing. For example, as provided in @@@, identification of targeted SOAP header blocks, and checking of all mustUnderstand attributes is to be done before successful processing can proceed. Depending on the representation used for the Infoset, and the order in which it is transmitted, this rule might limit the degree to which streaming can be achieved.

Note:

Section @@@ provides that the XML Infoset of a SOAP message MUST NOT include a DTD. Accordingly, a binding that uses the XML 1.0 serialization MUST NOT transmit a DTD; a binding that accepts XML 1.0 serializations MUST fault in a binding specific manner if an XML 1.0 serialization corresponding to a DTD for the SOAP message is received.

Bindings MAY depend on state that is modeled as being outside of the SOAP XML Infoset (e.g. retry counts), and MAY transmit such information to adjacent nodes. For example, some bindings take a message delivery address (typically a URI) that is not within the envelope.

4 Security Considerations

The Web Services Extension Framework does not directly provide any mechanisms for dealing with access control, confidentiality, integrity and non-repudiation. Such mechanisms can be provided as Web Services extensions???. This section describes the security considerations that designers and implementers need to take into consideration when designing and using such mechanisms.

Web Services implementers need to anticipate rogue applications sending intentionally malicious data to a Web service endpoint. It is strongly recommended that a Web service endpoint receiving a message is capable of evaluating to what level it can trust the sender of that message and its contents.

In addition, a binding specification might not address or provide countermeasures for all aspects of the inherent security risks. The binding specification authors ought to identify any such risks as might remain and indicate where further countermeasures would be needed above and beyond those provided for in the binding specification.

Authors of binding specifications need to be aware that Web Services extensions expressed as SOAP header blocks could affect the underlying protocol in unforeseen ways. A message carried over a particular protocol binding might result in seemingly conflicting features. An example of this is a SOAP message carried over HTTP, using the HTTP basic authentication mechanism in combination with a SOAP based authentication mechanism. It is strongly recommended that a binding specification describes any such interactions between the extensions and the underlying protocols.