WS-SecurityPolicy

WS-SecurityPolicy

Now that you have learned about WS-Policy (a general approach for creating policy assertions across any type of problem domain), WS-PolicyAssertions (a small set of policy assertions that could apply in any situation), and finally WS-PolicyAttachments (specifying how to attach a policy to a particular resource), you can now learn specifically how you can build on them to create a specific policy that relates to WS-Security. The main purpose of WS-SecurityPolicy ^[5] is to provide six policy assertions that apply directly to WS-Security. The following sections describe each of these assertions in turn .

^[5] The specification used for a resource for the WS-SecurityPolicy text is located at http://msdn.microsoft.com/ webservices /default.aspx?pull=/library/en-us/dnglobspec/html/ws-securitypolicy.asp. Note that this is an initial draft dated December 18, 2002. Consequently, some of the details are sure to change as the specification evolves. However, examining this information should be useful because it reviews most of the material on WS-Security, and something very close to this will be required to express and publish WS-SecurityPolicy.

SecurityToken

The SecurityToken assertion specifies which security tokens are required and accepted by a Web service or Web service client. This could apply to messages in ( requests ) or out (response). Listing 8.11 shows the template for a SecurityToken assertion.

Listing 8.11. The <SecurityToken> Assertion Template

 <SecurityToken wsp:Preference="..." wsp:Usage="..." >   <TokenType>...</TokenType>   <TokenIssuer>...</TokenIssuer>   <Claims>...Token type-specific claims...</Claims>   ...   (TokenType-specific details) </SecurityToken> 

The Preference and Usage elements were described in the "WS-Policy Details" section and are on all the WS-SecurityPolicy assertions. TokenType describes the type of token that is required; following is a list of the valid TokenType s: ^[6]

^[6] The valid TokenType s were defined in the December 18, 2002, WS-SecurityPolicy specification located at http://msdn.microsoft.com/webservices/default.aspx?pull=/library/en-us/dnglobspec/html/ws-securitypolicy.asp.

• wsse:X509v3 ” X.509 v3 certificate

• wsse:Kerberosv5TGT ” Kerberos v5 Ticket Granting Ticket

• wsse:Kerberosv5ST ” Kerberos v5 Service Ticket

• wsse:UsernameToken ”Username token defined in WS-Security

• wsse:SAMLAssertion ” SAML assertion

• wsse:XrMLLicence ” XrML license

TokenIssuer is the name of a trusted issuer (or names of trusted issuers ). The Claims element describes token type “specific information about a token. For example, if a particular X.509 extension is required for an X509v3 token, you describe it as a child of the Claims element. WS-Security describes claims for three token types: Username, X509v3, and Kerberos. The following sections review what the Username and X509v3 claims can specify.

Username Token Claims

A Username policy assertion with the claims specified has the options shown in Listing 8.12.

Listing 8.12. The Options for a Username Policy Assertion

 <SecurityToken wsp:Preference="..." wsp:Usage="..." wsu:id="...">   <TokenType>wsse:UsernameToken</TokenType>  <Claims>   <SubjectName MatchType="...">...</SubjectName>   <UsePassword wsp:Usage="..." Type="..."/>   </Claims>  </SecurityToken> 

The SubjectName element specifies the contents that match the contents of the Username element in a WS-Security UsernameToken . The MatchType attribute on the SubjectName describes what type of match should be done. The MatchType options are as follows :

• wsse:Exact ” The values must be exactly the same.

• wsse:Prefix (default) ” The specified value must be the prefix of the value in the certificate.

• wsse:Regexp ” The specified value is a regular expression that matches the value in the token.

The UsePassword element describes the policy related to the UserName password. The attribute Usage is the same as the WS-Policy Usage element (required, optional, and so on). The Type attribute specifies the type of password that is required. The options for password are as follows:

• wsse:PasswordText (default) ” The <Type> attribute of this <UserNameToken> is <wsse:PasswordText> (in other words, a plaintext password is used).

• wsse:PasswordDigest ” The Type attribute of this <UsernameToken> is <wsse:PasswordDigest> (in other words, a digested password is used).

X509v3 Token Claims

X.509 tokens have specific claims as well, referring to X.509 Extensions and/or the SubjectName , for example. Listing 8.13 shows a template for a SecurityToken with an X509v3 token type.

Listing 8.13. The Template for a <SecurityToken > of Type X509v3

 <SecurityToken wsp:Preference="..." wsp:Usage="..." wsu:id="...">   <TokenType>wsse:X509v3</TokenType>   <TokenIssuer>...</TokenIssuer>  <Claims>   <SubjectName MatchType="...">...</SubjectName>   <X509Extension OID="..." Critical="..." MatchType="...">   ...   </X509Extension>   </Claims>  </SecurityToken> 

If the TokenIssuer element is present, the distinguished name of the certificate issuer is either the actual issuing certificate authority, or the root certificate authority who vouches for the issuing certificate authority.

SubjectName is similar to Username in the "Username Token Claims" section and Listing 8.12. If present, the presented X.509 must have a subject name that matches based on the MatchType attribute value. The MatchType attribute values are the same as shown for Username token claims.

The X509Extension element describes the value that must be present in an X.509 token in an extension. We won't go into X.509 extensions here; suffice it to say, using such extensions is a way to add different types of descriptive data to an X.509 certificate. The value in the element must match the value of the extension based on the MatchType . The Object Identifier (OID) attribute is a string representation of the OID of the matched extension. The Critical attribute is a Boolean that, if true, indicates that the extension must be marked as critical; if false, must not be marked as critical; or if omitted, does not specify criteria for critical.

Integrity

Integrity assertions allow you to set policy that a SOAP message must be digitally signed, what specifically in the message needs to be signed, and how it is to be signed, such as what algorithms must be used. Listing 8.14 shows a template for an Integrity assertion.

Listing 8.14. The Template for the <Integrity> Assertion

 <Integrity wsp:Preference="..." wsp:Usage="...">         <Algorithm Type="..." URI="..." wsp:Preference="..."/>         <TokenInfo>             <SecurityToken>...</SecurityToken>         </TokenInfo>         <Claims>...</Claims>         <MessageParts Dialect="..." Signer="...">             ...         </MessageParts> <Integrity> 

The Preference and Usage attributes of the Integrity element are the same as those discussed previously in the "WS-Policy Details" section.

The Algorithm element allows you to specify a specific algorithm that must be used in the signature. If no algorithms are specified, only the algorithms specified in XML Signature are supported. The URI attribute points to the specific algorithm URI from the XML Signature specification (for example, http://www.w3.org/2000/09/xmldsig#dsa-sha1 ). As you read in Chapter 4, "Safeguarding the Identity and Integrity of XML Messages," numerous algorithms are possible in an XML Signature, such as canonicalization and the various signature algorithms.

The Type attribute allows you to specify the type of algorithm. Following are the possible Type values:

• wsse:AlgCanonicalization ” Canonicalization

• wsse:AlgSignature ” Signature method

• wsse:AlgTransform ” Transformation

• wsse:AlgDigest ” Digest method

Multiple algorithms with the same type can be listed along with a preference such that the other party can choose from them. Also, you can include algorithm-specific elements within the Algorithm element; for example, you could put HMACOutputLength on an HMAC signature algorithm.

The TokenInfo element allows a list of required SecurityToken formats. TokenInfo has a child element, SecurityToken , which is the same SecurityToken mentioned in the "SecurityToken" section earlier in this chapter. Consequently, you can use the attributes and children of SecurityToken to constrain specific SecurityToken s that must appear with a signature. Also, you can use the OneOrMore operator specified in WS-Policy to show that one or more of a certain SecurityToken must be present.

The Claims element is also the same as the one described in the "SecurityToken" section earlier in this chapter.

The MessageParts element enables you to describe what part of the message must be signed. You do this by providing an expression whose syntax is determined by the Dialect attribute. The default dialect is XPath 1.0. The following two dialect types are predefined in the specification:

• http://www.w3.org/TR/1999/REC-xpath-19991116

  (Default) An XPath 1.0 location path that identifies the nodes to be protected. The XPath expression is evaluated against the S:Envelope element node to select which nodes are to be protected. Additionally, the expression should use the functions defined in Appendix I of the WS-PolicyAssertions specification (where appropriate).

• http://schemas.xmlsoap.org/2002/12/wsse#part

  A list of message parts to be protected that are identified using the set of predefined functions defined in Appendix II of the WS-PolicyAssertions specification. The functions are evaluated against the S:Envelope element node.

You can have multiple MessageParts elements in list format, and the concatenated set of MessageParts must be signed unless they are separated by the Choice operator from WS-Policy. The Signer attribute allows you to designate who must sign the message. In this version of the specification, only one type of Signer is predefined, Sender (http://schemas.xmlsoap.org/2002/12/secext/originalSender ) , meaning that the originator of the message, at a minimum, must sign the message.

Listing 8.15 shows an example of an Integrity assertion.

Listing 8.15. An Example of an <Integrity> Assertion

 <wsse:Integrity wsp:Usage="wsp:Required">         <wsse:Algorithm  Type="wsse:AlgCanonicalization"          URI="http://www.w3.org/Signature/Drafts/xml-exc-c14n"/>         <wsse:Algorithm Type="wsse:AlgSignature"             URI=" http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>         <wsse:TokenInfo>             <wsse:SecurityToken>                 <wsse:TokenType>wsse:X509v3</wsse:TokenType>             </wsse:SecurityToken>         </wsse:TokenInfo>         <wsse:MessageParts          Dialect="http://schemas.xmlsoap.org/2002/12/wsse#soap">             S:Body some-URI:HeaderBlockElementName         </wsse:MessageParts> </wsse:Integrity> 

The Integrity assertion in Listing 8.15 indicates that the message must be digitally signed, exclusive canonicalization must be used, the RSAwithSHA1 signature algorithm must be used, an X.509 BinarySecurityToken must be included, and the part of the message to be signed is the SOAP body and a header called "some-URI:HeaderBlockElementName" .

Confidentiality

A Confidentiality assertion allows a sender or receiver of Web services messages to require that some specific part of a SOAP message must be encrypted. For instance, it allows the sender (or receiver) of a message to specify that parts of a message must be encrypted with a certain algorithm.

Listing 8.16 shows the template for the Confidentiality assertion.

Listing 8.16. The Template for the <Confidentiality> Assertion

 <Confidentiality wsp:Preference="..." wsp:Usage="...">         <Algorithm Type="..." URI="..." wsp:Preference="..."/>         <KeyInfo>             <SecurityToken .../>             <SecurityTokenReference .../>             ...         </KeyInfo>         <MessageParts Dialect="...">             ...         </MessageParts> </Confidentiality> 

The Confidentiality element represents a policy assertion about encryption.

The Algorithm element is the same as described for the Integrity assertion except that it has only one valid Type , wsse:AlgEncryption , to specify encryption.

The KeyInfo element is similar to the TokenInfo element described previously for the Integrity assertion. (Why it is called something different is not clear; this discrepancy will likely be remedied in a future version of the specification.) This element contains one or more (if the OneOrMore operator from WS-Policy is used) SecurityToken s. The SecurityTokenReference is a reference to a SecurityToken that must be used for the encryption.

The MessageParts element in a Confidentiality assertion is the same as the MessageParts element defined in the "Integrity" section earlier in this chapter. Listing 8.17 provides a simple example of a Confidentiality assertion.

Listing 8.17. An Example of a <Confidentiality> Assertion

 <wsse:Confidentiality wsp:Usage="wsp:Required">         <wsse:Algorithm Type="wsse:AlgEncryption"            URI="http://www.w3.org/2001/04/xmlenc#3des-cbc"/>         <MessageParts         Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">             wsp:GetInfosetForNode(wsp:GetBody(.))         </MessageParts> </wsse:Confidentiality> 

In this example, the body of the message must be encrypted using the 3DES algorithm.

Of course, you will often use digital signature and encryption together. Listing 8.18 shows Confidentiality and Integrity assertions used together.

Listing 8.18. Typical Use of <Confidentiality> and <Integrity> Assertions Together

 <wsse:Confidentiality wsp:Usage="wsp:Required">         <wsse:Algorithm Type="wsse:AlgEncryption"             URI="http://www.w3.org/2001/04/xmlenc#3des-cbc"/>         <MessageParts          Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">             wsp:GetInfosetForNode(wsp:GetBody(.))         </MessageParts> </wsse:Confidentiality> <wsse:Integrity wsp:Usage="wsp:Required">         <wsse:Algorithm  Type="wsse:AlgCanonicalization"         URI="http://www.w3.org/Signature/Drafts/xml-exc-c14n"/>         <wsse:Algorithm Type="wsse:AlgSignature"              URI=" http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>         <wsse:SecurityToken>             <wsse:TokenType>wsse:X509v3</wsse:TokenType>         </wsse:SecurityToken>         <MessageParts          Dialect="http://schemas.xmlsoap.org/2002/12/wsse#soap">             S:Body         </MessageParts> </wsse:Integrity> 

This example requires that the SOAP body be encrypted before it is signed.

Visibility

The Visibility assertion allows an intermediary to require that a certain portion of the SOAP message be visible to it. Visible means either in the clear or encrypted in a way that the intermediary is able to decrypt. Remember that a SOAP message can pass through multiple intermediaries before arriving at its final destination. An example might be a firewall, but it also could be a business waypoint such as an audit or approval processor. When you use the Visibility assertion, these intermediaries can make sure that the portion of the message they need to view will be available.

Listing 8.19 shows the template for the Visibility assertion.

Listing 8.19. The Template for the <Visibility> Assertion

 <Visibility wsp:Usage="...">         <MessageParts Dialect="...">             ...         </MessageParts>  </Visibility> 

The main element here is MessageParts , which is the same as used in Listings 8.14 and 8.16 in the Integrity and Confidentiality assertions. Listing 8.20 provides an example of a Visibility assertion.

Listing 8.20. An Example of a <Visibility> Assertion

 <wsse:Visibility wsp:Usage="wsp:Required">         <MessageParts>             wsp:GetInfosetForNode(wsp:GetBody(.))         </MessageParts>  </wsse:Visibility> 

SecurityHeader

The security header in WS-Security allows significant flexibility as to how it can show up in a SOAP header. The SecurityHeader assertion allows for constraints to be put on the security header.

Listing 8.21 shows the template for the SecurityHeader assertion.

Listing 8.21. The Template for the <SecurityHeader> Assertion

 <SecurityHeader MustPrepend="..."                 MustManifestEncryption="..."                 wsp:Usage="..."/> 

The SecurityHeader element, which is composed of three main attributes, also allows any elements to be added for extensibility purposes. The two new attributes are MustPrepend and MustManifestEncryption . If MustPrepend is true, the security header must be prepended to the message. If MustManifestEncryption is true, only the encryptions that are listed in the security header will be processed (by the WS-Security processor); all other encryptions will be ignored. This forces use of one of the encryption manifest strategies we discussed earlier in this chapter using either EncryptedData (if not using a wrapped key) or EncryptedKey .

MessageAge

As you might guess, the MessageAge assertion is related to the WS-Security Timestamp element, which has the sub-element Created , representing the date/time that the SOAP message originated. Using the MessageAge assertion, you can specify the acceptable time period before which a message will be declared "stale" and discarded.

Listing 8.22 shows the template for the MessageAge assertion.

Listing 8.22. The Template for the <MessageAge> Assertion

 <wsse:MessageAge wsp:Usage="..."       wsp:Preference="..."       Age=.../> 

In this example, Usage and Preference are the same attributes discussed in the "WS-Policy Details" section, and Age represents the maximum age timeout for the message expressed in seconds.

Listing 8.23 provides an example of the MessageAge assertion.

Listing 8.23. An Example of a <MessageAge> Assertion

 <wsse:MessageAge     wsse:Usage="wsp:Required"     Age="3600"/>