- From: Maryann Hondo via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 26 Oct 2007 16:28:54 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv13349
Modified Files:
ws-policy-guidelines.xml
Log Message:
This checkin addresses 3 editor actions: 379, 380, 381
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.128
retrieving revision 1.129
diff -u -d -r1.128 -r1.129
--- ws-policy-guidelines.xml 24 Oct 2007 15:55:39 -0000 1.128
+++ ws-policy-guidelines.xml 26 Oct 2007 16:28:51 -0000 1.129
@@ -110,30 +110,10 @@
specifications and the Primer. It is intended to provide
non-normative guidelines for WS-Policy Assertion Authors who
need to know the features of the language and understand the
- requirements for describing policy assertions. Some of the
- guidance for WS-Policy Assertion Authors can also be helpful
- for:
-
+ requirements for describing policy assertions. Some of the guidance
+ for WS-Policy Assertion Authors can also be helpful for those who use
+ the policy assertions created by Assertion Authors.
</p>
- <ulist>
- <item>
- <p>WS-Policy expression authors who need to understand
- the syntax of the language and understand how to build consistent
- policy expressions
- </p>
- </item>
- <item>
- <p>Consumers of policy expressions who need to understand
- the requirements contained in policy assertions
- </p>
- </item>
- <item>
- <p>Providers of policy expressions who need to understand
- how to use the assertions authored by Assertion Authors
- </p>
- </item>
-
- </ulist>
<p>This document assumes a basic understanding of XML,
Namespaces in XML, WSDL, SOAP and the Web Services Policy language.
</p>
@@ -849,6 +829,62 @@
<quote>Assertion Authors should reuse an existing assertion (rather than create a new one) whenever possible.</quote>
</p>
</div3>
+ <div3 id="order-of-behaviors">
+ <head>Order of Behaviors</head>
+ <p> A policy alternative is a collection of zero or more policy assertions.
+ Assertions within a policy alternative are not ordered.</p>
+ <p>The order of assertions in a policy alternative and order in which behaviors
+ (indicated by assertions) are applied are two distinct concepts. The order of
+ assertions in a policy alternative has no bearing on the order in which behaviors are applied.</p>
+ <p>Specifying the order in which behaviors are applied is outside the scope of the Web Services
+ Policy Framework. However, the Framework says that assertion authors can write assertions that
+ indicate the order in which behaviors are applied.</p>
+ <p>According to the SOAP processing model, the order of headers and body processing
+ (for behaviors such as addressing, security, reliability and transaction) is at the discretion
+ of the SOAP node and SOAP-based protocols may be used to control the order of processing. </p>
+ <p>The Web Services Security specification provides producers with a choice of signing a message
+ before encrypting or signing a message after encrypting. That is, WS-Security 1.1, section 8 says,
+ lines 1173-1183 - says "Finally, if a producer wishes to sign a message before encryption, then
+ following the ordering rules laid out in section 5, "Security Header", they SHOULD first prepend
+ the signature element to the <code>wsse:Security</code> header, and then prepend the encryption element, ...
+ Likewise, if a producer wishes to sign a message after encryption, they SHOULD first prepend the
+ encryption element to the <code>wsse:Security</code> header, and then prepend the signature element." </p>
+ <p>The Web Services Security Policy specification provides assertions which let users control
+ whether to sign the message before encrypting or sign it after encrypting. </p>
+ <p>In the example below, the SignBeforeEncrypting assertion requires producers to sign a message
+ before encrypting.</p>
+
+ <example> <head>Example 1</head>
+<eg xml:space="preserve"><wsp:Policy>
+ <sp:AsymmetricBinding>
+ <wsp:Policy>
+ <sp:IncludeTimestamp />
+ <sp:SignBeforeEncrypting />
+ <sp:EncryptSignature />
+ <sp:ProtectTokens />
+ <wsp:Policy/>
+ </sp:AsymmetricBinding>
+ <wsam:Addressing>...</wsam:Addressing>
+</wsp:Policy> </eg>
+</example>
+ <p>In the example below, the EncryptBeforeSigning assertion requires producers
+ to sign a message after encrypting. </p>
+
+
+ <example> <head>Example 2</head>
+<eg xml:space="preserve"><wsp:Policy>
+ <sp:AsymmetricBinding>
+ <wsp:Policy>
+ <sp:IncludeTimestamp />
+ <sp:EncryptBeforeSigning />
+ <sp:EncryptSignature />
+ <sp:ProtectTokens />
+ <wsp:Policy/>
+ </sp:AsymmetricBinding>
+ <wsam:Addressing>...</wsam:Addressing>
+</wsp:Policy> </eg>
+</example>
+ </div3>
</div2>
<div2 id="comparison">
<head>Comparison of Nested and Parameterized Assertions</head>
@@ -1106,73 +1142,78 @@
<div3>
<head>Optional behavior at runtime</head>
- <p>Since optional behaviors indicate optionality for
- both the provider and the consumer, behaviors that must
- always be engaged by a consumer must not be marked as
- "optional" with a value "true" since this would allow the
- consumer to select the policy alternative that does not contain the assertion,
- and thus not engaging the behavior.
- </p>
- <p role="practice" id="bp-limit-optional-assertions">
- <quote>Limit use of Optional Assertions</quote>
- <quote>Assertion Authors should not use optional assertions for behaviors that must be present
- in compatible policy expressions.</quote>
- </p>
- <p> The target scope of an optional assertion is an important factor for
+ <p> The target scope of an assertion is an important factor for
Assertion Authors to consider as it determines the
- <emph>granularity</emph> where the behavior is optionally
- engaged. For example, if the assertion is targeted for an
- endpoint policy subject, it is expected to govern all the
- messages that are indicated by the specific endpoint when
- optional behavior is <emph> engaged </emph>. Since the
- behavior would be applicable to policy subject that is
- designated, it is important for the Assertion Authors
- to choose the appropriate level of granularity for optional
- behaviors, to consider whether a specific message or all messages, etc. are targeted.
- </p>
- <p>
- When optional behaviors are indicated by attaching assertions with
+ <emph>granularity</emph> of the scope for which the behavior
+ is to be engaged. For example, if an assertion has a scope of
+ endpoint policy subject the behavior indicated by that assertion
+ applies to all , messages exchanged in both directions (e.g. both
+ request and response messages) with the specific endpoint to which
+ the policy alternative including that assertion is attached.
+ </p>
+ <p> Certain behaviors might provide in their specification for the
+ optional use of that behavior in the context of a subset of a
+ given interaction. When such optional behaviors are indicated by attaching assertions with
only one side of an interaction, such as an inbound message of a
- request-response, the engagement of the rest of the interaction will
+ request-response, the engagement in the context of the rest of the interaction
+ such as the outbound message, will
be undefined. Therefore, the Assertion Authors are encouraged to
- consider how the attachment on a message policy subject on a response
- message should be treated when optional behaviors are specified for
- message exchanges within a request response for response messages,
- using message policy subject. Leaving the semantics not specified or
- incompletely specified may result in providers making assumptions.
- Similarly, if engagement of a behavior is only specified for an
- outbound message, the Assertion Authors should consider describing
- the semantics if the incoming messages also utilized the behavior.
+ consider the implications of attachment of an assertion that indicates
+ such optional behavior at a message policy subject on the interaction
+ as a whole. For example, if reliable messaging (RM) is applied to a request
+ message because the policy attached to the inbound message in a request-response
+ operation had an alternative that incldued RM in its assertions, is the application
+ of RM to the outbound message permitted, even if there is no policy
+ attached to that subject? Leaving the semantics either unspecified or
+ incompletely specified may result in implementations making assumptions
+ that might have undesireable consequences.
This is especially important if the assertion is applicable to more
- than one specific policy subject. One approach that is currently taken
- by WS-RM Policy [<bibref ref="WS-RM-Policy"/>] is to
- introduce both message and endpoint policy subjects for one of its
- assertions and require the use of endpoint policy subject
- when message policy subject is used via attachment.
+ than one specific policy subject. The approach taken by
+ WS-RM Policy [<bibref ref="WS-RM-Policy"/>] is to provide for an RM
+ assertion to be attached at either or both message and endpoint policy subjects.
+ In order to eliminate the ambiguity associated with only using a message
+ policy subject, the WS-RM Policy requires a policy to be attached to an
+ endpoint policy subject as well as a message policy subject whenever a policy
+ is attached to a message policy subject.
+ The combination directly addresses
+ the unstated semantic that if RM is used for inbound messages, that it MAY
+ be used for outbound messages, even if the assertion is not attached to the
+ outbound message (and vice-versa).
</p>
<p role="practice" id="bp-entire-mep-for-optional">
- <quote>Consider entire message exchange pattern when specifying Assertions that may be optional</quote>
- <quote>Assertion Authors should associate optional assertions with the appropriate endpoint and use the smallest
- possible granularity to limit the degree to which optionality applies.</quote>
+ <quote>Consider entire message exchange pattern when specifying Assertions that represent optional behavior related
+ to a subset of that message exchange pattern when considering appropriate policy
+ subject attachment points </quote>
+ <quote>Assertion Authors should associate assertions that represent optional behavior
+ with the appropriate policy subject and use the smallest
+ possible granularity (See Best Practice 28) to limit the degree to which optional behavior applies.</quote>
</p>
<p>
- Behaviors must be engaged
- with respect to messages that are targeted to the provider
- so that the provider can determine that the optional
- behavior is engaged. In other words, the need for self
- describing messages [<specref ref="self-describing"/>] should
- not be forgotten.
- An explicit, out of band mechanism might be necessary to enable a
- client to indicate that
- the optional behavior is engaged.
- (Such an out of band mechanism is outside the scope of WS-Policy
- Framework).
+ Behaviors that must be engaged in the context of an interaction must not be marked
+ with wsp:Optional="true". since this creates two alternatives; one with and one without
+ that assertion. This would allow the policy consumer to select the policy alternative
+ that does not contain that assertion, and thus result in an interaction that did
+ not engage the required behavior that was indicated by that assertion.
+ </p>
+ <p role="practice" id="bp-limitoptional-assertion-use">
+ <quote>Limit use of an Optional Assertion</quote>
+ <quote>Assertion Authors should disallow the use of the wsp:Optional
+ attribute on assertions that represent behaviors that must be engaged.</quote>
+ </p>
+ <p>
+ Behaviors must be engaged with respect to messages that are targeted to the
+ provider so that the provider can determine that the optional behavior is engaged.
+ In ohter words, the need for self describing messages [<specref ref="self-describing"/>]should not be forgotten.
+ An explicit, out of band mechanism might be necessary to enable a client to
+ indicate that the optional behavior is engaged. (Such an out of band mechanism
+ is outside the scope of the WS-Policy Framework).
</p>
<p role="practice" id="bp-indicate-optional-assertion-use">
<quote>Indicate use of an Optional Assertion</quote>
- <quote>When a given behavior may be optional, it must be possible for both message participants to determine that the assertion is selected by both parties,
- either out of band or as reflected by the message content.</quote>
- </p>
+ <quote>When a given behavior may be optional, it must be possible for both message participants
+ to determine that the assertion has been selected by both parties,
+ either out of band or as reflected by the message content.</quote>
+ </p>
<p>
The <bibref ref="WS-Policy-Primer"/> document contains an example that outlines the
use of
@@ -1190,14 +1231,12 @@
alternate that contains the MTOM assertion is being obeyed (
<loc href="#bp-indicate-optional-assertion-use">Best Practice: Indicate use of an Optional Assertion</loc>).
</p><p>
- Note that if a MTOM assertion were only bound to an inbound message endpoint,
- then it would not be clear whether the outbound message from the provider would
- also utilize the behavior. Thus this assertion should be associated at the granularity
+ Note that if a MTOM assertion were only bound to the policy subject representing the
+ inbound message, then it would not be clear to the service provider whether the outbound
+ whether the outbound messages generated by that provider should
+ also utilize that behavior. Thus this assertion should be associated at the granularity
of an entire message exchange. The semantics of the assertion should specify this
- to avoid inappropriate assumptions by implementations. This is important for an
- optional assertion where it may not be clear whether it is to apply in a message
- exchange when optionally used in part of that exchange
- (<loc href="#bp-entire-mep-for-optional">Best Practice: Consider entire message exchange pattern when specifying Assertions that may be optional</loc>).
+ to avoid inappropriate assumptions by implementations.
</p>
</div3>
</div2>
@@ -2760,7 +2799,23 @@
<loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5186">5186</loc>. Editors' action
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/374">374</loc>.
</td>
- </tr>
+ </tr>
+ <tr>
+ <td>20071026</td>
+ <td>MH</td>
+ <td>Implemented the resolution for issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5206">5206</loc>. Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/379">379</loc>.
+ </td>
+ </tr>
+ <tr>
+ <td>20071026</td>
+ <td>MH</td>
+ <td>Implemented the resolution for issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5189">5189</loc>. Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/381">381</loc>.
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Friday, 26 October 2007 16:29:09 UTC