Library

Understanding WS – Security Policy Language

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Nandana Mihindukulasooriya
  • 28 Jan, 2008

Introduction



WS-Security Policy language is built on top of WS–Policy framework and defines a set of policy assertions that can be used in defining individual security requirements or constraints.Those individual policy assertions can be combined using policy operators defined in the WS–Policy framework to create security policies that can be used to secure messages exchanged between a Web service and a client. WS-Policy Attachment specification defines a set of policy subjects that can be put in places where we can attach or apply security policies. For example, we can attach security policies either at service-level, operation-level or even at message-level. WS-Security Policy specification also defines how security assertions defined in the specification can be attached to policy subjects and possible policy subjects for each of those assertions.

Applies To



Apache Rampart / Java version > 1.3
Environment any

 

Table of Contents

What is a Policy Assertion ?



A policy assertion is a way of defining a requirement, constraint or a property. The WS -Security Policy Language introduces a set of security policy assertions to enable security requirements of Web services to be able to be stated in a standard, inter-operable manner. Let’s take a look at an example:

<sp:SignedParts> 
 <sp:Body/>
</sp:SignedParts>

The security assertion above defines that the body of SOAP messages must be signed. Security policy assertions like these are the building blocks that can be combined to make a complete security policy to publish satisfactory security requirements for a Web service.

What are the Main Security Policy Assertion Types ?





Security policy language defines 5 main policy assertion types. They are,

i) Security binding assertions

ii) Protection assertions

iii) Token assertions

iv) Supporting token assertions

v) Protocol assertions

Now, let’s take a look at each of these assertion types and assertions defined under each types.

Security Binding Assertions



Security binding assertions are used to define the main stream mechanism used in securing message exchanges. It also defines some important properties of those mechanisms such as the keys being used, algorithms, etc. Common properties used by other assertions are also defined in the security binding assertion. Properties defined in security binding assertion are injected to other assertions whenever necessary. There are three security binding assertions defined in the specification that are suitable for different use case scenarios.

i.) Transport binding assertion

ii.) Asymmetric binding assertion

iii.) Symmetric binding assertion



Each of the above security bindings, defines mechanisms that are suited for specific scenarios. Transport binding is suited when the message protection is provided by the transport medium. Most common scenario is using HTTPS as the message exchange transport medium. In transport binding assertion, we can define a transport token through which we can constrain messages to be exchanged only through a defined medium. WS-Security policy specification defines a HTTPS token that defines messages be transmitted over HTTPS.



Transport Binding

Asymmetric binding is suited for when both parties, i.e. client and the service, possess security tokens. For example, if both parties possess X509 certificates we use an asymmetric binding where the initiator or client will use it’s private key to sign and the recipient’s public key to encrypt. Recipient or the Web service will use it’s private key to decrypt and initiator’s public key to verify the signature. Asymmetric binding allows defining tokens used by the initiator and the recipient using Initiator Token and Recipient Token properties. These are asymmetric binding specific properties.



Asymmetric Binding



When a symmetric binding is used only one party needs to generate the security tokens. A symmetric key is established using that security token and further signing and encrypting is done using this. For example, symmetric binding can be used when only the server possesses a X509Token. Here, the initiator first creates an ephemeral key and then creates an encrypted key encrypting that ephemeral key using the recipient’s public key. This ephemeral key is then used for both signing and encrypting messages back and forth. This mechanism allows a Web service to sign and encrypt messages even with an anonymous client thus very useful at times. If a Web service wants to authenticate it’s clients, it can be done using supporting tokens. We will look at that in the latter part of this article. Symmetric binding defines three token properties namely, protection token, signature token and encryption token. If we are using the same token for signature and encryption, we can use the protection token property otherwise we can use the signature token and encryption token properties to define what type of tokens to be used.

symmetric binding



Security binding assertions also defines some properties that will be used when securing message exchanges. We will go through these properties and see what they actually mean:





Security Binding Properties

Values defined as security binding properties are used to provide additional information on the behavior on above mechanisms. Security binding property assertions populates values of these properties and default values defined in the WS-Security Policy specification, when they are not defined in a particular security policy. Following table is a list of security binding properties defined in the specification and their default values:

Property Description Default value
Algorithm Suite Defines what algorithms should be used when cryptographic operations are involved and the minimum and maximum key sizes to be used. -
Timestamp Defines whether a time stamp must be included in the security header. false
Protection order Defines the order of Signature and Encryption operations when some content needs to be both signed and encrypted. If this property is set to sign before encrypt, the signature must be computed over plain text and if this property is set to encrypt before sign then the signature must be computed over the cipher text resulted in encryption operation.

Sign before

Encrypt

Signature protection Defines whether the signature and the signature confirmation elements need to be encrypted. If this property is set to true both message signature element must be encrypted and the signature confirmation element also must be encrypted if present. false
Token protection Defines whether the signature should cover the token that is used as the key to generate the signature. In the scenarios where derived keys are used the primary token should be covered by the signature not the derived token. false
Entrire Header and Body Signature Defines whether the signature digests over the SOAP body and SOAP headers should only cover the entire body and entire header elements. false
Security Header Layout Defines the layout of the security header. Four defined values for this property are Lax, Strict, LaxTimestampFirst , LaxTimestampLast. Lax

Token Assertions



These assertions specify the types of the tokens to be used to protect messages. These assertions also define two important properties on tokens used for protecting messages.

  • Derived Keys property
  • Token Inclusion property

Derived Keys property is used to define, if derived keys should be used. If the derived keys property is set to true, tokens derived from the original token should be used to sign and encrypt messages and not the original token. However, these keys need be derived as specified in the WS–Secure Conversation specification.

Token Inclusion property is used to define, when these tokens should be included, in messages exchanged. The table below describes, four possible inclusion values:

Inclusion Value Description
/IncludeToken/Never Token should not be included in any messages. It should be externally referenced using a suitable referencing mechanism according to the policy.
/IncludeToken/Once Token must be sent only once from initiator to the recipient. Subsequent messages need not to include the token.
/IncludeToken/AlwaysToRecipient All messages sent from initiator to the recipient must carry the token. Messages from the recipient to initiator need not to carry the token.
/IncludeToken/Always All the messages should include the token. Internal reference mechanisms can be used to reference the token.

Some of the token types defined in the WS - Security Policy specification are listed below.

i)Username Tokens

ii)X509 Tokens

iii)Issued Tokens

iv)Secure Conversation Tokens

v)SAML Tokens

vi)Https Tokens

>

Supporting Token Assertions

There are four types of supporting tokens and are listed below. They are used to provide additional claims for a client. Supporting tokens also allow, additional elements to be signed and encrypted with the help of the protection assertions that are also discussed below:

  1. Supporting Tokens
  2. Signed Supporting Tokens
  3. Endorsing Supporting tokens
  4. Signed Endorsing supporting tokens



Signed supporting tokens should be signed using the primary token used to sign the message. If endorsing supporting tokens are defined in the security policy, the message signature generated by signing the elements defined in the security policy, should be signed again using the endorsing supporting tokens generating a second signature. If signed, endorsing supporting tokens are defined in the security policy, the signed endorsing supporting tokens should be signed using the primary token and the message signature should also be signed again using the signed endorsing supporting tokens. These four scenarios can be better understood looking at the table given below:

Type Sign main signature Signed by main token
Supporting tokens NO NO
Signed supporting tokens NO YES
Endorsing supporting tokens YES NO
Signed Endorsing supporting tokens YES YES

Protection Assertions



These assertions defines, which message parts are protected and how they are protected. There are mainly two types of protection token assertions, they are: Integrity Assertions and Confidentiality Assertions. Integrity assertions defines which elements of the message should be signed and confidentiality assertions defines which elements should be encrypted. Five protection assertions are:

Assertion Description
Signed Parts Assertion Defines whether body should be signed and what soap header elements should be signed
Signed Elements Assertion Defines arbitrary elements to be signed using XPath
Encrypted Parts Assertion Defines whether body should be signed and what soap header elements should be encrypted
Encrypted Elements Assertion Defines arbitrary elements to be encrypted using XPath
Required Elements Assertion Defines elements that must be present in the message

Protocol assertions



WS-Security Policy Specification defines three assertions WSS10, WSS11 and Trust10 that are used to provide SOAP message security and trust related options.These options define requirements, that an initiator and a recipient must support.

Wss10 assertion

Property Description
Direct References Defines that the initiator and the recipient must be able to process direct references
Key Identifier References Defines that the initiator and the recipient must be able to process key identifier references
Issuer Serial References Defines that the initiator and the recipient must be able to process issuer serial references
External URI References Defines that the initiator and the recipient must be able to process external URI references
Embedded Token References Defines that the initiator and the recipient must be able to process embedded token references

Wss11 assertion

Property Description
Thumbprint References Defines that the initiator and the recipient must be able to process thumbprint references
EncryptedKey References Defines that the initiator and the recipient must be able to process encrypted key references
Signature Confirmation Defines that the signature confirmation must be sent as defined in SOAP Message Security 1.1 specification
Direct References Defines that the initiator and the recipient must be able to process direct references
Key Identifier References Defines that the initiator and the recipient must be able to process key identifier references
Issuer Serial References Defines that the initiator and the recipient must be able to process issuer serial references
External URI References Defines that the initiator and the recipient must be able to process external URI references
Embedded Token References Defines that the initiator and the recipient must be able to process embedded token references

Trust10 assertion

Property Description
MustSupportClientChallenge Defines that client challenge should be supported. That is wst:SignChallenge element is supported in Request Security Token elements in Trust scenarios.
MustSupportServerChallenge Defines that server challenge should be supported.That is wst:SignChallenge element is supported in a Request Security Token Response elements.
RequireClientEntropy Defines whether client entropy is required as a key material.
RequireServerEntropy Defines whether server entropy is required as a key material.
MustSupportIssuedTokens Defines whther wst:IssuedTokens header is supported in the SOAP header.

How to Construct a Security Policy using Policy Assertions ?

WS–Policy specifications define two policy operators that can be used to construct policies using policy assertions. "wsp" is used as the prefix of the namespace defined in the WS-Policy specification.



i) wsp:All operator

ii) wsp:ExactlyOne operator

These policy operators can be used to construct policy alternatives. Policy alternatives are collections of policy assertions. These policy alternatives can be combined to construct policies which are collections of policy alternatives.  For example , we can define a policy like

<wsp:Policy>
    <wsp:ExactlyOne>
        <wsp:All>
             <sp:SecurityBindingAssertion/>
             <sp:ProtectionAssertion/>
             <cs:CustomAssertion/>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

Above policy has defined that all the 3 assertions that is <sp:SecurityBindingAssertion/>, <sp:ProtectionAssertion/> and <cs:CustomAssertion/> should be stratified and has only a single policy alternative defined in the policy. 

<wsp:Policy>
    <wsp:ExactlyOne>
        <wsp:All>
             <sp:SecurityBindingAssertion/>
             <sp:ProtectionAssertion/>
             <cs:CustomAssertion/>
        </wsp:All>
        <wsp:All>
             <sp:SomeOtherSecurityBindingAssertion/>
             <sp:SomeOtherProtectionAssertion/>
             <cs:SomeOtherCustomAssertion/>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>



Above policy has two policy alternatives, that is a Web service client can either satisfy all requirements defined by <SecurityBindingAssertion/>,<ProtectionAssertion/>, <CustomAssertion/> assertions or all the requirements defined by <SomeotherSecurityBindingAssertion/>, <SomeotherProtectionAssertion/>, <SomeotherCustomAssertion/>

 

What are Policy Subjects ?

Policy subjects are the attachment points for policies. WS Policy attachment defines various policy subjects.



     i)    Message Policy Subject

     ii)   Operation Policy Subject

     iii)  Endpoint Policy Subject



We can attach security policies to each of these policy subjects, so we have a policy that is common to the service at the end point level, and additionally define different policies for each of the operations at operation and message level. So in the message exchanges policy, it will include, all requirements defined in message-level, operation-level and end-point level. WS-Security policy specification suggests policy attachment points for the assertions defined in the specification. The table below describes, suggested policy attachment points for the assertions defined in WS-Security Policy specification.

 

Policy Subject WSDL attachment points Suggested Assertions
End point policy subject wsdl:binding

wsdl:port
Security binding

Supporting token

Protocol
Operation policy subject wsdl:binding/wsdl:operation Supporting Token
Message wsdl:binding/wsdl:operation/wsdl:input

wsdl:binding/wsdl:operation/wsdl:output

wsdl:binding/wsdl:operation/wsdl:fault
Supporting Token

Protection

 

A Sample Security Policy

<wsp:Policy wsu:Id="example"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
    <wsp:ExactlyOne>
        <wsp:All>
            <sp:SymmetricBinding>
                <wsp:Policy>
                    <sp:ProtectionToken>
                        <wsp:Policy>
                            <sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never">
                                <wsp:Policy>
                                    <sp:RequireDerivedKeys/>
                                    <sp:RequireThumbprintReference/>
                                    <sp:WssX509V3Token10/>
                                </wsp:Policy>
                            </sp:X509Token>
                        </wsp:Policy>
                    </sp:ProtectionToken>
                    <sp:AlgorithmSuite>
                        <wsp:Policy>
                            <sp:Basic256/>
                        </wsp:Policy>
                    </sp:AlgorithmSuite>
                    <sp:Layout>
                        <wsp:Policy>
                            <sp:Lax/>
                        </wsp:Policy>
                    </sp:Layout>
                    <sp:IncludeTimestamp/>
                    <sp:EncryptSignature />
                    <sp:OnlySignEntireHeadersAndBody/>
                </wsp:Policy>
            </sp:SymmetricBinding>
            <sp:SignedParts>
                <sp:Body/>
                <sp:Header Name="To" Namespace="http://schemas.xmlsoap.org/ws/2004/08/addressing"/>
            </sp:SignedParts>
            <sp:EncryptedParts>
                <sp:Body />
            </sp:EncryptedParts>
            <sp:Wss11>
                <wsp:Policy>
                    <sp:MustSupportRefKeyIdentifier/>
                    <sp:MustSupportRefIssuerSerial/>
                    <sp:MustSupportRefThumbprint/>
                    <sp:MustSupportRefEncryptedKey/>
                    <sp:RequireSignatureConfirmation/>
                </wsp:Policy>
            </sp:Wss11>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>



The above security policy states, the requirement to use, symmetric binding mechanism as we've discussed earlier in the article. It uses a X509 token as a protection token, so for both signing and encryption, this token will be used as described in symmetric binding. X509 token assertions further defines the requirements to use derived keys, and to use thumbprint reference for referencing. Algorithm suite property is set Basic256, security header layout is set to Lax and signature should be encrypted. As the security binding assertion doesn't say anything on protection order, default protection order, that is, sign before encryption exists.

According to this security policy, SOAP body should be signed and the “To” addressing header should also be signed, if available in the SOAP header. Wss11 assertion defines, the implementation support Key identifier, Issuer serial, thumbprint reference and encrypted key referencing mechanisms. It aslo defines, that recipients send signature confirmation back to the initiator and it is made compulsory.

 

Conclusion:

WS security policy specification defines a stand way to define and publish security requirements in an extensible and interoperable way. This article looks at the basic concepts of WS security policy language.

 

Reference:

 

Author

Nandana Mihindukulasooriya, Software Engineer, WSO2 Inc. nandana AT wso2 DOT com

About Author

  • Nandana Mihindukulasooriya
  • Tech Lead
  • WSO2 Inc.