WS-Security | Understanding Web Services Specifications and the WSE (Pro Developer)

WS-Security, published at http://msdn.microsoft.com/ws/2002/04/Security , and the WS-Security Addendum ( http://msdn.microsoft.com/ws/2002/07/Security/ ) were authored by Microsoft, IBM, and Versign. These specifications were submitted to the Organization for the Advancement of Structured Information Standards (OASIS). By the time this book is published, OASIS will have released their recommendation for WS-Security. Since the release of the WS-Security specification, it has quickly become the primary industry standard for secure Web service communication. This specification fully leverages the existing XML Signature and XML Encryption protocols and optimizes them for use in a SOAP message “based Web services environment to support the transmission of security tokens in SOAP messages as well as encryption and digital signatures. WS- Security describes the following SOAP header elements:

Security The root WS-Security element in the SOAP header
UsernameToken A child element that supports simple username and password authentication mechanisms
BinarySecurityToken A child element that supports binary-based security tokens such as Kerberos tickets and X.509 certificates
SecurityTokenReference A child element that supports referencing remote security tokens that are available at a URI
KeyInfo A child element that supports inclusion of key information (derived from XML Signature)
Signature A child element that supports signing one or more parts of a SOAP message (based on XML Signature)
ReferenceList A child element that supports referencing one or more encrypted elements in the body of a SOAP message (based on XML Encryption)
EncryptedKey An element that supports encryption specifically for keys (based on XML Encryption)
EncryptedData A child element that supports including additional encrypted data in a SOAP header (based on XML Encryption)
Timestamp The WS-Security Addendum specification that supports including timestamp information in the SOAP header that can be used to prevent replay attacks when an attacker tries to reuse an old message

Now let s look at how these elements let us build a secure SOAP message.

Security Element

Security is the root element in the SOAP header that contains all of the security information for the message targeted at a specific SOAP role (except for the EncryptedData element, which lives in the message body). In the SOAP 1.2 world, if a SOAP message is being sent along a path with multiple Web service nodes, then each node may have its own specific Security header element, where the role attribute used to define which Security header maps to which node. A WS-Security “based SOAP message might look like the following:

While this example message contains an X.509 certificate as a binary security token and has been digitally signed and encrypted, depending on the degree of protection required to access a Web service, you might implement a subset of this total security package. Also, the WS-Security header can contain multiple security tokens, and multiple, even overlapping digital signatures. In Chapter 6, I show how to use WS-Policy to tell a requesting client application which features of WS-Security must be implemented in SOAP request messages.

 <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext"> 
 <soap:Header> 
   
 <wsu:Timestamp> 
 <wsu:Created wsu:Id="Id-95df9726-68a6-4b7a-b4c6-008c3ca191d2"> 
 2003-08-01T16:36:25Z 
 </wsu:Created> 
 <wsu:Expires wsu:Id="Id-0d9a1097-f852-4419-8d2d-f1c113caccb4"> 
 2003-08-01T16:41:25Z 
 </wsu:Expires> 
 </wsu:Timestamp> 
 <wsse:Security soap:mustUnderstand="1"> 
 <wsse:BinarySecurityToken ValueType="wsse:X509v3" 
 EncodingType="wsse:Base64Binary" 
 xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility" 
 wsu:Id="SecurityToken-e518b947-5fff-4163-8f4c-15cd1c8a4a30" 
 >MIIFPzCCBwA840DANBgkqhkiG9sDtr<;$VE></wsse:BinarySecurityToken> 
 <xenc:EncryptedKey 
 Type="http://www.w3.org/2001/04/xmlenc#EncryptedKey" 
 xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"> 
 <xenc:EncryptionMethod 
 Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5" /> 
 <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"> 
 <wsse:SecurityTokenReference> 
 <wsse:KeyIdentifier ValueType="wsse:X509v3"> 
 YmlKVwXYD8vuGuYliuIYdEAQQPw= 
 </wsse:KeyIdentifier> 
 </wsse:SecurityTokenReference> 
 </KeyInfo> 
 <xenc:CipherData> 
 <xenc:CipherValue>UJ64Addf3Fd59XsaQ=</xenc:CipherValue> 
 </xenc:CipherData> 
 <xenc:ReferenceList> 
 <xenc:DataReference URI= 
 "#EncryptedContent-608eef8b-4104-4469-95b6-7cb4703cfa03" /> 
 </xenc:ReferenceList> 
 </xenc:EncryptedKey> 
 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> 
 <SignedInfo> 
 <CanonicalizationMethod 
 Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /> 
 <SignatureMethod 
 Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1" /> 
 <Reference URI="#Id-70179c5b-4975-4932-9ecd-a58feb34b0d3"> 
 <Transforms> 
 <Transform 
 Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /> 
 </Transforms> 
 <DigestMethod 
 Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /> 
 <DigestValue>y9L6igpzr7W4SiHwGxp7J92dQgw=</DigestValue> 
 </Reference> 
   
 </SignedInfo> 
 <SignatureValue>gUXCDEOJO4x/2ayBy4HNVSWh/KA=</SignatureValue> 
 <KeyInfo> 
 <wsse:SecurityTokenReference> 
 <wsse:Reference 
 URI="#SecurityToken-e518b947-5fff-4163-8f4c-15cd1c8a4a30" /> 
 </wsse:SecurityTokenReference> 
 </KeyInfo> 
 </Signature> 
 </wsse:Security> 
 </soap:Header> 
 <soap:Body xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility" 
 wsu:Id="Id-70179c5b-4975-4932-9ecd-a58feb34b0d3"> 
 <xenc:EncryptedData 
 Id="EncryptedContent-608eef8b-4104-4469-95b6-7cb4703cfa03" 
 Type="http://www.w3.org/2001/04/xmlenc#Content" 
 xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"> 
 <xenc:EncryptionMethod 
 Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc" /> 
 <xenc:CipherData> 
 <xenc:CipherValue> 
 4o1b4befwBJu6tzuaygfrAaX0UGtaYKcw2klIbuZPjLi...z8i2ypHN4+w== 
 </xenc:CipherValue> 
 </xenc:CipherData> 
 </xenc:EncryptedData> 
 </soap:Body> 
 </soap:Envelope>

The Security element is extensible so as to be able to handle additional message security features as they arise. For example, the WS-Security Profile for XML-based Tokens specification, which I will not discuss in this book, prescribes how SAML assertions and XrML licenses, which are both XML-based security tokens, can be included as child elements of the Security header. Now I will describe some of the Security header elements explicitly defined in WS- Security and its companion WS-Security Addendum specification.

UsernameToken Element

The UsernameToken element supports the most basic form of authentication provided by the WS-Security specification, namely a shared secret based on a username and a password as proof-of-possession. This element contains both a required Username element, used to specify a user s name , and an optional Password element, which can be either a plaintext password or a hashed password. Regardless, since the username itself is valuable information, as a security best practice, you should always use an encrypted transport, like SSL, with username tokens or at least encrypt the UsernameToken element. Also, you must include a Timestamp element to specify a time-to-live (TTL) of less than 5 minutes. The following example shows a sample message using the UsernameToken element to send a hashed password for user JSmith:

 <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext"> 
 <soap:Header> 
   
 <wsse:Security> 
 <wsse:UsernameToken> 
 <wsse:Username>JSmith</wsse:Username> 
 <wsse:Password Type="PasswordDigest"> 
 Wdj2mSKlr98dLswQl30CNs2aP 
 </wsse:Password> 
 </wsse:UsernameToken> 
 </wsse:Security> 
   
 </soap:Header> 
 <soap:Body> 
   
 </soap:Body> 
 </soap:Envelope>

In this example, a password hash is sent instead of the actual password text. We could have also not sent the hashed password, relying on a signature generated using the password for proof-of-possession. A SOAP message can have one or more UsernameToken elements.

BinarySecurityToken Element

The BinarySecurityToken element supports more sophisticated, and secure, authentication mechanisms, such as the use of binary Kerberos tickets or X.509 certificates for authentication rather than a simple username and password. These mechanisms include Kerberos tickets and X.509 certificates. Of course, binary tokens require special encoding when being included in an XML document, and typically they are encoded as either Base64 binary XML or hexadecimal. The encoding of binary tokens is specified by the EncodingType attribute, while the ValueType element is used to declare the type of token being carried. The supported values for ValueType are as follows :

wsse:X509v3, for X.509 v3 certificates
wsse:Kerberosv5TGT, for Kerberos v5 TGT
wsse:Kerberosv5ST, for a Kerberos service ticket (ST)

You can also use this element to pass certificate collections, such as a certificate authority hierarchy. The WS-Security Addendum specification also supports the following two additional ValueType values for collections:

wsse:PKCS7, for a PKCS#7 SignedData object
wsse:PKIPath, for an ASN.1 DER encoded certificate sequence

This list will likely be extended further to handle any new authentication systems that are developed to use binary tokens. The following example shows a sample SOAP message carrying a Kerberos TGT encoded as base64 binary:

 <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" 
 xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"> 
 <soap:Header> 
   
 <wsse:Security> 
 <wsse:BinarySecurityToken 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" 
 Id="sampleToken" 
 ValueType="wsse:Kerberosv5TGT" 
 EncodingType="wsse:Base64Binary"> 
 F8jEL0Ai28vSTe2OmQz75lP4Bs3... 
 </wsse:BinarySecurityToken> 
   
 </wsse:Security> 
   
 </soap:Header> 
 <soap:Body> 
   
 </soap:Body> 
 </soap:Envelope>

A SOAP message that implements the WS-Security specification can specify one or more BinarySecurityToken elements. Later, I will show an example of attaching a binary security token based on an X.509 certificate to a SOAP message.

SecurityTokenReference Element

The SecurityTokenReference element merely provides a mechanism for a SOAP message to reference the location of security credentials as a URI. In this case, applications that need these credentials can retrieve them from the remote location. The target URI is specified in the URI attribute of the child Reference element. Using a referenced token, the message might look something like the following:

 <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext"> 
 <soap:Header> 
   
 <wsse:Security> 
 <SecurityTokenReference> 
 <Reference 
 URI="http://example.com/tokens/sessiontoken/token1234.xml"/> 
 </SecurityTokenReference> 
   
 </wsse:Security> 
   
 </soap:Header> 
 <soap:Body> 
   
 </soap:Body> 
 </soap:Envelope>

The SecurityTokenReference element can also be used as a child element of the KeyInfo element, which is the recommended way to reference a key, rather than including the name of the key in the message.

KeyInfo Element

The KeyInfo element from the XML Signature specification is supported in WS- Security to allow you to carry encryption keys or tokens in a SOAP message; however, WS-Security recommends passing binary tokens in the BinarySecurityToken element. KeyInfo , which can contain keys, names , certificates, and other public key management information, has two child elements named KeyName and KeyValue . KeyValue contains the actual key information being transported, while KeyName identifies the key. WS-Security recommends using SecurityTokenReference for identifying keys rather than KeyName .

Signature Element

The Signature element from the XML Signature specification is supported in WS-Security to allow you to sign portions of a SOAP message. A single message can have multiple Signature elements, each referencing different, even overlapping, parts of the message. This supports cases in which various agents need to process a message, and each needs to sign the data that they have added or modified. Signatures are implemented in WS-Security in the manner described in the earlier section, XML Signature.

The following sample shows how the Signature element is used in the Security message header:

 <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" 
 xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> 
 <soap:Header> 
   
 <wsse:Security> 
 <wsse:BinarySecurityToken 
 ValueType="wsse:X509v3" 
 EncodingType="wsse:Base64Binary" 
 Id="sampleToken"> 
 MIIEZzCCA9CgAwIBAgIQEmtJZc0rqrKh5i... 
 </wsse:BinarySecurityToken> 
 <ds:Signature> 
 <ds:SignedInfo> 
 <ds:CanonicalizationMethod Algorithm= 
 "http://www.w3.org/2001/10/xml-exc-c14n#"/> 
 <ds:SignatureMethod Algorithm= 
 "http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> 
 <ds:Reference> 
 <ds:Transforms> 
 <ds:Transform Algorithm= 
 "http://www.w3.org/2001/10/xml-exc-c14n#"/> 
 </ds:Transforms> 
 <ds:DigestMethod Algorithm= 
 "http://www.w3.org/2000/09/xmldsig#sha1"/> 
 <ds:DigestValue>A1b2C3d4E5f6...</ds:DigestValue> 
 </ds:Reference> 
 </ds:SignedInfo> 
 <ds:SignatureValue> 
 BL8jdfToEb1l/vXcMZNNjPOV... 
 </ds:SignatureValue> 
 <ds:KeyInfo> 
 <wsse:SecurityTokenReference> 
 <wsse:Reference URI="#sampleToken"/> 
 </wsse:SecurityTokenReference> 
 </ds:KeyInfo> 
 </ds:Signature> 
   
 </wsse:Security> 
   
 </soap:Header> 
 <soap:Body> 
   
 </soap:Body> 
 </soap:Envelope>

In this example, the message digest is included in the DigestValue element, and the message is signed with a separate X.509 token that is referenced by the SecurityTokenReference element in KeyInfo .

ReferenceList Element

ReferenceList is an element specified by XML Encryption that s used to reference the encrypted portions of a SOAP message. WS-Security prescribes including this element within the Security message header to provide a manifest of the EncryptedData elements contained within the message.

EncryptedKey Element

The EncryptedKey element is prescribed by WS-Security for carrying an encrypted key within a SOAP message. This is used when obtaining secret cryptographic keys from a security token service, which I cover in Chapter 8, or anytime you need to safely transport such an item. This element supports < ReferenceList > as a child element in order to reference the encrypted portion of the message. < KeyInfo > can also be included as a child element to provide additional information about the key, although the < KeyIdentifier > element, rather than < KeyInfo >, is recommended. The following sample shows how the EncryptedKey element is used in a WS-Security implementation:

 <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" 
 xmlns:ds="http://www.w3.org/2000/09/xmldsig#" 
 xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"> 
 <soap:Header> 
   
 <wsse:Security> 
 <xenc:EncryptedKey> 
 <xenc:EncryptionMethod 
 Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/> 
 <ds:KeyInfo> 
 <wsse:SecurityTokenReference> 
 <wsse:KeyIdentifier> 
 F2hejk5oPDkWoV7nAqlMsQ89ijnCnd... 
 </wsse:KeyIdentifier> 
 </wsse:SecurityTokenReference> 
 </ds:KeyInfo> 
 <xenc:CipherData> 
 <xenc:CipherValue> 
 d2FpbmdvbGRfE0lm4byV0R3mA9Lped3cDS49hJ... 
 </xenc:CipherValue> 
 </xenc:CipherData> 
 <xenc:ReferenceList> 
 <xenc:DataReference URI="#encData"/> 
 </xenc:ReferenceList> 
 </xenc:EncryptedKey> 
 </wsse:Security> 
   
 </soap:Header> 
 <soap:Body> 
   
 <xenc:EncryptedData 
 Type="http://www.w3.org/2001/04/xmlenc#Element" 
 wsu:Id="encData"> 
 <xenc:EncryptionMethod 
 Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/> 
 <xenc:CipherData> 
 <xenc:CipherValue>d2FpbmdvbGRfE0lm4byV0... 
 </xenc:CipherValue> 
 </xenc:CipherData> 
 </xenc:EncryptedData> 
   
 </soap:Body> 
 </soap:Envelope>

In this example, the < EncryptedData > element is referenced by the < DataReference > element. Also, the encrypted key is identified by the < Key- Identifier > element instead of by < KeyName > because this is more secure.

EncryptedData Element

The EncryptedData element is inherited from the XML Encryption specification. WS-Security supports transporting encrypted data as attachments that are referenced in the Security message header. This element will also have the child elements < EncryptionMethod >, to specify the encryption algorithm being used, and < CipherReference >, which points to the encrypted data. When included in the Security header, the EncryptedData element must specify a MimeType attribute. The following sample shows how the EncryptedData element can be used in the Security header to reference an encrypted image file attachment:

 <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" 
 xmlns:ds="http://www.w3.org/2000/09/xmldsig#" 
 xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"> 
 <soap:Header> 
   
 <wsse:Security> 
 
 <xenc:EncryptedData MimeType="image/jpeg"> 
 <xenc:EncryptionMethod 
 Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/> 
 <ds:KeyInfo> 
 <wsse:SecurityTokenReference> 
 <wsse:KeyIdentifier> 
 F2hejk5oPDkWoV7nAqlMsQ89ijnCnd... 
 </wsse:KeyIdentifier> 
 </wsse:SecurityTokenReference> 
 </ds:KeyInfo> 
 <xenc:CipherData> 
 <xenc:CipherReference URI="cid:image"/> 
 </xenc:CipherData> 
 </xenc:EncryptedData> 
 </wsse:Security> 
   
 </soap:Header> 
 <soap:Body> 
   
 </soap:Body> 
 </soap:Envelope>

In this example, the URI in the CipherReference element must have the scheme portion of the URI equal to cid:image .

Timestamp Element

The Timestamp header element is described in the Web Services Security Addendum specification. This element provides an additional layer against attack by allowing the sender of a SOAP message to place a timestamp in the message as well as an expiration time for the message, much as there is in a Kerberos ticket. This is valuable in preventing replay attacks since the service can reject any messages with expired timestamps, and this element is required when sending hashed passwords. The expiration time is specified by the Expires element, which defaults to the xsd:dateTime type. The following is a sample message that uses the Timestamp element:

 <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext" 
 xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"> 
 <soap:Header> 
   
 <wsu:Timestamp> 
 <wsu:Created>2002-08-13T08:42:00Z</wsu:Created> 
 <wsu:Expires>2002-08-14T08:42:00Z</wsu:Expires> 
 </wsu:Timestamp> 
 <wsse:Security> 
   
 </wsse:Security> 
   
 </soap:Header> 
 <soap:Body> 
   
 </soap:Body> 
 </soap:Envelope>

In this sample, notice that although the Timestamp header element is described in the WS-Security Addendum specification, it isn t a child element of the Security header and can be used even independently of a WS- Security implementation.