This document provides an overview of WS-Security Policy, which defines a framework for expressing security requirements for web services using policies. It discusses how WS-Security Policy builds on WS-Policy to allow endpoints to express security requirements through policy assertions. These include protection assertions to specify signed or encrypted parts, token assertions to specify required token types, and binding assertions to define how messages are secured. The document also covers how policies can be associated with WSDL definitions and how policy compatibility and intersections are defined.

1. WS – Security Policy
Prabath Siriwardena
Director, Security Architecture

2. Why we need a policy ?
• How come users get to know the security
requirements of your web service?
• Web service may need client to authenticate
• Web service may need client to sign all his requests
• Client may need some part of the response from the
service to be encrypted
• Client need the service to sign the entire response
first and then encrypts

3. WS-Policy
• General framework for endpoints to express
requirements.
• NOT just for security requirements
• Requirements are expressed in terms of a „Policy‟
• WS-Policy is a set of specifications providing a
generalized mechanism for describing policy in a
machine readable way.

4. WS-Policy & WSDL
• WSDL focuses on function descriptions
• Non-functional descriptions and QoS aspects are
covered by WS-Policy
• Web services clients do not have a WSDL, yet WSPolicy also applies to web services clients

5. WS-Policy Framework
• WS-Policy, defines a framework for describing policy
assertions.
• WS-PolicyAttachment, describes how policies are
attached to resource [e.g. WSDL]
• WS-PolicyAssertions, describes a common set of
assertions that are applicable across different
domains.

6. WS-Policy
• Basic operators
wsp:All
wsp:ExactlyOne

7. WS-Policy -Example
<wsp:Policy>
<wsp:ExactlyOne>
<wsp:All>
<A/>
<B/>
</wsp:All>
<wsp:All>
<A/>
<C/>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

8. WS-Policy
•
•
•
•
<wsp:All> and <wsp:ExactlyOne> are commutative
<wsp:All> and <wsp:ExactlyOne> are associative
<wsp:All> and <wsp:ExactlyOne> are idempotent
<wsp:All> and <wsp:ExactlyOne> are distributive

9. WS-SecurityPolicy
•
•
•
•
•
Based on WS-Policy
Various groups of policy assertions
Expressed in WSDL
Defines six policy assertions that apply to WS-Security
To express security requirements of a Web service according
to the WS-Policy spec
– What needs to be protected
– What tokens to use
– Algorithms, reference types, etc..

10. Assertion Types
•
•
•
•
•
•
Protection assertions
Required Elements Assertion
Token assertions
Security Binding assertions
Supporting token assertions
Protocol assertions

11. Protection Assertions
• Specify what needs to be protected
– Integrity Assertions
– Confidentiality Assertions

12. Protection Assertions - Integrity
SignedParts
This assertion specifies the parts of the message that
need integrity protection.
<sp:SignedParts ... >
<sp:Body />
<sp:Header Name="" Namespace=""/>
</sp:SignedParts>

13. Protection Assertions - Integrity
SignedElements
This assertion is used to specify arbitrary elements in
the message that require integrity protection.
<sp:SignedElements XPathVersion="“ >
<sp:XPath>xs:string</sp:XPath>
</sp:SignedElements>

14. Protection Assertions Confidentiality
EncryptedParts
This assertion specifies the parts of the message that
need confidentiality protection. .
<sp:EncryptedParts ... >
<sp:Body />
<sp:Header Name="" Namespace=""/>
</sp:EncryptedParts >

15. Protection Assertions Confidentiality
EncryptedElements
This assertion is used to specify arbitrary elements in
the message that require confidentiality protection.
<sp:EncryptedElements XPathVersion="“ >
<sp:XPath>xs:string</sp:XPath>
</ sp:EncryptedElements >

16. Protection Assertion Example
<sp:SignedParts xmlns:sp="http://...securitypolicy">
<sp:Body/>
<sp:Header Name="To"
Namespace="http://.../ws/2004/08/addressing"/>
<sp:Header Name="From"
Namespace="http://.../ws/2004/08/addressing"/>
</sp:SignedParts>
<sp:EncryptedParts xmlns:sp="http://...securitypolicy">
<sp:Body/>
</sp:EncryptedParts>

17. Required Elements Assertion
• This assertion is used to specify header elements
that the message MUST contain.
<sp:RequiredElements XPathVersion="”>
<sp:XPath>…</sp:XPath>
</sp:RequiredElements>

18. Token Assertions
• Token assertions specify the type of tokens to use to
protect or bind tokens and claims to the message.
– UsernameToken
– X. 509
– IssuedToken

19. Token Assertions UsernameToken
• This element represents a requirement to include a
UsernameToken
<sp:UsernameToken sp:IncludeToken=“”>
<wsp:Policy>
<sp:WssUsernameToken11 ... />
</wsp:Policy>
</sp:UsernameToken>

20. Token Assertions - IssuedToken
• This element represents a requirement for an issued
token, that is one issued by some token issuer.
<sp:IssuedToken sp:IncludeToken=“”>
<sp:Issuer>..</sp:Issuer>
<sp:RequestSecurityTokenTemplate TrustVersion="" >
</sp:RequestSecurityTokenTemplate>
<wsp:Policy> </wsp:Policy>
</sp:IssuedToken>

21. Token Assertions - IssuedToken
• This element represents a requirement for an issued
token, that is one issued by some token issuer.

22. Token Assertions – X.509
This element represents a requirement for a binary
security token carrying an X509 token.

23. Token Assertions – X.509
<sp:X509Token sp:IncludeToken="">
<wsp:Policy>
<sp:RequireKeyIdentifierReference />
<sp:RequireIssuerSerialReference />
<sp:RequireEmbeddedTokenReference />
<sp:RequireThumbprintReference />
<sp:WssX509V1Token10/>
<sp:WssX509V3Token10 />
<sp:WssX509Pkcs7Token10 />
<sp:WssX509PkiPathV1Token10/>
<sp:WssX509V1Token11/>
<sp:WssX509V3Token11/>
<sp:WssX509Pkcs7Token11/>
<sp:WssX509PkiPathV1Token11/>
</wsp:Policy>
</sp:X509Token sp:IncludeToken>

24. Token Assertions
• Token Inclusion
– Never
– Always
– AlwaysToRecipient
– Once

25. Token Assertions
• What we didn‟t cover...
– KerberosToken Assertion
– SecurityContextToken Assertion
– SecureConversationToken Assertion
– SamlToken Assertion
– HttpsToken Assertion

26. Security Bindings
• A set of properties that together provide enough information to
secure a given message exchange.
• The bindings are identified primarily by the style of protection
encryption used to protect the message exchange.
• A binding defines the following security characteristics:
• The minimum set of tokens that will be used and how they are
bound to messages
• Any necessary key transfer mechanisms
• Any required message elements (e.g. timestamps)
• The content and ordering of elements in the wsse:Security header.
Elements not specified in the binding are not allowed.
• How correlation of messages is performed securely (if
applicable to the message pattern)

27. Security Binding Assertion
•
•
•
•
•
AlgorithmSuite Assertion
Layout Assertion
TransportBinding Assertion
SymmetricBinding Assertion
AsymmetricBinding Assertion

28. AlgorithmSuite
• This assertion indicates a requirement for an
algorithm suite
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256 />
<sp:Basic192 />
<sp:Basic128/>
<sp:TripleDes/>
</wsp:Policy>
</sp:AlgorithmSuite>

29. AlgorithmSuite

30. Layout
This assertion indicates a requirement for a particular
security header layout
<sp:Layout>
<wsp:Policy>
</wsp:Policy>
</sp:Layout>

31. Layout

32. TransportBinding
• Indicates that the transport layer is used to satisfy
the security requirements
<sp:TransportBinding>
<wsp:Policy>
<sp:TransportToken>
<wsp:Policy> ... </wsp:Policy>
</sp:TransportToken>
<sp:AlgorithmSuite> ... </sp:AlgorithmSuite>
<sp:Layout> ... </sp:Layout>
<sp:IncludeTimestamp/>
</wsp:Policy>
</sp:TransportBinding>

33. TransportBinding

34. SymmetricBinding
• Indicates that the message layer is used to satisfy the
security requirements
• Defines "Encryption Token" and "Signature Token"
properties
• Where multiple messages are exchanged the tokens
perform the same functions for all messages

35. SymmetricBinding

36. AsymmetricBinding
• Indicates that the message layer is used to satisfy the security
requirements
• Defines “Initiator Token” and “Recipient Token” properties
• The Initiator Token is used for the message signature from
initiator to recipient, and encryption from recipient to
initiator.
• The Recipient Token is used for encryption from initiator to
recipient, and for the message signature from recipient to
initiator.
• Where multiple messages are exchanged the tokens perform
different functions

37. AsymmetricBinding

38. SupportingTokens
• Services may require multiple sets of claims to be
presented
• Corresponds to additional tokens in a message
• Supporting tokens are included in the security
header and may optionally include additional
message parts to sign and/or encrypt.

39. SupportingTokens

40. SupportingTokens

41. EncryptedSupportingTokens
• Encrypted supporting tokens are supporting tokens that are included in
the security header and MUST be encrypted when they appear in the
security header. Element encryption SHOULD be used for encrypting
these tokens.
• The encrypted supporting tokens can be added to any SOAP message
and do not require the “message signature” being present before the
encrypted supporting tokens are added.
• Introduced in WS-Security Policy 1.2

42. SignedSupportingTokens
• Token specified under this assertion will be signed by
the message signature.

43. SignedSupportingTokens
• If transport level security is used there won’t be any
signature in the message.

44. SignedSupportingTokens

45. SignedEncryptedSupportingTokens
• Signed, encrypted supporting tokens are Signed
supporting tokens that are also encrypted when they
appear in the wsse:Security header. Element
Encryption SHOULD be used for encrypting the
supporting tokens.
• Introduced in WS-Security Policy 1.2

46. EndorsingSupportingTokens
• Endorsing tokens sign the message signature, that is they sign the entire
ds:Signature element produced from the message signature and may
optionally include additional message parts to sign and/or encrypt.

47. EndorsingSupportingTokens
• When transport level security is used – there is no message signature
and the signature generated by the supporting token will sign the
Timestamp.

48. EndorsingSupportingTokens

49. EncryptedEndorsingSupportingTokens
• Endorsing, encrypted supporting tokens are Endorsing supporting
tokens that are also encrypted when they appear in the Security
header. Element Encryption SHOULD be used for encrypting the
supporting tokens.
• Introduced in WS-Security Policy 1.2

50. SignedEndorsingSupportingTokens
•
Signed endorsing tokens sign the entire ds:Signature element produced
from the message signature and are themselves signed by that message
signature, that is both tokens (the token used for the message signature
and the signed endorsing token) sign each other.

51. SignedEndorsingSupportingTokens
•
When transport level security level is used there will be
no message signature and the signature generated by
the supporting token will sign the Timestamp.

52. EncryptedSignedEndorsingSupportingTokens
• Signed, endorsing, encrypted supporting tokens are signed, endorsing
supporting tokens that are also encrypted when they appear in the
wsse:Security header. Element Encryption SHOULD be used for
encrypting the supporting tokens.
• Introduced in WS-Security Policy 1.2

53. WSS Assertions
• Specify supported version of WSS
– sp:Wss10
– sp:Wss11
• Specify supported token reference
mechanisms via boolean properties
• Specify Signature Confirmation requirements
for WSS 1.1

54. WSS10 Assertions

55. WSS10 Assertions

56. WSS11 Assertions

57. WSS11 Assertions

58. Trust Assertions
• Specify supported version of WS-Trust and
associated properties
– sp:Trust10
<sp:Trust10>
<wsp:Policy>
<sp:RequireClientEntropy />
<sp:RequireServerEntropy />
</wsp:Policy>
</sp:Trust10>

59. Trust Assertions

60. Associating a Policy
• Define the policy within the WSDL [ in the WSDL it
self or pointed to from the WSDL]
• Stand alone policy which points back to the web
service or services associated with it – Arbitrary
Resource Attachment

61. Associating a Policy
Arbitrary Resource Attachment
<wsp:PolicyAttachment>
<wsp:AppliesTo>
<wsp:EndpointReference>
<wsp:ServiceName Name=“”/>
<wsp:PortType Name=“”/>
<wsp:Address URI=“”/>
</wsp:EndpointReference>
</wsp:AppliesTo>
<wsp:PolicyReference Ref=“..../policy.xml/>
</wsp:PolicyAttachment>

62. Associating a Policy
Define the policy within the WSDL
- Policy can be attached to different locations in the
WSDL, which will give different meanings.
- Policy that is attached higher in the hierarchy is
inherited.
- If lower level element has a policy defined for it, the
parent‟s attached policy will be merged with the
child‟s policy.

63. The Main Structure of WSDL
<definition namespace = “http/… “>
<type> xschema types </type>
<message> … </message>
<port> a set of operations </port>
<binding> communication protocols </binding>
<service> a list of binding and ports </service>
<definition>

64. Policy Subjects
• WS-Policy Attachment defines various
attachment points for policy.
– Message Policy Subject
– Operation Policy Subject
– Endpoint Policy Subject

65. Message Policy Subject
•
•
•
•
wsdl:message
wsdl:portType/wsdl:operation/wsdl:input
wsdl:portType/wsdl:operation/wsdl:output
wsdl:portType/wsdl:operation/wsdl:fault

66. Operation Policy Subject
• wsdl:portType/wsdl:operation
• wsdl:binding/wsdl:operation

67. Endpoint Policy Subject
• wsdl:portType
• wsdl:binding
• wsdl:port

68. Associating a Policy
Define the policy within the WSDL
<wsdl>
.............
<wsp:UsingPolicy wsdl:required=“true”/>
<wsdl:message
name=“LookupResponse”
wsp:PolicyRef=“Q1” />
.............
</wsdl>

69. Associating a Policy
Define the policy within the WSDL
<Policy Name=“Q1”>
</Policy>

70. Associating a Policy
Define the policy within the WSDL
<Policy Name=“Q1”>
</Policy>

71. Normal Form
• Policy as a collection of policy alternatives
• A policy alternative as a collection of assertions
• Composed of a single <wsp:ExactlyOne> operator
containing one or more <wsp:All> operators.

72. Normal Form

73. Nested Assertions
• Nested assertions describe requirements and
alternatives for the enclosing assertion elements.

74. Nested Policy Normalization
• If an assertion in a normal form contains a nested
policy, it can at most contain ONE policy alternative.

75. Nested Policy Normalization

76. Nested Policy Normalization

77. Compatibility
• Two assertions are compatible if the QName value of
one assertion matches with a Qname value of the
other assertion.
• Two policies are compatible if an alternative in one is
compatible with an alternative in the other. If two
policies are compatible, their intersection is the set
of the intersections between all pairs of compatible
alternatives, choosing one alternative from each
policy. If two policies are not compatible, their
intersection has no policy alternatives.

78. Policy Intersection
• Useful when two or more parties express policy and
want to limit the policy alternatives to those that are
mutually compatible.
• Intersection takes two policies and returns a policy.
• There are two modes for intersection: strict and lax.
How the mode is selected or indicated for the policy
intersection is outside the scope of this specification.

79. Policy Intersection
•
•
If the mode is strict, two policy alternatives A and B are
compatible:
• if each assertion in A is compatible with an assertion in
B, and
• if each assertion in B is compatible with an assertion in A.
If the mode is lax, two policy alternatives A and B are
compatible:
• if each assertion in A that is not an ignorable policy
assertion is compatible with an assertion in B, and
• if each assertion in B that is not an ignorable policy
assertion is compatible with an assertion in A.

83. lean . enterprise . middleware