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

XML Encryption processing involves two different but obviously related processes: the encryption process and the decryption process. We describe each of them in turn .

Encryption Process

The steps in the encryption process are as described in the following sections.

1. Choose an Encryption Algorithm

Under the EncryptionMethod element, you choose one of the supported encryption algorithms, such as 3DES or AES.

2. Obtain an Encryption Key and Optionally Represent It

An encryption key can be obtained and then represented in a wide variety of ways. Often the encryption key is generated, because generating a shared symmetric key is generally a relatively efficient operation, but it can also be pre-generated and looked up in some registry or file that contains an existing key.

We discussed strategies for representing a key in the section on the KeyInfo element earlier. Such strategies can range from not including anything about the key at all (meaning that the encryption key is shared "out-of- band " and both parties know contextually what the key is); to including a key name as a pointer to the key, using some sort of key agreement protocol; or encrypting the encryption key using the public key of the message's receiver.

3. Serialize Message Data

Encryption algorithms expect octets (a stream of bytes), so the XML data to be encrypted must be converted to octets.

4. Encrypt the Data

Now that you have chosen the algorithm, the encryption key, and the raw data, you have everything you need to do the actual cryptographic encryption.

5. Specify the Data Type

Remember that the EncryptedDataType attribute specifies either element or content encryption. This element (which is optional but should probably always be included), along with the optional MimeType and Encoding , are then specified.

6. Build the Corresponding EncryptedData Structure

All the pieces necessary to construct the EncryptedData element have now been identified. They are then assembled into the EncryptedData structure described earlier in this chapter in the "EncryptedData" section.

Decryption Process

We just described the steps for encryption; next are the high-level steps for decryption.

1. Get Algorithm, Parameters, and KeyInfo

The encryption algorithm (and related parameters) and the KeyInfo element are optional because they may already be known to the receiver based on some agreement outside the message exchange. If they are not already known, any parameters specific to this encryption algorithm and KeyInfo elements should be included in the EncryptedData element's EncryptionMethod .

2. Locate the Key

If the key was agreed to outside the message exchange, locating the key is not necessary. Otherwise, the KeyInfo block must be used to find the key. As we have discussed in this chapter and the preceding chapter, you can include a key in various ways. If the KeyInfo contains a reference to an EncryptedKey , this decryption process must occur recursively until the encryption key is resolved.

3. Decrypt Data

Remember that the encrypted data ( CipherData ) can be in one of two forms: an inline CipherValue or a CipherReference . The decryption process varies by which CipherData child is present; however, the result of either of the following steps is the raw bytes needed to feed into the decryption algorithm:

• CipherValue ” If the CipherData is represented as a CipherValue , the content of the CipherValue element is Base-64 decoded into bytes.

• CipherReference ” If the CipherData is represented as a CipherReference , the URI is dereferenced, and any specified Transforms are applied.

4. Process XML Elements or XML Element Content

At this point, the decryption has occurred, and the UTF-8 encoded bytes are available. If the EncryptedDataType attribute has been specified (either element or content ), the decrypted information is placed back into the original XML, replacing the EncryptedData structure. If the EncryptedDataType attribute is not specified, go to the next step.

5. Process Non “XML Element (Type Not Specified)

If the EncrypteDataType attribute is not specified, the result of the decryption is passed back to the application. The EncryptedData , MimeType , and Encoding are optional advisory information to help the application know how to deal with the data.