Maryann Hondo, IBM Corporation
Umit Yalcinalp, SAP AG.
The Primer is a guideline for assertion authors that will work with the Web Services Policy 1.5 - Framework and Web Services Policy 1.5 - Attachment specifications to create domain specific assertions. The focus of this document is to introduce best practices and patterns for authors to follow as well as illustrate the care needed by providers and consumers in using WS-Policy to achieve the best possible results for interoperability. It is a complementary guide to using the specifications.
This document is an editors' copy that has no official standing.
2. Basic Concepts: What is an Assertion
2.1 Roles and Responsibilities in Utilizing Policy Assertions
2.1.1 Domain Owners
3. General Guidelines for Policy Expressions and Their Target Use
4. Authoring Styles
5. Guidelines for Modeling Assertions
5.1 Single Domains
5.2 New Policy Domains
5.3 Nested Assertions
5.4 Assertions with Parameters
5.5 Comparison of Nested and Parametrized Assertions
5.6 Self Describing Messages
5.7 Optional Policy Assertion
5.8 Considerations for Intersection and Merging
5.9 Typing Assertions
5.10 Naming Assertions
5.11 Subject Scoping Considerations [related to section 5]
5.12 Levels of Abstraction in WSDL
5.13 Lifecycle of Assertions
5.13.1 Referencing Policy Expressions
5.13.2 Factors in Extending Assertions within a Domain
5.13.3 Evolution of Assertions (Versioning and Compatibility)
6. Inter-domain Policy and Composition Issues
7. Applying Best Practices for Policy Attachment
7.1 Appropriate Attachment: Preserving Context-Free Policies
7.2 Appropriate Attachment: Identifying Assertion Subjects
7.2.1 Interaction between Subjects
7.3 Appropriate Attachment: Identifying Assertion Sources
8. Scenario and a worked example
A. Security Considerations
A.1 Information Disclosure Threats
A.2 Spoofing and Tampering Threats
A.3 Downgrade Threats
A.4 Repudiation Threats
A.5 Denial of Service Threats
A.6 General XML Considerations
B. XML Namespaces
D. Acknowledgements (Non-Normative)
E. Changes in this Version of the Document (Non-Normative)
F. Assertion Authors Guideline for WS-Policy Change Log (Non-Normative)
The WS-Policy specification defines a policy to be a collection of policy alternatives, where each policy alternative is a collection of policy assertions. The Primer is a resource primarily for assertion authors that provides guidelines on the use of the Web Services Policy 1.5 - Framework and Web Services Policy 1.5 - Attachment specifications to create and use assertions to enable interoperability.
WS-Policy Assertions are xml expressions that communicate the requirements and capabilities of a web service by adhering to the specification, WS-PolicyFramework. It was recognized that in order to enable interoperability of web services, different sets of WS-Policy Assertions needed to be defined by different communities based upon the requirements of the web service.
The focus of this document is to capture best practices and usage patterns for practitioners to follow as well as provide guidance to achieve the best possible result. It is a complementary guide to using the specifications and is intended to provide non-normative descriptions to supplement the specification text.
This document is intended for use by :
· WS-Policy expression authors who need to understand the syntax of the language and understand how to build consistent policy expressions,
· WS-Policy assertion authors who need to know the features of the language and understand the requirements for describing policy assertions.
· Consumers of policy expressions who need to understand the requirements contained in policy assertions
· Providers of policy expressions who need to understand how to use the assertions authored by policy assertion authors
This document assumes a basic understanding of XML 1.0, Namespaces in XML, WSDL 1.1 and SOAP.
This is a non-normative document and does not provide a definitive specification of the Web Services Policy framework. B. XML Namespaces lists all the namespaces used in this document. (XML elements without a namespace prefix are from the Web Services Policy XML Namespace.)
An assertion is a piece of metadata that describes a capability of a specific WS-Policy domain. Sets of assertions are typically defined in a dedicated specification that describe their semantics, applicability and scoping requirements as well as their data type definition using XML Schema.
There are already several examples in the industry that adhere to this practice, such as WS-ReliableMessaging [give reference] and WS-SecurityPolicy.
Some common characteristics from these documents may be considered as “best practices” for new assertion authors:
· Specify both the syntax and the semantics of the assertions
· If nested or parameterized assertions are defined, be clear about their usage
· Describe the policy subjects the assertions can be attached to.
In this document we will explain why these practices should be followed so that the assertion developers defining such a specification will be well informed and able to adequately specify assertions for their domain.
It is expected that consumers of the metadata specified by the assertion authors will also benefit from understanding these practices as it will help them utilize the assertions in the context of the WS-Policy framework. A result of following the best practices will be an assertion specification that describes a contract for the consumers and providers of the capabilities and constraints of the domain.
This document, then can also be considered a “cookbook” of techniques and guidelines for the use of the framework. You don’t have to follow the recipe, but you may not end up with the same result if you don’t.
In order for the policy framework to enable communities to express their own domain knowledge, it needed to provide basic functionality that all domains could exploit and then allow points of extension where authors of the various WS-Policy expressions for a particular domain could provide additional semantics.
Below we capture some of the characteristics of the roles and responsibilities for the authors, consumers and providers.
WS-Policy Domain owners or WS-Policy authors are defined by the WS-Policy Framework, to be a community that chooses to exploit the WS-Policy Framework by creating their own specification to define a set of assertions that express the capabilities and constraints of that target domain. The WS-Policy Framework is based on a declarative model, meaning that it is incumbent on the WS-Policy authors to define the scope of their target domain in their specification. The set of metadata will vary in the granularity of assertion specification, and it is therefore important for WS-Policy authors to clearly identify their scope (i.e, the variables of the WS-ReliableMessaging specification). It is the intent of this primer to help communities utilize the framework in such a way that multiple WS-Policy domains can co-exist and consumers and providers can utilize the framework consistenly across domains.
An example of this can be seen in the WS-SecurityPolicy specification. The WS-Security authors have defined their scope as follows:
"This document [WS-SecurityPolicy] defines a set of security policy assertions for use with the WS-Policy framework with respect to security features provided in WSS: SOAP Message Security, WS-Trust and WS-SecureConversation. This document takes the approach of defining a base set of assertions that describe how messages are to be secured. Flexibility with respect to token types, cryptographic algorithms and mechanisms used, including using transport level security is part of the design and allows for evolution over time. The intent is to provide enough information for compatibility and interoperability to be determined by web service participants along with all information necessary to actually enable a participant to engage in a secure exchange of messages."
In order to take advantage of the WS-Policy Framework, any domain author attempting to define new WS-Policy assertions must adhere to the MUST's and SHOULD's in the specifications and should review the conformance section of the specification.
WS-Policy Domain authors must also specify how to associate the assertions they have defined with the policy subjects identified by the WS-PolicyAttachment specification.
An example of how this subject mapping can be done is also provided by the WS-Security Policy specification in Appendix A.
Consumers of WS-Policy Assertions can be any entity that is capable of parsing a WS-Policy xml element, and selecting one alternative from the policy, that it then uses to govern its creation of a message to send to the subject that advertised the WS-Policy expression. The WS-Policy Attachment specification defines a set of attachment models for use with common web service subjects: WSDL definitions, UDDI directory entries, and WS-Addressing endpoints.
In the degenerative case, a human could be capable of reading the xml expression and could determine whether or not it was capable of constructing a message that the service advertised.
It is expected that consumers of WS-Policy will include a wide range of client configurations, from stand alone client applications to "active" web service requestors that are capable of adapting to the constraints and capabilities expressed in a WS-Policy document and modifying their own configurations dynamically.
Providers of WS-Policy Assertions can be any web service implementation that can reflect its on the wire message behavior as an XML expression that conforms to the WS-PolicyFramework and WS-PolicyAssertions specifications. The WS-PolicyAttachment specification has defined a set of subjects and an extensible mechanism for attaching policies to web services subjects. When a web service provider chooses to make its capabilities and constraints available, it may also need to conform to requirements of other policy specifications it utilizes ( i.e., WS-SecurityPolicy).
Also it is useful for providers to take into account how to evolve their services capabilities. If forward compatibility is a concern in order to accommodate compatibility with different and potentially new clients, providers should refer to Section XX ADD REFERENCE HERE that describes service and policy assertion evolution.
When a community of WS-Policy authors decides to define a set of WS-Policy assertions they should understand what functionality the framework provides and apply the knowledge of framework processing when defining the set of assertions. This will require the WS-Policy authors to have some definition and/or understanding of what the goal is for the use of the assertions.
Assertions can be simple or they can be complex. A set of WS-Policy authors may choose to specify one or two assertions or they may choose to specify many assertion elements that require parameters or other nested assertions. There are advantages to simplifying the set of assertions. The ultimate goal of policy assertions is to enable interoperability and assertions that define behavior for consumers and providers that can be clearly understood will most likely be consumed by a broad audience.
If a domain has a wide range of behaviors, the ability to combine individual assertions may also need to be considered.
The number of different subjects to which an assertion can be associated is also a factor when defining an assertion. It is possible that WS-Policy assertions will be consumed by a wide range of client configurations, from stand alone client applications to "active" web service requestors that are capable of adapting to constraints and capabilities modifying their own configurations dynamically. If the assertion is intended to be consumed by a broad range of clients, then the behavior should be simple for all of these clients to understand and implement.
Once the subjects are identified, one way of attaching multiple instances of a simple policy assertion is to utilize the referencing mechanism that is present in the framework. By defining the assertion once and using it in different policies (i.e.different alternatives) via reference, a policy assertion may be associated with different alternatives and subjects. A referencing mechanism is very useful in a tooling environment or when creating a domain specific attachment in multiple WSDL files, EPRS, in which the same set of policies are expected to be applied.
WS-Policy domain authors should consider the following factors when composing the set of domain assertions as it may make sense to factor out some assertions that can be used by multiple subjects:
· The definition of the assertion. Does the assertion pertain to a specific behavior that is tied to a context or does the behavior different in each possible context? For example an assertion that may have different semantics for a single message exchange or for all message exchanges that pertain to an endpoint would probably be represented by separate assertions.
· Scoping of the assertion Where does the assertion apply? Is the assertion about a specific description in WSDL? Is the assertion about a specific aspect of protocol? Is the assertion about a specific coordination between parties? Determination of the assertions subject is helpful in determining the different scopes and subjects that it applies to.
· Composition If the assertion is used with other assertions in a context, how does the assertion may or may not affect the composition? For example, if an assertion applies to the SOAP protocol, it would be necessary to consider how its presence must interact with other policy assertions that are defined for security.
We will cover these aspects in more detail with respect to the type of assertions being used in the subsequent sections.
WS-Policy supports 2 different authoring styles. A compact form is one in which an expression consists of three constructs: an attribute to decorate an assertion (to indicate whether it is required or optional), semantics for recursively nested policy operators, and a policy reference/inclusion mechanism.
An alternative style is a "normal form" in which the optional attribute is replaced by the expression of the alternatives allowed by the set of policy assertions.
Note that both authoring styles are equivalent, however there may be reasons
to choose one form over another depending on the use. For example, when
multiple alternatives are present in a policy (designated by multiple wsp
the compact form can not be used. On the other hand, the compact form is more
readable for humans when an assertion is marked as optional using the
@optional attribute as our example
When considering the creation of a new domain of policy assertions, it is important to identify whether or not the domain is self contained or can be well defined. A domain that expresses a broad set of capabilities will need to have community support to provide value to the consumers. Ultimately it is the consumers and providers that will determine whether a particular set of assertions correctly characterize the domain. A community should avoid duplicating assertions that have already been defined as this will create ambiguity not clarification and focus on creating assertions for those specific constraints and capabilities that do not overlap with other domains but that communicate new functionality.
The model is an opt-in model. Namely, the providers of services must find the set of assertions useful to improve interoperability of services or they will not include the assertions in their service descriptions.
A review by a broad community is the best way to ensure that the granularity of a set of domain assertions is appropriate.
When creating a new policy domain, it is important to understand how policy expressions are used by the framework. Some WS-Policy domains represent infrastructure efforts like WS-SecurityPolicy and WS-ReliableMessaging Policy. We also anticipate that individual web services applications and deployments may wish to reuse the WS-Policy framework in order to enable dynamic negotiation of business requirements and capabilities at runtime.
New policy authors should not try to overload assertions. A single assertion indicates a single behavior. Sets of assertions can by grouped by an operator "all". This indicates that there is a relationship between the assertions and they now constitute a policy alternative. Choices between alternatives can be indicated by an "exactly one" operator. This basic set of operators allows authors a wide range of options for expressing the possible combinations of assertions within their domain.
It requires a good deal of effort to evaluate the capabilities of a domain and capture them in a way that reflects the options of the domain if the domain has a lot of assertions to define. Interoperability testing of new policy domains is recommended to ensure that consumers and providers are able to use the new domain assertions.
Domain authors are encouraged to look at WS-SecurityPolicy [ADD REFERENCE HERE doc references] to see an example of a complex domain that has been decomposed into a set of policy expressions. New aurthors are encouraged to look at WS-ReliableMessaging Policy to see an example of a simple domain that has only defined 2 assertions.
The framework provides the ability to "nest" policy assertions. For domains with a complex set of options, nesting provides one way to indicate dependent elements within a behavior. The granularity of assertions is determined by the authors and it is recommended that care be taken when defining nested policies to ensure that the options provided appropriately specify policy alternatives within a specific behavior.
We will use the WS-SecurityPolicy to illustrate the use of nested assertions.
Securing messages is a complex usage scenario. The WS-SecurityPolicy
authors have defined the
sp:TransportBinding policy assertion
to indicate the use of transport-level security for protecting messages. Just
indicating the use of transport-level security for protecting messages is not
sufficient. To successfully interact with a Web service, the consumer must know
not only that transport-level security is required, but also what transport
token to use, what secure transport to use, what algorithm suite to use for
performing cryptographic operations, etc. The
assertion can represent these dependent behaviors.
A policy assertion – like the
sp:TransportBinding - identifies
a visible behavior that is a
requirement. A nested policy expression can be used to enumerate the dependent
behaviors on the Transport binding. A nested policy expression is a policy
expression that is a child element of another policy assertion element. A
nested policy expression further qualifies the behavior of its parent policy
In the example below, the child
element is a nested policy expression and further qualifies the behavior of the
policy assertion. The
is a nested policy assertion of the
assertion requires the use of a specific transport token and further qualifies
the behavior of the
policy assertion (which already requires the use of transport-level security
for protecting messages).
is a nested policy assertion of the
assertion requires the use of the algorithm suite identified by its nested
policy assertion (
the example above) and further qualifies the behavior of the
Setting aside the details of using transport-level security,, a policy-aware client that recognizes this policy assertion can engage transport-level security and its dependent behaviors automatically. That is, the complexity of security usage is absorbed by a policy-aware client and hidden from these Web service developers.
The framework provides an alternative approach for providing additional information for an assertion beyond its type. The framework allows WS-Policy domain authors to define name value pairs to qualify an assertion. For some domains it will be appropriate to specify these parameters instead of nesting elements.
Note that parameters of assertions include the following:
· Complex elements that have element children which can not be policy assertions.
· Elements that have attributes
An example of Assertions with Parameters is the WS-ReliableMessagingPolicy Assertions
The main consideration for selecting parameters or nesting of assertions, is that the framework intersection algorithm processes nested alternatives, but does not consider parameters in its algorithm.
Domain authors should recognize that the framework can yield multiple assertions of the same type. The QName of the assertion is the only vehicle for the framework to match a specific assertion, NOT the contents of the element. If the assertion is a parameterized assertion the authors must understand that this type of assertion will require additional processing by consumers in order to disambiguate the assertions or to understand the semantics of the name value pairs, complex content, attribute values contribution to the processing. Therefore, if the domain authors want to delegate the processing to the framework, utilizing nesting should be considered. Otherwise, domain specific comparison algorithms would need to be devised and be delegated to the specific domain handlers that are not visible to the WS-Policy framework. The tradeoff is the generality vs. the flexibility and complexity of the comparison expected for a domain.
ADD THE EARLIER EXAMPLE FROM THE AUTHORS DOCUMENT
WS-Policy is intended to communicate the requirements, capabilities, preferences and behaviors of nodes on the message's path, not specifically declare properties of the messages themselves. One of the advantages of Web services is that an XML message can be stored and later examined (e.g. as a record of a business transaction) or interpreted by an intermediary; however, if information that is necessary to understand a message is not available, these capabilities suffer.
For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed in policy that isn't attached to the message, it isn't possible to later decipher it. This is very different from expressing, in policy, what ciphers (and so forth) are supported by a particular endpoint, or those that are required in a particular message; the latter are the intended uses of the Ws-Policy framework.
The assertion authors should take into account that there are two important concepts when designing assertions. An assertion type indicates a runtime behavior. How the assertion type can be inferred or indicated from a message, if there is a need for the behavior to be represented in a persitent way by additional data or metadata that is present in a message. If such a relationship exists, it should be incorporated into an assertion design document that illustrates the disambiguation of the usage of the policy at runtime and in the message if that message is persisted.
As a result, Policy assertions should not be used to express what otherwise should be part of the message; if a property is required to understand a message, it should be communicated in the message, or made available to in a message (e.g., being referenced by a URI in the message) rather than communicated as a policy element.
Optional Policy assertions are assertions that express capabilities.
Optional assertions thus represent behaviours which
may or may not be engaged at runtime. Such behaviours
are marked by using
attribute that has a value, "true".
CHANGE THIS EXAMPLE ...
The use of something like Optimized MIME Serialization (as defined in the MTOM specification) can be an example of this type of behavior. It can be engaged either [ADD REFERENCE] for sending or receiving messages. If a provider indicates optional support for the Optimized MIME Serialization and expresses this optional behavior in a machine-readable form by utilizing an optional policy assertion,
(see the example below),
then Policy-aware clients can recognize this policy assertion and engage Optimized MIME Serialization for messages.
The semantics of this assertion may be reflected in messages on the wire: they use an optimized wire format (MIME Multipart/Related serialization). Note that in order for an optional behaviour to be engaged, the wire message that would utilize the specific assertion must be self describing.
Similar to the optional support for Optimized MIME Serialization, there are
behaviors that may be engaged (in contrast to must be engaged) for a Web
service interaction. A service provider will not fault if these behaviors are
not engaged if the policy is optional. Policy assertions can be marked optional
to represent behaviors that MAY be engaged for an interaction. A policy
assertion is marked as optional using the
wsp:Optional attribute. Optional
assertions represent the capabilities of the service provider as opposed to the
requirements of the service provider.
In the example below, the Optimized MIME Serialization policy assertion is marked optional. This policy expression allows the use of optimization and requires the use of addressing and one of transport- or message-level security.
If a provider indicates support for the Optimized MIME Serialization as a capability by using an optional policy assertion there are several aspects to consider, as the engagement of the optional behavior must be explicit on the wire.
· MIME optimization must be engaged with respect to messages that are targeted to the provider so that the provider can determine that the optional behaviour is engaged.
· It is not advisable to utilize optional assertions for outbound messages unless there is explicit, out of band mechanism that is outside the scope of WS-Policy Framework that a client is capable of using the indicated behavior ( somehow they have said that outbound optional capability may be engaged). Currently, such a mechanism is not provided by this version of the framework and may be vendor specific.
Optional assertion authors should explicitly state how the capability that is enabled by the assertion would be engaged when they are designing their assertion, whether by specific headers or etc.
Since a QName is the central mechanism for identifying a policy assertion, assertion authors should be aware of the possible evolution of their assertions and how this would impact the semantics overtime. A namespace associated with the assertion may be used to indicate a specific version of an assertion.
WS-PolicyAttachment provides a means of associating an assertion with arbitrary subjects, regardless of their nature. This flexibility can lead to ambiguity in the interpretation of policy; for example, if one attaches an assertion with the semantic "must be encrypted" to a SOAP endpoint, it's unclear what must be encrypted.
To avoid this confusion, assertion definitions should be precise about their semantics and include information that restricts their set of permissible policy subjects appropriately and indicates which Qnames are associated with which subjects. One way to do this is to generally determine if an assertion is specific to a policy attachment mechanism. An example could be identifying whether the assertion expressed is associated with behaviours (endpoints) or artifacts ( messages) and then constraining the use of an assertion to one of these subjects.
Thus our example encryption assertion would have a subject of "message", and could only be attached to messages, where the assertion is valid. However, authors need to be aware that policy attachment subjects are not limited to the subjects defined in WSDL, for example. The external attachment model in WS-PolicyAttachment allows for the definition of other domain expressions to be policy subjects .
Appendix A. Which assertions
Enabled versioning. Conservative composites.
Anti patterns. Interaction between the subjects and interaction between different attachment points. How you can get into trouble.
Granularity we need to talk about. Give wS-RX as example.
Give examples for WSDL 1.0.
Subject may be not be WSDL.
A behavior identified by a policy assertion applies to the associated policy subject. If a policy assertion is to be used with WSDL, policy assertion authors must specify a WSDL policy subject. What is the policy subject of this behavior?
· If the behavior applies to any message exchange using any of the endpoints offered by a service then the subject is the service policy subject.
· If the behavior applies to any message exchange made using an endpoint then the subject is the endpoint policy subject.
· If the behavior applies to any message exchange defined by an operation then the subject is the operation policy subject.
· If the behavior applies to an input message then the subject is the message policy subject - similarly for output and fault message policy subjects.
The authors should understand how assertions will be processed in intersection and merging and the implications of the processing when considering a specific attachment point and policy subject.
The current set of subjects as mapped to the WSDL 1.1 elements, can constrain THE assertion CONSTRUCTS TO A WSDL EXCHANGE if the authors so choose. FOR EXAMPLE, IN WS-RM, there was not a WSDL subject that was appropriate to some of the characteristics of a reliable messaging exchange and the domain authors chose to not SUPPORT certain CAPABILIties AT THE ENDPOINT LEVEL.
If the capability is not really suitable and may imply different semantics with respect to attachment points, the assertion authors should consider the following
· Decompose the semantics with several assertions
· Rewrite a single assertion targeting a specific subject.
For a given WSDL policy subject, there may be several attachment points to consider. For example, there are three attachment points for the endpoint policy subject: the port, binding and portType element. Policy assertion authors should determine the relevant attachment points, and authors should consider the impact of restricting an assertion scope to a particular attachment point. For example, an assertion should only be allowed in the portType element if the assertion reasonably applies to any endpoint that ever references that portType. Most of the known policy assertions are designed for the endpoint, operation or message policy subject because the semantics of these are more precisely understood. The commonly used attachment points for these policy subjects are outlined in XXX.
In using WSDL attachment, you will notice that the service policy subject is a collection of endpoint policy subjects. The endpoint policy subject is a collection of operation policy subjects and etc. As you can see, the WSDL policy subjects compose naturally. It is quite tempting to associate the identified behavior to a broader policy subject than to a fine granular policy subject. For instance, it is convenient to attach a supporting token assertion (defined by the Web Services Security Policy specification) to an endpoint policy subject instead of a message policy subject. For authoring convenience, an assertion author may allow the association of an assertion to multiple policy subjects. If an assertion is allowed to be associated with multiple policy subjects then the assertion author has the burden to describe the semantics of multiple instances of the same assertion attached to multiple policy subjects at the same time.
One approach is to specify a policy subject, choose the most granular policy subject that the behavior applies to and specify a preferred attachment point in WSDL.
Note that this approach only works if the policy subject is a true WSDL construct other than some other protocol concept that is layered over WSDL message exchanges. For example, the WS-RM Policy is a capability that governs a target endpoints capability to accept sequences that is beyond single message exchanges. Therefore, its semantics encompasses the cases when message level policy subjects may be used as attachment but considers when sequences are present. In addition, when the policy assertions do not target wire-level behaviours but rather abstract requirements, this technique can not be used.
There are three aspects that govern an assertions lifecycle:
· Assertion Extensibility
· Policy Language Extensibility
· Subject attachment Extensibility
If a provider has
numerous Web service offerings that provide different kinds of real-time quotes
and book information on securities such as
they may need to support multiple WSDL bindings
for these Web services. If a provider
needs to provide a consistent way to
interact with their services and to represent these capabilities and
requirements consistently without
duplicating policy expressions multiple times, a policy expression can be named
and referenced for re-use.
A policy expression may be identified by a URI and referenced for re-use as
a standalone policy or within another policy expression. There are two
mechanisms to identify a policy expression: the
Name attributes. A
PolicyReference element can be
used to reference a policy expression identified using either of these
In the example above, the
wsu:Id attribute is used to identify a policy
expression. The value of the
wsu:Id attribute is an XML ID. The relative URI
for referencing this policy expression (within the same document) is
#common. If the policy document URI is
the absolute URI for referencing this policy expression is
absolute URI is formed by combining the document URI,
# and the value of the
For re-use, a
element can be used to reference a policy expression as a standalone policy or
within another policy expression. The example below is a policy expression that
re-uses the common policy expression above.
For referencing a policy expression within the same XML document, a provider
would use the
attribute for identifying a policy expression and a URI to this ID value for referencing
this policy expression using a
The example below is a policy expression that re-uses the common policy expression within another policy expression. This policy expression requires the use of addressing, one of transport- or message-level security for protecting messages and allows the use of optimization.
Name attribute is an
alternate mechanism to identify a policy expression. The value of the
Name attribute is an absolute URI and is
independent of the location of the XML document where the identified policy
expression resides in. As such, referencing a policy expression using the
Name attribute relies on additional out
of band information. In the example below, the
Name attribute identifies the policy expression. The URI
of this policy expression is
The example below is a policy expression that re-uses the common policy expression above.
Extensibility affects the policy subjects and attachment semantics.
4.4.7. Over time, there may be multiple equivalent behaviors emerging in the Web Service interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message Security 1.0 vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C Recommendation. These equivalent behaviors are mutually exclusive for an interaction. Such equivalent behaviors can be modeled as independent assertions. The policy expression in the example below requires the use of WSS: SOAP Message Security 1.0.
The policy expression in the example below requires the use of WSS: SOAP Message Security 1.1. These are multiple equivalent behaviors and are represented using distinct policy assertions.
Best practice: use independent assertions for modeling multiple equivalent behaviors.
GET THE REST FROM DAVE and Umit
Domain authors must be aware of the interactions between different domains. For example, security assertions interact with other protocol assertions in a composition. Although modeling such assertions may appear as independent behaviours when seen only from the individual domain perspective, protocol assertions and security assertions can affect transport bindings and their interactions must be considered.
Policy attachment should not affect the interpretation of Policy alternatives. If it did, each policy assertion would need to be written with different (and possibly unknown) attachment mechanisms in mind. In particular, the timing of a policy attachment or the role that a party who attaches policy should have no bearing on the evaluation of the policy assertion [clarify subject relationship]
Each policy attachment mechanism should unambiguously identify the subject of the attached assertions. Generally, this should be a specific SOAP node or a specific message between two SOAP nodes. Some attachment mechanisms may encompass multiple notes or messages, for example, "the message along its entire path".
If the best practices are followed, and the assertions are scoped according to their subject, then multiple policy domains may be combined without conflict. Each domain should define any limitations at the policy subject level that might impact interoperability (i.e. WS-SecurityPolicy - binding abstraction to group capabilities per message exchange).
As with identifying Policy subjects, policy attachment mechanisms should make it possible to clearly identify the source of a poly assertion both for debugging and for verification. This could take several forms: it could be assumed ( in WSDL, the soufce of the assertion is the same as the WSDL provider) or it could be proven ( using WS-Trust).
To illustrate the topics explored in this document, we include an example of a web service and how a fictitous company might utilize the WS-Policy Framework to enable Web Service interoperability. In addition we provide the following matrix as a partial ????
CompanyA has determined to utilize WS-Security, WS-Addressing and WS-Reliable Messaging in all its new web service offerings and has instructed its developers to use the policy assertions defined by the following documents:
· Web Services Security Policy
· Web Services Reliable Messaging Policy
· Web Services Addressing WSDL Binding
The application developers at CompanyA are instructed to review the current web services at CompanyA and propose a plan for adding policy assertions.
The application developers collect information about web services within CompanyA and determine that all of the web services already have a WSDL 1.1 description. The developers have determined that Company A's web services fall into two types of web services. There are those that fall into the "default" category, and will use a predefined set of policy assertions, and there are those that use the default but also extend the policy alternatives.
They have also determined that for the both types, the appropriate policy subject is the endpoint. They determined this because the capabilities apply to all operations and messages for the web service not to any one individual operation or message exchange.
Service A is a WSDL 1.1 conformant web service and requires the use of transport-level security for protecting messages as well as including addressing headers. Employees of CompanyA have already incorporated wss:Security headers into their messages.
The SOAP message in the example above includes security timestamps that express creation and expiration times of this message. CompanyA requires the use of these security timestamps and transport-level security -such as HTTPS for protecting messages.
The example below illustrates a policy expression that CompanyA has created for its employees to use on their web services to indicate the use of addressing and transport-level security for securing messages.
The sp:TransportBinding element is a policy assertion.The assertion identifies the use of transport-level-security - such as HTTPS for protecting messages at the transport level. CompanyA's policy aware clients can now recognize this policy assertion and if they support it, engage in transport level security for protecting messages and providing security timestamps in SOAP envelopes for any WSDL with this policy attached.
When creating the policy for the default web services, the developers took into consideration several factors. First, all their web services were WSDL 1.1 web services. Second, they wanted to reuse policy assertions where ever possible. Third, they wanted to ensure that where possible they would support alternatives rather than forcing a single client configuration.
The developers read the WS-Policy specification and noted that there were 3 ways to express combinations of behaviors. The three policy operators, ( Policy, All and ExactlyOne) were considered and the result was the creation of two policy elements.
The first policy is shown in Figure X, CompanyA-ProfileA and it is the policy that is used by many web services at Company A that rely on https to provide transport level protection of messages.
The second policy is shown in Figure Y, CompanyA-ProfileB and it offers requestors of a service the ability to provide additional integrity protection by including WS-Security Headers to protect the message content after it is processed by the transport. The additional security processing is not required by all CompanyA web services.
In the previous section CompanyA offered a second profile that included two security options. The details of the Bindings, requires a more detailed exploration of some of the other features of the WS-Policy Framework.
When WS-Policy authors create sets of Policy assertions, like WS-Security Policy they need to consider expressing the semantics of their domain in a way that policy consumers, like Company A, can utilize them. In this case, the WS-SecurityPolicy authors factored out common elements of security mechanisms and utilized a feature of WS-Policy called "nested" assertions. In the case of an sp:TransportBinding assertion, just indicating the use of transport-level security for protecting messages is not sufficient. For a consumer of a web service provided by a company, like CompanyA, to successfully interact, the consumer must also know what transport token, what algorithm suite, etc is required. The sp:TransportBinding assertion, can (and has) represent (ed) these dependent behaviors as "nested" policy assertions.
In the example below the child Policy element is a nested policy behavior and further qualifies the behavior of the sp:TransportBinding policy assertion.
The sp:AlgorithmSuite is a nested policy assertion of the sp:TransportBinding assertion and indicates that this suite is required. The sp:TransportToken is a nested policy assertion that indicates the use of a specific type of token, in this case an HttpsToken.
You will notice that each policy has an Identifier. In the case of the default policy expression, CompanyA has decided that this policy expression should be broadly available via a URI. There are advantages and disadvantages to using each type of identifier. For URI's there is the issue of maintaining the policy expression when it may no longer be used ( CompanyA gets bought by CompanyB and starts using the policies of Company B, but some "old" consumers may still try to reference the URI).
For the second type of web services, which may be used only by certain of CompanyA's business partners, the id is an XML ID. The relative URI for referencing this within the same WSDL document is #CompanyA-ProfileB. This can be useful for company's when the policy expressions are agreed to between partners but may be changed as the business agreements change. But the disadvantage is that the policy expression must be included in each WSDL document.
Since CompanyA has decided to use well known policy expressions that are themselves part of a specification, they adhere to the guidance given in the WS-SecurityPolicy specification and attach the policies to the web service endpoint policy subject as recommended by the WS-SecurityPolicy specification. For the default web services, the URI is included in the wsdl binding for each web service.
The partner specified policy is included in the beginning of the wsdl 1.1document and referenced by the binding for the service as in the example below.
In some cases, companies may chose to implement their own assertions. When companies chose to become policy authors they need to consider not only the definition of the behavior that the assertion represents but they need to consider how new assertions will be intersected and merged with other assertions in the calculation of an effective policy and this also indicates they need to consider policy subjects.
The policy framework only defines an algorithm for calculating effective policies for WSDL 1.1 based subjects.
This appendix describes the security considerations that service providers, requestors, policy authors, policy assertion authors, and policy implementers need to consider when exposing, consuming and designing policy expressions, authoring policy assertions or implementing policy.
A policy is used to represent the capabilities and requirements of a Web Service. Policies may include sensitive information. Malicious consumers may acquire sensitive information, fingerprint the service and infer service vulnerabilities. These threats can be mitigated by requiring authentication for sensitive information, by omitting sensitive information from the policy or by securing access to the policy. For securing access to policy metadata, policy providers can use mechanisms from other Web Services specifications such as WS-Security and WS-MetadataExchange.
If a policy expression is unsigned it could be easily tampered with or replaced. To prevent tampering or spoofing of policy, requestors should discard a policy unless it is signed by the provider and presented with sufficient credentials. Requestors should also check that the signer is actually authorized to express policies for the given policy subject.
A policy may offer several alternatives that vary from weak to strong set of requirements. An adversary may interfere and remove all the alternatives except the weakest one (say no security requirements). Or, an adversary may interfere and discard this policy and insert a weaker policy previously issued by the same provider. Policy authors or providers can mitigate these threats by sun-setting older or weaker policy alternatives. Requestors can mitigate these threats by discarding policies unless they are signed by the provider.
Malicious providers may include policy assertions in its policy whose behavior cannot be verified by examining the wire message from the provider to requestor. In general, requestors have no guarantee that a provider will behave as described in the provider’s policy expression. The provider may not and perform a malicious activity. For example, say the policy assertion is privacy notice information and the provider violates the semantics by disclosing private information. Requestors can mitigate this threat by discarding policy alternatives which include assertions whose behavior cannot be verified by examining the wire message from the provider to requestor. Assertion authors can mitigate this threat by not designing assertions whose behavior cannot be verified using wire messages.
Malicious providers may provide a policy expression with a large number of alternatives, a large number of assertions in alternatives, deeply nested policy expressions or chains of PolicyReference elements that expand exponentially (see the chained sample below; this is similar to the well-known DTD entity expansion attack). Policy implementers need to anticipate these rogue providers and use a configurable bound with defaults on number of policy alternatives, number of assertions in an alternative, depth of nested policy expressions, etc.
Malicious providers may provide a policy expression that includes multiple PolicyReference elements that use a large number of different internet addresses. These may require the consumers to establish a large number of TCP connections. Policy implementers need to anticipate such rogue providers and use a configurable bound with defaults on number of PolicyReference elements per policy expression.
The table below lists XML Namespaces that are used in this document. The choice of any namespace prefix is arbitrary and not semantically significant.
Transmission Optimization Mechanism, M. Gudgin,
N. Mendelsohn, M. Nottingham and H. Ruellan, Editors. World Wide Web Consortium,
Simple Object Access Protocol (SOAP) 1.1, D. Box, et al, Editors. World Wide Web Consortium, 8 May 2000. Available at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
SOAP Version 1.2
Part 1: Messaging Framework, M. Gudgin, M.
Packaging, M. Gudgin, N. Mendelsohn, M. Nottingham and H. Ruellan,
Editors. World Wide Web Consortium,
Web Services Addressing 1.0 - Core, M. Gudgin, M. Hadley, and T. Rogers, Editors. World Wide Web Consortium, 9 May 2006. This version of the Web Services Addressing 1.0 - Core Recommendation is http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/. The latest version of Web Services Addressing 1.0 - Core is available at http://www.w3.org/TR/ws-addr-core.
Web Services Addressing 1.0 - WSDL Binding, M. Gudgin, M. Hadley, T. Rogers and Ü. Yalçinalp, Editors. World Wide Web Consortium, 29 May 2006. This version of the Web Services Addressing 1.0 - WSDL Binding is http://www.w3.org/TR/2006/CR-ws-addr-wsdl-20060529/. The latest version of Web Services Addressing 1.0 - WSDL Binding is available at http://www.w3.org/TR/ws-addr-wsdl.
Web Services Metadata Exchange (WS-MetadataExchange), K. Ballinger, et al, Authors. BEA Systems Inc., Computer Associates International, Inc., International Business Machines Corporation, Microsoft Corporation, Inc., SAP AG, Sun Microsystems, and webMethods, September 2004. Available at http://schemas.xmlsoap.org/ws/2004/09/mex/
Web Services Description Language (WSDL) 1.1, E. Christensen, et al, Authors. World Wide Web Consortium, March 2001. Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315.
Web Services Description
Language (WSDL) Version 2.0 Part 1: Core Language, R. Chinnici, J. J. Moreau, A. Ryman, S. Weerawarana,
Editors. World Wide Web Consortium,
Web Services Policy 1.5 - Framework, A. S. Vedamuthu, D. Orchard, M. Hondo, T. Boubez and P. Yendluri, Editors. World Wide Web Consortium, @@, @@@@ @@@@. This version of the specification of the Web Services Policy 1.5 - Framework specification is ws-policy-framework.html. The latest version of Web Services Policy 1.5 - Framework is available at http://www.w3.org/TR/ws-policy-framework.
Web Services Policy 1.5 - Attachment, A. S. Vedamuthu, D. Orchard, M. Hondo, T. Boubez and P. Yendluri, Editors. World Wide Web Consortium, @@, @@@@ @@@@. This version of the specification of the Web Services Policy 1.5 - Attachment specification is ws-policy-attachment.html. The latest version of Web Services Policy 1.5 - Attachment is available at http://www.w3.org/TR/ws-policy-attachment.
Web Services Security: SOAP Message Security 1.0, A. Nadalin, C. Kaler, P. Hallam-Baker and R. Monzillo, Editors. Organization for the Advancement of Structured Information Standards, March 2004. Available at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.
v1.0, A. Nadalin, M. Gudgin,
A. Barbir, and H. Granqvist,
Editors. Organization for the Advancement of Structured Information Standards,
Web Services Trust Language
This document is the work of the W3C Web Services Policy Working Group.
Members of the Working Group are (at the time of writing, and by alphabetical order): Dimitar Angelov, Abbie Barbir, Charlton Barreto, Toufic Boubez (Layer 7 Technologies), Paul Cotton (Microsoft Corporation), Jeffrey Crump, Glen Daniels, Ruchith Fernando (WSO2), Christopher Ferris, William Henry, Frederick Hirsch, Maryann Hondo, Tom Jordahl, Philippe Le Hégaret (W3C/MIT), Jong Lee (BEA Systems, Inc.), Mark Little (JBoss Inc.), Ashok Malhotra, Monica Martin, Jeff Mischkinsky, Dale Moberg, Anthony Nadalin, David Orchard (BEA Systems, Inc.), Bijan Parsia (University of Manchester), Fabian Ritzmann, Daniel Roth (Microsoft Corporation), Sanka Samaranayake (WSO2), Felix Sasaki (W3C/Keio), Seumas Soltysik, Yakov Sverdlov (Computer Associates), Asir Vedamuthu (Microsoft Corporation), Sanjiva Weerawarana (WSO2), Ümit Yalçinalp, Prasad Yendluri.
The people who have contributed to discussions on firstname.lastname@example.org are also gratefully acknowledged.
A list of substantive changes since the previous publication is below:
 WS-PolicyAttachment, w3c working draft