Web Services Security, Part 2
by Bilal Siddiqui | Pages: 1, 2, 3

XML Encryption

The XML Encryption specification satisfies confidentiality requirements in XML messages. XML encryption offers several features.

• You can encrypt a complete XML file.
• You can encrypt any single element of an XML file.
• You can encrypt only the contents of an XML element.
• You can encrypt non-XML data (e.g. a JPG image).
• You can encrypt an already encrypted element (i.e., "super-encryption").

Encrypting a Complete XML File

We'll start with encrypting a complete XML file. Have a look at Listing 6, where we have shown an XML encrypted file. We have not shown the XML document that we encrypted to arrive at Listing 6 because it doesn't matter. Encrypting any XML file will produce the same XML structure, except the encrypted value wrapped inside the CipherValue element in Listing 6.

The root EncryptedData element in Listing 6 holds the encrypted data along with relevant information such as the algorithm used for encryption. The EncryptedData element contains the XML Encryption namespace declaration (http://www.w3.org/2001/04/xmlenc#) and has an attribute named MimeType with value text/xml. This attribute advises the recipient of the XML encrypted file that we encrypted an XML file to produce the EncryptedData structure.

The first child of the root EncryptedData element is the EncryptionMethod element. The EncryptionMethod element has an attribute named Algorithm, which specifies the algorithm we used for encryption. The value that we have used for the Algorithm attribute is http://www.w3.org/2001/04/xmlenc#3des-cbc, which specifies the triple DES algorithm for encryption.

The ds:KeyInfo element in Listing 6 is the same as the one used in XMLDS. Note that the ds:KeyInfo element has been borrowed form the XMLDS namespace.

The EncryptedData element has another child element named CipherData, which in turn has a child element named CipherValue. The CipherValue element holds the encrypted content (the encrypted version of the XML document that we wanted to encrypt). Therefore, encrypting the XML file produces the contents of the CipherValue element.

Encrypting a Single Element

We have seen that the EncryptedData structure holds the encrypted data along with relevant information. While encrypting a single element of an XML file, we will use the same concept. Look at Listing 7, in which we have we have encrypted the complete GetSpecialDiscountedBookingForPartners element of Listing 1 by simply replacing it with the EncryptedData element.

You can compare the EncryptedData element of Listing 6 with the EncryptedData element of Listing 7. You will notice that there is one difference. Instead of the MimeType attribute of Listing 6, we now have a Type attribute in Listing 7. The value of this attribute is http:///www.w3.org/2001/04/xmlenc#Element, which means we encrypted an XML element.

Whenever you are encrypting an element of an XML file, you will use the identifier http:///www.w3.org/2001/04/xmlenc#Element as the Type attribute value. This tells the recipient of the XML encrypted file that the encrypted data should be treated as an XML element in decrypted plain text form.

Encrypting the Contents of an Element

Look at Listing 8, in which we have encrypted only the contents of the GetSpecialDiscountedBookingForPartners element by replacing the contents with the EncryptedData structure. This is similar to what we did while encrypting an element (Listing 7. There is a difference; this time, the value of the Type attribute of the EncryptedData tag says http://www.w3.org/2001/04/xmlenc#Content. The value tells that the encrypted data should be treated as element content.

XML Encryption Processing

How will our XML firewall work with these encryption concepts? It will receive Listing 7 or 8 (SOAP messages with encrypted elements or content) and translate the contents to a decrypted form before forwarding the decrypted SOAP message request to the SOAP server.

The recipient of an XML encrypted file (e.g. the hotel's XML firewall in our case) will decrypt the XML encrypted file in the following sequence:

1. Extract the encrypted content of the CypherValue element.
2. Read the algorithm attribute value of the EncryptionMethod element.
3. Read the Type attribute values of the EncryptedData element.
4. Obtain the keying information form the ds:KeyInfo element.
5. Use the information gathered in steps 1, 2, 3, and 4 to construct the plain text (decrypted) file.

An Introduction to Web Service Security

How will our XML firewall use XML signatures and encryption to protect SOAP servers? We have given many examples of using the two technologies individually, but the question of how to apply these two technologies in an XML firewall application to protect a SOAP server still needs to be addressed, especially since neither XMLDS nor XML Encryption are SOAP-specific. So why have we put all the signature related information in the SOAP header? Why not wrap it inside the SOAP body?

The Web Services Security (WSS) specification from OASIS defines the details of how to apply XML signature and XML encryption concepts in SOAP messaging. WSS relies on XMLDS and XML encryption for low level details and defines a higher-level syntax to wrap security information inside SOAP messages.

WSS describes a mechanism for securely exchanging SOAP messages. It provides the following three main security features:

1. Message Integrity
2. User Authentication
3. Confidentiality

Have a look at Listing 9. It is a SOAP message that carries security information according to the WSS syntax. Listing 9 is the same GetSpecialDiscountedBookingForPartners SOAP request that we have seen many times in this article. This time the request's header is carrying digital signature information according to the WSS syntax.

Following are the simple points about Listing 9 that will help you understand WSS syntax:

1. The SOAP:Envelope element in Listing 9 contains namespace declarations for SOAP, WSS, and XMLDS.

2. The SOAP:Header element contains just one child element (wsse:Security), which is the wrapper for all the security information in Listing 9. The wsse:Security element in Listing 9 has two child elements, namely a wsse:BinarySecurityToken element and a ds:Signature element.

3. The wsse:BinarySecurityToken element contains a security token. A security token is like a security pass or an identity card that you are required to show if you want to enter a restricted access area. There are several types of electronic security tokens.

   The most popular and widely used security token is a login-password pair, like the one you use while checking your e-mail.

   A login-password pair is a human readable security token. There are some security tokens that are in binary form (and therefore not necessarily human readable). Such tokens are referred to as binary security tokens. For example an X509 certificate (a widely popular format for digital certificates developed by ITU-T) is a binary security token.

   The ValueType attribute of the wsse:BinarySecurityToken element in Listing 9 tells what type of binary security token is wrapped inside this BinarySecurityToken element. In Listing 9, the ValueType attribute contains wsse:X509v3 as its value, which identifies X509 certificates.

   The EncodingType attribute of the wsse:BinarySecurityToken element tells the encoding of the binary security token. As already explained, it is not possible to wrap binary data inside XML format as such. Therefore, we have to encode binary data (usually as a sequence of base-64 encoded values) before wrapping inside XML. The X509 certificate is wrapped inside the wsse:BinarySecurityToken element as the element content.

4. The ds:Signature element is the same as the one we discussed in the section on XML signatures. Note two important things:

   • Look at the URI attribute of the Reference element. Its value (#myDiscountRequestBody) is a fragment identifier that points toward the SOAP:Body element. This means that the SOAP:Body element is the one that we have signed and wrapped the signature in XMLDS tags.

   • Secondly, also look at what the ds:KeyInfo element contains. It is a wsse:SecurityTokenReference element. The wsse:SecurityTokenReference element contains references to security tokens. In our case, it has a child element named wsse:Reference, whose URI attribute points toward the wsse:BinarySecurityToken element discussed in point 3 above. This means that the public key inside the X509 certificate (which the wsse:BinarySecurityToken element wraps) will be used to verify the signature.

This is a very simple example to introduce signed WSS messages. The third and fourth parts of this series will explore further details of XML-based security, the different types of security tokens that we can use with WSS, and the use of XML encryption in WSS messages.

In the next article, we will discuss Security Assertions Markup Language (SAML), which provides a way for web service applications to share user authentication information. This sharing of authentication data is commonly referred to as single sign-on. SAML can be used as a security token in WSS applications. The next article will elaborate why, when, and how.

Resources: Check the official XML Signature and XML Encryption workgroup pages at W3C. Here is the Web Services Security page at OASIS-open.org. This two part series of articles (Part 1 and Part 2) by the same author discusses XML canonicalization. This handbook discusses applied cryptography in detail. This includes discussions on keys, encryption, digital signatures, and message digests. Read this article to learn more about X.509 certificates.

---