Web Services Policy 1.5 - Attachment

2.1 Notational Conventions

This specification uses the following syntax within normative outlines:

• The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.

• Characters are appended to elements and attributes to indicate cardinality:

  • "?" (0 or 1)

  • "*" (0 or more)

  • "+" (1 or more)

• The character "|" is used to indicate a choice between alternatives.

• The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.

• This document relies on the XML Information Set [[XML Information Set]]. Information items properties are indicated by the style infoset property.

• XML namespace prefixes (see Table 2-1) are used to indicate the namespace of the element or attribute being defined.

• The ellipses characters "…" are used to indicate a point of extensibility that allows other Element or Attribute Information Items.

Elements and Attributes defined by this specification are referred to in the text of this document using XPath 1.0 [XPATH 1.0] expressions. Extensibility points are referred to using an extended version of this syntax:

• An element extensibility point is referred to using {any} in place of the element name. This indicates that any element name can be used, from any namespace other than the http://www.w3.org/@@@@/@@/ws-policy namespace.

• An attribute extensibility point is referred to using @{any} in place of the attribute name. This indicates that any attribute name can be used, from any namespace. namespace.

Normative text within this specification takes precedence over normative outlines, which in turn take precedence over the XML Schema [[XML Schema Structures]] descriptions.

2.2 XML Namespaces

This specification uses a number of namespace prefixes throughout; they are listed in Table 2-1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [[XML Namespaces]]).

All information items defined by this specification are identified by the XML namespace URI [[XML Namespaces]] http://www.w3.org/@@@@/@@/ws-policy. A normative XML Schema [[XML Schema Structures], [XML Schema Datatypes]] document can be obtained by dereferencing the XML namespace URI.

In this document reference is made to the wsu:Id attribute in a utility schema (http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd). The wsu:Id attribute was added to the utility schema with the intent that other specifications requiring such an Id could reference it (as is done here).

It is the intent of the W3C Web Services Policy Working Group that the Web Services Policy 1.5 - Framework and Web Services Policy 1.5 - Attachment XML namespace URI will not change arbitrarily with each subsequent revision of the corresponding XML Schema documents but rather change only when a subsequent revision, published as a WD, CR or PR draft results in non-backwardly compatible changes from a previously published WD, CR or PR draft of the specification.

Under this policy, the following are examples of backwards compatible changes that would not result in assignment of a new XML namespace URI:

• Addition of new global element, attribute, complexType and simpleType definitions.

• Addition of new elements or attributes in locations covered by a previously specified wildcard.

• Modifications to the pattern facet of a type definition for which the value-space of the previous definition remains valid or for which the value-space of the preponderance of instance would remain valid.

• Modifications to the cardinality of elements for which the value-space of possible instance documents conformant to the previous revision of the schema would still be valid with regards to the revised cardinality rule.

2.3 Terminology

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]].

We introduce the following terms that are used throughout this document:

effective policy

the effective policy, for a given policy subject, is the combination of relevant policies. The relevant policies are those attached to policy scopes that contain the policy subject.

element policy

The element policy is the policy attached to the policy subjects associated with the element information item that contains it.

merge

a merge consists of serializing each policy as a policy expression, replacing their wsp:Policy element with a wsp:All element, and placing each as children of a wrapper wsp:Policy element.

policy

A policy is a potentially empty collection of policy alternatives.

policy alternative

A policy alternative is a potentially empty collection of policy assertions.

policy assertion

A policy assertion represents an individual requirement, capability, or other property of a behavior.

policy attachment

A policy attachment is a mechanism for associating policy with one or more policy scopes.

policy expression

A policy expression is an XML Infoset representation of a policy, either in a normal form or in an equivalent compact form.

policy scope

A policy scope is a collection of policy subjects to which a policy may apply.

policy subject

A policy subject is an entity (e.g., an endpoint, message, resource, interaction) with which a policy can be associated.

2.4 Example

This specification defines several mechanisms for associating policies (Web Services Policy 1.5 - Framework, [[Web Services Policy Framework]]) with various XML Web service entities. For brevity, we define two sample policy expressions that the remainder of this document references.

The example in Example 2-1 indicates a policy for reliable messaging [[WS-RM Policy]]. The example in Example 2-2 is a policy for securing messages using X509 certificates [[WS-SecurityPolicy]].

(01) <wsp:Policy
        xmlns:rmp="http://docs.oasis-open.org/ws-rx/wsrmp/200602"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        wsu:Id="RmPolicy" >
(02)   <rmp:RMAssertion>
(03)     <rmp:InactivityTimeout Milliseconds="600000" />
(04)     <rmp:BaseRetransmissionInterval Milliseconds="3000" />
(05)     <rmp:ExponentialBackoff />
(06)     <rmp:AcknowledgementInterval Milliseconds="200" />
(07)   </rmp:RMAssertion>
(08) </wsp:Policy>

(01) <wsp:Policy
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        wsu:Id="X509EndpointPolicy" >
(02)   <sp:AsymmetricBinding>
(03)     <wsp:Policy>
(04)       <sp:RecipientToken>
(05)         <wsp:Policy>
(06)           <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
(07)             <wsp:Policy>
(08)               <sp:WssX509V3Token10 />
(09)             </wsp:Policy>
(10)           </sp:X509Token>
(11)         </wsp:Policy>
(12)       </sp:RecipientToken>
(13)       <sp:InitiatorToken>
(14)         <wsp:Policy>
(15)           <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient" >
(16)             <wsp:Policy>
(17)               <sp:WssX509V3Token10 />
(18)             </wsp:Policy>
(19)           </sp:X509Token>
(20)         </wsp:Policy>
(21)       </sp:InitiatorToken>
(22)       <sp:AlgorithmSuite>
(23)         <wsp:Policy>
(24)           <sp:Basic256Rsa15 />
(25)         </wsp:Policy>
(26)       </sp:AlgorithmSuite>
(27)       <sp:Layout>
(28)         <wsp:Policy>
(29)           <sp:Lax />
(30)         </wsp:Policy>
(31)       </sp:Layout>
(32)       <sp:IncludeTimestamp />
(33)       <sp:OnlySignEntireHeadersAndBody />
(34)     </wsp:Policy>
(35)   </sp:AsymmetricBinding>
(36) </wsp:Policy>

The document containing both of these policy expressions is assumed to be located at http://www.example.com/policies.  Per Section 3.2 Policy Identification of Web Services Policy 1.5 - Framework [[Web Services Policy Framework]], the URIs used for these policy expressions in the remainder of this document are http://www.example.com/policies#RmPolicy and http://www.example.com/policies#X509EndpointPolicy, for the examples in Example 2-1 and Example 2-2, respectively.

3.1 Effective Policy

Policies will often be associated with a particular policy subject using multiple policy attachments. For example, there may be attachments at different points in a WSDL description that apply to one policya subject, and other attachments may be made by UDDI and other mechanisms.

When multiple attachments are made, [Definition: the effective policy, for a given policy subject, is the combination of relevant policies. The relevant policies are those attached to policy scopes that contain the policy subject.]

This combination can be achieved by: [Definition: a merge consists of serializing each policy as a policy expression, replacing their wsp:Policy element with a wsp:All element, and placing each as children of a wrapper wsp:Policy element.] The resulting policy expression is considered to represent the combined policy of all of the attachments to that policy subject.

Such calculated policy expressions have no meaningful IRI of their own.

3.2 Policy Attachment Mechanisms

This section defines two general-purpose mechanisms for associating policies [[Web Services Policy Framework]] with one or more policy subjects. The first allows XML-based descriptions of resources to associate policy as part of their intrinsic definition. The second allows policies to be associated with arbitrary policy subjects independently from their definition.

3.3 XML Element Attachment

It is often desirable to associate policies with Webthe XML elements describing a subject; services policy subjects representedformats such as XMLWSDL to be easily used elements (i.e., WSDL 1.1 elementsPolicy Framework - Section 4. Attaching Policies Using WSDL 1.1 for the specific details of WSDL attachment).

Since policy assertions are stronglyThe typed by the authors, the precise semantics of how element policy is to be processed once discovered is domain-specific; however, implementations are likely to follow the precedent specified in the section below on WSDL [[WSDL 1.1]] and Policy.

This specification defines a global attribute that allows policy expressions to be attached to an arbitrary XML element. The following is the schema definition for the wsp:PolicyURIs attribute:

<xs:schema>
  <xs:attribute name="PolicyURIs">
    <xs:simpleType>
	<xs:list itemType="xs:anyURI" />
    </xs:simpleType>
  </xs:attribute>
</xs:schema>

The namespace URI [[XML Namespaces]] for this attribute is http://www.w3.org/@@@@/@@/ws-policy.

The wsp:PolicyURIs attribute contains a white space-separated list of one or more IRIs [[IETF RFC 3987]]. When this attribute is used, each of the values identifies a policy expression as defined by [[Web Services Policy Framework]]. If more than one IRI is specified, the individual referenced policies need to be merged together to form a single element policy expression. The resultant policy is then associated with the element information item's element policy property. [Definition: The element policy is the policy attached to the policy subjects associated with the element information item that contains it.]

Note that the policy scope of the attachment is specific to the policy attachment Mechanism using it; accordingly, any policy attachment mechanism using this attribute MUST define the policy scope of the attachment.

An example of element policy through the use of this global attribute is given below using the sample policies stated in Section 2.4 Example.

If the policies referenced by the following XML element

<MyElement wsp:PolicyURIs="
   http://www.example.com/policies#RmPolicy
   http://www.example.com/policies#X509EndpointPolicy" />

have been processed and merged, it would result in an element policy whose XML 1.0 representation is listed in Example 3-1:

(01) <wsp:Policy
        xmlns:rmp="http://docs.oasis-open.org/ws-rx/wsrmp/200602"
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy" >
(02)   <rmp:RMAssertion>
(03)     <rmp:InactivityTimeout Milliseconds="600000" />
(04)       <rmp:BaseRetransmissionInterval Milliseconds="3000" />
(05)       <rmp:ExponentialBackoff />
(06)       <rmp:AcknowledgementInterval Milliseconds="200" />
(07)     </rmp:RMAssertion>
(08)   <sp:AsymmetricBinding>
(09)     <wsp:Policy>
(10)       <!-- Details omitted for readability -->
(11)       <sp:IncludeTimestamp />
(12)       <sp:OnlySignEntireHeadersAndBody />
(13)     </wsp:Policy>
(14)   </sp:AsymmetricBinding>
(15) </wsp:Policy>

Note that this element policy has no meaningful IRI.

The presence of the wsp:PolicyURIs attribute does not prohibit implementations from using additional mechanisms for associating policy expressions with XML-based constructs.

Alternatively, rather than using the global attribute, XML elements may use the wsp:Policy or wsp:PolicyReference elements directly as children, in order to support element policy (Per Section 4.3.4 Policy References of Web Services Policy 1.5 -, Framework [[Web Services Policy Framework]]), and the semantics for this are the same as for the use of the global attribute. For example, an alternative way of attaching the policies in the above example, using child elements, would be as follows: 

<MyElement>
  <wsp:PolicyReference
     URI="http://www.example.com/policies#RmPolicy" />
  <wsp:PolicyReference
     URI="http://www.example.com/policies#X509EndpointPolicy" />
<MyElement/>

3.4 External Policy Attachment

This mechanism allows policies to be associated with a policy subject independent of that subject's definition and/or representation through the use of a wsp:PolicyAttachment gelement.

This element has three components: the policy scope of the attachment, the policy expressions being bound, and optional security information. The policy scope of the attachment is defined using one or more extensible domain expressions that identify policy subjects, typically using IRIs.

Domain expressions identify the domain of the association. That is, the set of policy subjects that will be considered for inclusion in the scope using an extensible domain expression model. Domain expressions identify policy subjects to be included within the policy scope. Domain expressions yield an unordered set of policy subjects for consideration.

For the purposes of attaching policy to a policy subject through this mechanism, any policy expression contained inside of the wsp:AppliesTo element MUST NOT be considered in scope. For example, an Endpoint Reference may be used as a domain expression, and it may contain policy expressions within it, but this policy expressions are not considered in scope with respect to the wsp:PolicyAttachment element using it.

The following is the pseudo-schema for the wsp:PolicyAttachment element:

<wsp:PolicyAttachment … >
  <wsp:AppliesTo>
    <x:DomainExpression/> +
  </wsp:AppliesTo>
  ( <wsp:Policy>…</wsp:Policy> |
    <wsp:PolicyReference>…</wsp:PolicyReference> ) +
  <wsse:Security>…</wsse:Security> ?
  …
</wsp:PolicyAttachment>

The following describes the attributes and elements listed in the pseudo-schema outlined above:

/wsp:PolicyAttachment

This describes an external policy attachment.

/wsp:PolicyAttachment/wsp:AppliesTo

This required element's children describe the policy scope.

/wsp:PolicyAttachment/wsp:AppliesTo/{any}

These child elements MUST specify and/or refine the domain expression(s) that define the policy scope. They MUST NOT contradict the semantics of their root element; if an element is not recognized, it SHOULD be ignored. Domain expressions are XML elements that describe policy subjects within a policy scope. When more than one domain expression is present, the policy scope contains the union of the policy subjects identified by each expression.

/wsp:PolicyAttachment/wsp:Policy

This element is a policy expression representing a policy that is attached to the policy subjects within the policy scope.

/wsp:PolicyAttachment/wsp:PolicyReference

This element references a policy expression to be attached to the policy subjects that are in the policy scope. Refer to Web Services Policy 1.5 - Framework [[Web Services Policy Framework]] for additional details.

/wsp:PolicyAttachment/wsse:Security

This optional element allows security information such as signatures to be included. The syntax of this element is described in WS-Security [[WS-Security 2004]].

/wsp:PolicyAttachment/@{any}

Additional attributes MAY be specified but MUST NOT contradict the semantics of the owner element; if an attribute is not recognized, it SHOULD be ignored.

/wsp:PolicyAttachment/{any}

Other child elements for binding constructs MAY be specified but MUST NOT contradict the semantics of the parent element; if an element is not recognized, it SHOULD be ignored.

Domain expressions are used to identify entities such as endpoints, messages or resources with which a policy can be associated. For example, domain expressions may be used to refer to WSDL 1.1 definitions, WSDL 2.0 components, endpoint references, etc.

The following example illustrates the use of this mechanism with an EndpointReference domain expression for a deployed endpoint as defined in Web Services Addressing [[WS-Addressing Core]]:

<wsp:PolicyAttachment>
  <wsp:AppliesTo>
    <wsa:EndpointReference>
      <wsa:Address>http://www.example.com/acct</wsa:Address>
    </wsa:EndpointReference>
  </wsp:AppliesTo>
  <wsp:PolicyReference
     URI="http://www.example.com/policies#RmPolicy" />
</wsp:PolicyAttachment>

In this example, the policy expression at http://www.example.com/policies#RmPolicy applies to all interactions with the endpoint at http://www.example.com/acct.

4.1 Calculating Effective Policy in WSDL 1.1

Policy attachments in WSDL 1.1 can be used to associate policies with four different types of policy subject, identified as the service policy subject, the endpoint policy subject, the operation policy subject, and the message policy subject. These policy subjects should be considered as nested, due to the hierarchical nature of WSDL.

When attaching a policy to a WSDL element, a policy scope is implied for that attachment. The policy scope only contains the policy subject associated with that element and not those associated with the children of that element. Therefore, it is RECOMMENDED that each policy assertion contained within a WSDL element's element policy should have the correct semantic such that the policy subject for that assertion is that WSDL element. For example, assertions that describe behaviours regarding the manipulation of messages should only be contained within policies attached to WSDL message elements.

Figure 1 represents how the effective policies, with regard to WSDL, are calculated for each of these policy subjects. In the diagram, the dashed boxes represent policy scopes implied by WSDL elements. For a particular policy subject, the effective policy MUST merge the element policy of each element with a policy scope that contains the policy subject.

For abstract WSDL definitions, the element policy is considered an intrinsic part of the definition and applies to all uses of that definition. In particular, it MUST be merged into the effective policy of every implementation of that abstract WSDL definition.

Policies that are attached to a deployed resource (e.g., services or ports) are only considered in the effective policy of that deployed resource itself.

Figure 4-1. Effective Policy and Policy Scopes in WSDL

(This graphic is also available in SVG format here.)

When attaching policies at different levels of the WSDL hierarchy, care must be taken. A message exchange with an endpoint MAY be described by the effective policies in all four subject types simultaneously.

For example, in Figure 4-1, for a particular input message to a deployed endpoint, there are four policy subjects involved, each with their own effective policy. There is an effective policy for the message, as well as an effective policy for the parent operation of that message, an effective policy for the deployed endpoint, and the effective policy for the service as a whole. All four effective policies are applicable in relation to that specific input message.

It is RECOMMENDED that, where specific policy assertions associated with one policy subject are only compatible with specific policy assertions on another policy subject in the same hierarchical chain, the policies containing these assertions should be attached within a single WSDL binding hierarchy.

For any given port, the policy alternatives for each policy subject type SHOULD be compatible with each of the policy alternatives at each of the policy subjects parent and child policy subjects, such that choices between policy alternatives at each level are independent of each other.

The rest of this section describes these policy subject types, and how the effective policy for each policy subject is calculated.

(01) <wsdl11:definitions name="StockQuote"
        targetNamespace="http://www.example.com/stock/binding"
        xmlns:tns="http://www.example.com/stock/binding"
        xmlns:fab="http://www.example.com/stock"
        xmlns:rmp="http://docs.oasis-open.org/ws-rx/wsrmp/200602"
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        xmlns:wsoap12="http://schemas.xmlsoap.org/wsdl/soap12/"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" >
(02)   <wsp:Policy wsu:Id="RmPolicy" >
(03)     <rmp:RMAssertion>
(04)       <rmp:InactivityTimeout Milliseconds="600000" />
(05)       <rmp:BaseRetransmissionInterval Milliseconds="3000" />
(06)       <rmp:ExponentialBackoff />
(07)       <rmp:AcknowledgementInterval Milliseconds="200" />
(08)     </rmp:RMAssertion>
(09)   </wsp:Policy>
(10)     <wsp:Policy wsu:Id="X509EndpointPolicy" >
(11)       <sp:AsymmetricBinding>
(12)         <wsp:Policy>
               <!-- Details omitted for readability -->
(13)           <sp:IncludeTimestamp />
(14)           <sp:OnlySignEntireHeadersAndBody />
(15)         </wsp:Policy>
(16)       </sp:AsymmetricBinding>
(17)     </wsp:Policy>
(18)     <wsp:Policy wsu:Id="SecureMessagePolicy" >
(19)       <sp:SignedParts>
(20)         <sp:Body />
(21)       </sp:SignedParts>
(22)       <sp:EncryptedParts>
(23)         <sp:Body />
(24)       </sp:EncryptedParts>
(25)     </wsp:Policy>
(26)     <wsdl11:import namespace="http://www.example.com/stock"
            location="http://www.example.com/stock/stock.wsdl" />
(27)     <wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
(28)       <wsoap12:binding style="document"
(29)          transport="http://schemas.xmlsoap.org/soap/http" />
(30)       <wsp:PolicyReference URI="#RmPolicy" wsdl11:required="true" />
(31)       <wsp:PolicyReference URI="#X509EndpointPolicy" wsdl11:required="true" />
(32)       <wsdl11:operation name="GetLastTradePrice" >
(33)         <wsoap12:operation soapAction="http://www.example.com/stock/Quote/GetLastTradePriceRequest" />
(34)           <wsdl11:input>
(35)             <wsoap12:body use="literal" />
(36)             <wsp:PolicyReference URI="#SecureMessagePolicy"
                                      wsdl11:required="true" />
(37)           </wsdl11:input>
(38)           <wsdl11:output>
(39)             <wsoap12:body use="literal" />
(40)             <wsp:PolicyReference URI="#SecureMessagePolicy"
(41)                                  wsdl11:required="true" />
(42)           </wsdl11:output>
(43)       </wsdl11:operation>
(44)     </wsdl11:binding>
(45) </wsdl11:definitions>

(01) <wsp:Policy
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy"
        xmlns:wsp="http://www.w3.org/@@@@/@@/ws-policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        wsu:Id="SecureMessagePolicy" >
(02)   <sp:SignedParts>
(03)     <sp:Body />
(04)   </sp:SignedParts>
(05)   <sp:EncryptedParts>
(06)     <sp:Body />
(07)   </sp:EncryptedParts>
(08) </wsp:Policy>

6.1 Calculating Effective Policy and Element Policy in UDDI

When attaching a policy to a UDDI entity a policy scope is implied for that attachment. The policy scope only contains the policy subjects associated with that entity, and not those associated with the children of that entity. This policy is the entity's element policy.

Each policy assertion contained within a UDDI entity's element policy should have the correct semantic such that the policy subject for that assertion is that UDDI entity. For example, assertions that describe behaviours regarding a service provider should only be contained within policies attached to a businessEntity structure.

For UDDI tModels that represent Web service types, the element policy is considered an intrinsic part of the tModel and applies to all uses of that tModel. In particular, it MUST be merged into the effective policy of every bindingTemplate that references that tModel.

Policies that apply to deployed Web services (bindingTemplates) are only considered in the effective policy of that deployed resource itself.

Each of these entities MAY have an element policy per Section 3. Policy Attachment. The remainder of this section defines how that element policy is interpreted to calculate the effective policy.