Securing Web Services with WS-Security: Demystifying WS-Security, WS-Policy, SAML, XML Signature, and XML Encryption

The next major feature of WS-Security to cover is using XML Encryption to hide selective information in SOAP messages. As you read in Chapter 5, "Ensuring Confidentiality of XML Messages," XML Encryption is a powerful, flexible technology for encrypting all or part of an XML document. Nearly everything discussed in Chapter 5 on XML Encryption is applicable to WS-Security, but there are few new features and considerations for weaving XML Encryption into a SOAP message.

Shared Key XML Encryption

Let's start our discussion of XML Encryption in WS-Security with a simple scenario: encrypting the body of a SOAP message using a shared (symmetric) key. In XML Encryption, you would represent this scenario by creating an EncryptedData block in the place where the clear-text element would have been. In WS-Security, in addition to the EncryptedData element, a ReferenceList in the security header will point to the parts of the message that have been encrypted. Listing 7.17 shows an example.

Listing 7.17. Use of a <ReferenceList> in the Security Header Pointing to the Parts of the Message Encrypted with XML Encryption

<S:Envelope> <S:Header> <wsse:Security> <xenc:ReferenceList> <xenc:DataReference URI="#body"/> </xenc:ReferenceList> </wsse:Security> </S:Header> <S:Body> <xenc:EncryptedData Id="body"> <xenc:CipherData> <xenc:CipherValue>...</xenc:CipherValue> </xenc:CipherData> </xenc:EncryptedData> </S:Body> </S:Envelope>

As you can see in Listing 7.17, the body of the SOAP message has been encrypted, and an EncryptedData element (with an Id of "body" ) represents the SOAP body. The new feature here is the ReferenceList within the Security element. The ReferenceList contains DataReference elements for each item encrypted, which in this case is just the SOAP body.

As we have mentioned multiple times in this book, from a key management perspective, a shared key approach can cause serious difficulties because you need to communicate (share) the key with the receiver or receivers out-of- band so that they can decrypt the message. Consequently, you will often see the shared encryption key wrapped by another key, as discussed next.

Wrapped Key XML Encryption

Shared key encryption is very fast, scalable to any size message, and, consequently, is always used for encrypting the XML text of a message. Public key encryption has beneficial key management characteristics because a public key, typically wrapped in an X.509 certificate issued by a certificate authority, can be published publicly in a registry or even in the WSDL. The recipient's public key can then be used to encrypt the shared key, and the shared key can be used to encrypt the different parts of the message itself.

Let's go over that again but in a different order. First, the message itself, or perhaps multiple individual parts of the message, are encrypted using a generated arbitrary shared key. Second, this shared key is then encrypted using the recipient's public key. Because the recipient is the holder of the solitary matching and highly protected private key, theoretically, the recipient is the only one who can decrypt the shared key and then proceed to decrypt the rest of the message.

The technique is often called key wrapping or digital enveloping because the shared key is wrapped by the recipient's public key. Although we tend to emphasize using a public key for key wrapping, it is equally possible to use a shared key to wrap a shared key.

Tip

You might use a shared key to wrap other shared keys in a "master key" scenario. In this scenario, a single master shared key can be used to encrypt multiple other shared keys used to encrypt different parts of the document. With this approach, intended recipients can read only their parts of the document, but the holder of the master key can read the entire document.

When key wrapping is involved in WS-Security, an EncryptedKey element shows up in the security header. The ReferenceList in the EncryptedKey element points to the EncryptedData elements that use the underlying encrypted key. Listing 7.18 shows an example of a wrapped key in a security header.

Listing 7.18. A Wrapped Key in a Security Header for Use in XML Encryption

<S:Envelope> <S:Header> <wsse:Security> <xenc:EncryptedKey> <xenc:EncryptionMethod Algorithm="..."/> <ds:KeyInfo> <wsse:SecurityTokenReference> <wsse:KeyIdentifier EncodingType="wsse:Base64Binary" ValueType="wsse:X509v3"> F2JfLa0GXSq... </wsse:KeyIdentifier> </wsse:SecurityTokenReference> </ds:KeyInfo> <xenc:CipherData> <xenc:CipherValue>...</xenc:CipherValue> </xenc:CipherData> <xenc:ReferenceList> <xenc:DataReference URI="#body"/> </xenc:ReferenceList> </xenc:EncryptedKey> </wsse:Security> </S:Header> <S:Body> <xenc:EncryptedData Id="body"> <xenc:CipherData> <xenc:CipherValue>...</xenc:CipherValue> </xenc:CipherData> </xenc:EncryptedData> </S:Body> </S:Envelope>

In Listing 7.18, you can see that the EncryptedKey uses a public key to encrypt a shared key, which is in turn used to encrypt the message body. The public key used to do the encryption is within a SecurityTokenReference using the embedded style in the KeyInfo block. The recipient uses this key to assist in locating the corresponding private key that will be required to decrypt the shared key that is encrypted within the CipherValue . The ReferenceList , which is used to list the EncryptedData elements that this key was used to encrypt, then points to the body of the SOAP message ( URI="body" ). This example is really no different from what was discussed in Chapter 5 except that the prescribed location of the EncryptedKey element is in the security header, not in the body.

Encrypting Attachments

We have not addressed attachments very much in this book, in large part because there is continued turmoil about how best to implement attachments, much less secure them. SOAP with Attachments (SwA) is a W3C Note and has never reached recommendation status. Microsoft has proposed an alternative based on Direct Internet Message Encapsulation (DIME). DIME ^[7] is meant to address issues that MIME has with speed and efficiency, especially for large attachments. Both of these approaches cause attachments to exist outside the XML Infoset, which makes it difficult for them to integrate well with the emerging WS-* standards. Consequently, ongoing standards work is being done to have attachments become a full-fledged member of the XML Infoset. At this point, it is unclear whether a new approach to attachments will emerge or whether the existing approaches such as SwA or DIME will become de facto standards.

^[7] See the Microsoft DIME index page at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnglobspec/html/dimeindex.asp.

SwA, which is arguably the most prevalent attachments strategy, proposes MIME as an approach for handling attachments. With SwA using MIME, the overall message is broken up into parts, in which one part is the SOAP message and the other parts of the message are attachments that contain a MIME type such as text/plain, image/gif, and so on, as diagrammed in Figure 7.3.

Obviously, when you have attachments, you may want to encrypt them along with or independent of the body of the message. To accomplish this, you use an EncryptedData element directly in the security header. This EncryptedData element will contain a ReferenceList pointing to the attachment that is encrypted. Listing 7.19 shows an example.

Listing 7.19. SOAP with Encrypted MIME Attachments

MIME-Version: 1.0 Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml; start="<soapMessage>" Content-Description: This is the optional message description. --MIME_boundary Content-Type: text/xml; charset=UTF-8 Content-Transfer-Encoding: 8bit Content-ID: <soapMessage> <?xml version='1.0' ?> <S:Envelope <S:Header> <wsse:Security> <xenc:EncryptedData MimeType="image/tiff"> <ds:KeyInfo> <wsse:SecurityTokenReference> <xenc:EncryptionMethod Algorithm="..."/> <wsse:KeyIdentifier EncodingType="wsse:Base64Binary" ValueType="wsse:X509v3"> F2JfLa0GXSq... </wsse:KeyIdentifier> </wsse:SecurityTokenReference> </ds:KeyInfo> <xenc:CipherData> <xenc:CipherReference URI="cid:image"/> </xenc:CipherData> </xenc:EncryptedData> </wsse:Security> </S:Header> <S:Body> ... </S:Body> </S:Envelope> --MIME_boundary Content-Type: image/tiff Content-Transfer-Encoding: binary Content-ID: <image> ...binary TIFF image... --MIME_boundary--

In this example, a TIFF image, which is one of the message parts, is being encrypted. The attachment itself will have a MIME type of application/octet-stream , so the MimeType on the EncryptedData element represents the original MIME type of the attachment before encryption. The CipherReference points to the attachment via the URI="cid:image" attribute.

WS-Security Encryption Summary

As you can see from the code listings, XML Encryption in WS-Security mostly just provides some extra rules about how to use XML Encryption within a SOAP message, although a few new uses are introduced with ReferenceList and EncryptedData in the security header. Notice that the main SOAP elements such as Envelope , Header , and Body are never encrypted because these elements are necessary for the SOAP infrastructure to work effectively.