- From: Umit Yalsinap via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 01 Nov 2006 01:18:15 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv22794
Modified Files:
ws-policy-guidelines.xml
Log Message:
Fixes for Frederick's comments (20061025)
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- ws-policy-guidelines.xml 31 Oct 2006 04:04:10 -0000 1.7
+++ ws-policy-guidelines.xml 1 Nov 2006 01:18:13 -0000 1.8
@@ -264,7 +264,7 @@
<head>Providers</head>
<p>A provider of WS-Policy
Assertions can be any web service implementation that can
- reflect it's on the wire message behavior as an XML
+ specify its' on-the-wire message behavior as an XML
expression that conforms to the WS-PolicyFramework and
WS-Policy Attachment specifications. The
WS-PolicyAttachment specification has defined a set of
@@ -518,8 +518,53 @@
their service descriptions. </p>
<p>A review by a broad community is
the best way to ensure that the granularity of a set of domain
- assertions is appropriate. </p> </div2> <div2
- id="nested-assertions"> <head>Nested Assertions</head>
+ assertions is appropriate. </p>
+ </div2>
+ <div2 id="comparison">
+ <head>Comparison of Nested and Parameterized Assertions</head>
+ <p>There are two different ways to
+ provide additional information in an
+ assertion beyond its type. We cover
+ these two cases below followed by a
+ comparison of these approaches
+ targeting when to use either of the
+ approach. </p>
+
+ <div3 id="parameterized-assertions">
+ <head>Assertions with Parameters</head>
+ <p>The framework allows WS-Policy
+ domain authors to define name value pairs, for example, to
+ qualify an assertion. For some domains it will be appropriate
+ to specify these parameters instead of nesting assertion elements. </p>
+ <p> Note that parameters of assertions include the following:</p>
+ <ulist>
+ <item>
+ <p> Complex elements
+ with element children
+ that cannot be policy
+ assertions. </p> </item>
+ <item>
+ <p> Elements that have attributes </p>
+ </item>
+ </ulist>
+ <p>In the example below,
+ <code>sp:Body</code> and <code>sp:Header</code> elements
+ are the two assertion parameters of the
+ <code>sp:SignedParts</code> policy assertion (this
+ assertion requires the parts of a message to be
+ protected). </p>
+
+ <example> <head>Policy Assertion with Assertion Parameters</head>
+ <eg xml:space="preserve"><Policy>
+ <sp:SignedParts>
+ <sp:Body />
+ <sp:Header />
+ </sp:SignedParts>
+</Policy></eg>
+ </example>
+ </div3>
+
+ <div3 id="nested-assertions"> <head>Nested Assertions</head>
<p>The framework provides the ability
to "nest" policy assertions. For domains with a complex set of
options, nesting provides one way to indicate dependent
@@ -594,28 +639,10 @@
security usage is absorbed by a policy-aware client and hidden
from these Web service developers.
</p>
- </div2>
- <div2 id="parameterized-assertions">
- <head>Assertions with Parameters</head>
- <p>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, for example, to qualify an assertion. For some domains it
- will be appropriate to specify these parameters instead of
- nesting elements. </p>
- <p> Note that parameters of assertions include the following:</p>
- <ulist>
- <item>
- <p> Complex elements that have element children which can not be policy assertions. </p>
- </item>
- <item>
- <p> Elements that have attributes </p>
- </item>
- </ulist>
- </div2>
- <div2 id="comparison">
- <head>Comparison of Nested and Parameterized Assertions</head>
- <p>The main consideration for selecting parameters or nesting
+ </div3>
+ <div3 id="which-one-to-use">
+ <head>Considerations for choosing parameters vs nesting</head>
+ <p>The main consideration for selecting parameters or nesting
of assertions, is that <emph>the framework intersection
algorithm processes nested alternatives, but does not consider
parameters in its algorithm</emph>. </p>
@@ -636,66 +663,66 @@
to the WS-Policy framework. The tradeoff is the generality
vs. the flexibility and complexity of the comparison expected
for a domain. </p>
- <p>In the example below, <code>sp:Body</code> and <code>sp:Header</code> elements are the
- two assertion parameters of the <code>sp:SignedParts</code> policy assertion (this
- assertion requires the parts of a message to be protected). </p>
- <example> <head>Policy Assertion with Assertion Parameters</head>
- <eg xml:space="preserve"><Policy>
- <sp:SignedParts>
- <sp:Body />
- <sp:Header />
- </sp:SignedParts>
-</Policy></eg>
- </example>
-
+
+ </div3>
</div2>
<div2 id="self-describing">
<head> Self Describing Messages </head>
- <p>WS-Policy is intended to communicate the requirements,
- capabilities, preferences and behaviors of nodes that provide the message's
- path, not specifically to declare properties of the message semantics.
- 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
+ <p> WS-Policy is intended to
+ communicate the requirements, capabilities, preferences and
+ behaviors of nodes that provide the message's path, not
+ specifically to declare properties of the message semantics. 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.
</p>
- <p>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.
+ <p>Policy assertions should not be
+ used to express the semantics of a message. Rather, if a property is
+ required to understand a message, it should be communicated in
+ the message, or be made available by some other means (e.g., being
+ referenced by a URI in the message) instead of being communicated as a
+ policy element.
</p>
- <p>The assertion authors should take into account that there are
- two important concepts when designing assertions and documenting the semantics of the
- assertion types. Firstly, an
- assertion type indicates a <emph>runtime</emph> behavior. Secondly,
- an assertion should also indicate 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 persistent way or if there s a need for additional data
- or metadata that is present in a message to be persisted, it should be incorporated
- into the assertion design or in the message itself.
+ <p>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.
</p>
- <p>As a result, Policy assertions should not be used to express
- the semantics of a message. If a property is
- required to understand a message, it should be communicated in
- the message, or be made available by some other means(e.g., being
- referenced by a URI in the message) rather than communicated as a
- policy element.
+ <p>As a result, the assertion authors
+ should take into account that the following important concepts
+ when designing assertions and documenting the semantics of the
+ assertion types. Firstly, an assertion type indicates a
+ <emph>runtime</emph> behavior. Secondly, an assertion should
+ also indicate how the assertion type can be inferred or indicated
+ from a message at runtime. If there is a need for the behavior
+ to be represented in a persistent way or if there is a need for
+ additional data or metadata that is present in a message to be
+ persisted, it should be incorporated into the assertion design or
+ in the message itself. In essence, the assertion authors should
+ consider how to make messages self describing when utilizing
+ their assertions by specifying additional properties, headers,
+ etc. that must be present in a message as part of their assertion
+ design.
</p>
- <p>If the messages could not be made self describing by utilizing
- additional properties present in the message as required by the assertion, it would be
- necessary to determine the behaviors engaged at runtime by
- additional means. A general protocol that aids in determining
- such behaviors may be utilized, however a standard protocol for
- this purpose is currently not available to ensure
- interoperability. Thus, a private protocol should be used with
- care. Another alternative is to use
- of the assertion to selectively apply to subjects. For example, creating a separate endpoint to ensure
- engagement of the behavior is an option that can be
- considered as an alternate approach when messages can not be self describing.
+
+ <p>If the messages could not be made
+ self describing by utilizing additional properties present in the
+ message as required by the assertion, it would be necessary to
+ determine the behaviors engaged at runtime by additional means. A
+ general protocol that aids in determining such behaviors may be
+ utilized, however a standard protocol for this purpose is
+ currently not available to ensure interoperability. Thus, a
+ private protocol should be used with care. </p>
+ <p>Another approach is to use of the
+ assertion to selectively apply to subjects. For example, a
+ dedicated endpoint may be allocated to ensure the engagement of a
+ behavior that is expressed by a policy assertion. This approach
+ can be considered when messages can not be self describing.
</p>
</div2>
<div2 id="optional-policy-assertion">
@@ -1142,7 +1169,7 @@
<eg xml:space="preserve">
<Policy URI=http://www.CompanyA.com/WebServicesProfileA.xml>
<wsa:UsingAddressing />
- <sp:TransportBinding></spTransportBinding>
+ <sp:TransportBinding></sp:TransportBinding>
</Policy></eg>
</example>
<p>The <code>sp:TransportBinding</code> element is a policy assertion. The
@@ -1208,17 +1235,19 @@
<wsa:UsingAddressing />
<ExactlyOne>
<sp:TransportBinding>
- <sp:TransportToken>
- <Policy>
- <sp:HttpsToken RequireClienCertificate="false" />
- </Policy>
- </sp:TransportToken>
- <sp:AlgorithmSuite>
<Policy>
- <sp:Basic256Rsa15 />
+ <sp:TransportToken>
+ <Policy>
+ <sp:HttpsToken RequireClienCertificate="false" />
+ </Policy>
+ </sp:TransportToken>
+ <sp:AlgorithmSuite>
+ <Policy>
+ <sp:Basic256Rsa15 />
+ </Policy>
+ </sp:AlgorithmSuite>
</Policy>
- </spAlgorithmSuite>
- </sp:TransportBinding>
+ </sp:TransportBinding>
<sp:AsymmetricBinding>
</sp:AssymetricBinding>
</ExactlyOne>
@@ -1276,22 +1305,22 @@
<wsa:UsingAddressing />
<ExactlyOne>
<sp:TransportBinding>
- <sp:TransportToken>
+ <Policy>
+ <sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken RequireClienCertificate="false" />
- </wsp:Policy>
- </sp:TransportToken>
- <sp:AlgorithmSuite>
- <wsp:Policy>
- <sp:Basic256Rsa15 />
- </wsp:Policy>
- </spAlgorithmSuite>
- </sp:TransportBinding>
+ </wsp:Policy>
+ </sp:TransportToken>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic256Rsa15 />
+ </wsp:Policy>
+ </spAlgorithmSuite>
+ </Policy>
+ </sp:TransportBinding>
<sp:AsymmetricBinding>
-
-</sp:AssymetricBinding>
+ </sp:AssymetricBinding>
</ExactlyOne>
-
</wsp:Policy>
<wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault">
@@ -1574,11 +1603,16 @@
<td>MH</td>
<td>Editorial fixes for readability, added example for Encrypted parts</td>
</tr>
-<tr>
+ <tr>
<td>20061030</td>
<td>UY</td>
<td>Fixes for Paul Cotton's editorial comments (20061020)</td>
</tr>
+ <tr>
+ <td>20061031</td>
+ <td>UY</td>
+ <td>Fixes for Frederick's editorial comments (20061025)</td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Wednesday, 1 November 2006 01:18:33 UTC