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

We have reviewed at a high level the XML Signature elements. Now let's review how an XML Signature is created and then subsequently verified before we go into each element in more detail. This process is actually relatively straightforward. The basic steps are described in the following sections. (Note that unless you are writing a signature processing engine, you won't be performing this process yourself. This description is provided mainly so that you understand what is going on under the covers.)

XML Signature Generation

XML Signature generation is broken down into two components : Reference generation and Signature generation.

Reference Generation

When generating an XML Signature, an XML Signature processing engine first creates all the References. This process involves iterating through all the data objects that are to be signed and calculating their digest value. This basic process is as follows :

1. Obtain the resource specified by the Reference URI or, if not specified, as determined by the application. Note that seeing XML Signatures that do not use that Reference element to refer to what is being signed is rare; however, the specification allows for the possibility that what is being signed is known from the context of the situation and therefore does not have to be specified.

   In the example earlier, the reference http://www.foo.com/securePage.html would be dereferenced.

2. Apply the Transforms.

   No Transforms were used in the earlier example. A simple Transform might be an XPath statement that causes the signature to apply only to a part of an XML document. We describe Transforms in more detail later in the chapter.

3. Calculate the Digest using the DigestMethod specified. This step results in the creation of the DigestValue element.

4. Create the Reference element, including all the sub-elements described previously.

At the end of Reference generation, the XML Signature processing engine will have everything necessary to generate the Reference element. In the simple example used earlier, this looks like Listing 4.9.

Listing 4.9. The XML Signature <Reference> Element

<Reference URI="http://www.foo.com/securePage.html"> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /> <DigestValue>60NvZvtdTB+7UnlLp/H24p7h4bs=</DigestValue> </Reference>

Signature Generation

After all the Reference elements are created, the XML processing engine can create the Signature itself. To do this, it must gather all the information necessary to create the SignedInfo element, which is what is actually signed in an XML Signature. Here are the steps:

1. Create the SignedInfo element itself, including the Reference objects created in Reference generation and the CanonicalizationMethod , SignatureMethod , and DigestMethod . The information in SignedInfo is what is actually signed. Listing 4.10 shows the SignedInfo from the earlier example.

   Listing 4.10. The <SignedInfo> Element

   <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2000/WD-xml-c14n-20001011" /> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" /> <Reference URI="http://www.foo.com/securePage.html"> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /> <DigestValue>60NvZvtdTB+7UnlLp/H24p7h4bs=</DigestValue> </Reference> </SignedInfo>

2. Canonicalize SignedInfo using the CanonicalizationMethod specified. We talk in detail about canonicalization later, but suffice it to say that whenever XML is being signed, it needs to be "normalized" before creating the hash and actually signing the SignedInfo information.

3. Using the output from the canonicalization algorithm, create a hash of the SignedInfo element using the specified DigestMethod .

4. Calculate the SignatureValue using the algorithm specified in SignatureMethod against the hashed , canonicalized SignedInfo element that was calculated in step 3. Listing 4.11 shows the SignatureValue element from the earlier example:

   Listing 4.11. The <SignatureValue> Element

   <SignatureValue> hTHQJyd3C6ww/OJz07P4bMOgjqBdznSUOsCh6P+0MpF69w2tln/PFLdx/EP4/VKX </SignatureValue>

5. Bundle the SignedInfo , SignatureValue , KeyInfo (if supplied), and Object (if necessary) into the Signature element.

You now have an XML Signature. The key point to remember here is that the SignedInfo element is what is really being signed, not the direct resource(s) targeted by the Reference URI(s). Of course, because a digest of the target URI(s) is included in the SignedInfo element, it is being indirectly signed along with the information about the signature in the SignedInfo element.

XML Signature Validation

The process to validate an XML Signature is similar, except that it occurs in reverse. It is composed of two major processes like Signature generation: Reference validation and Signature validation. The goal of Reference validation is to ensure that the resource being pointed to by each Reference has not been changed. The goal of Signature validation is to ensure that the entire SignedInfo block has not been changed. Only if both of these processes succeed is integrity confirmed for the entire Signature.

Reference Validation

For Reference validation, you need to validate that the resources pointed to by the Reference elements have not changed. The first step is to canonicalize the SignedInfo element based on the CanonicalizationMethod element. Then the following steps are completed for each Reference element in the SignedInfo .

1. Get the data that is pointed to in the Reference. This will either be from the URI attribute, or as we mentioned above, it may be supplied by the application calling the XML Signature processing engine.

2. Apply any Transforms to the data returned. For example, if the Reference URI points to an XML document, it is likely that a Canonicalization Transform will be specified in the Reference element.

3. Create a hash of the data using the DigestMethod specified in the Reference.

4. Compare the resulting hash with the DigestValue in the Reference. If there is any difference, the validation fails.

Signature Validation

If Reference validation is successful, the XML Processing engine can proceed to Signature validation. The objective of the Signature validation step is to confirm that SignedInfo has not been changed (integrity) and, as in any digital signature verification, that the appropriate key has signed this information (that is, non- repudiation ). Here are the steps for Signature validation:

1. Obtain the key for verification from the KeyInfo block, or in some other manner. Note that it is critical to determine trust for this key ”ensuring that it is certainly bound to the expected identity. You learn more about this topic in Chapter 9, "Trust, Access Control, and Rights for Web Services."

2. Using the output of the SignedInfo canonicalization, create a hash of the SignedInfo .

3. Using the verification key, decrypt the SignedInfo element. Compare the hash from step 2 to the result of this verification. If they do not match, Signature validation has failed.