Look at Listing 4.7 for an XML shorthand schema for the Signature element. It comes directly from the XML Signature specification1 and, for convenience, is a repeat of the schema shown previously. Understanding this structure is key to understanding XML Signature.

Listing 4.7 XML Shorthand Schema for the <Signature> Element

<Signature ID?>
 <SignedInfo>
  <CanonicalizationMethod/>
  <SignatureMethod/>
  (<Reference URI? >
   (<Transforms>)?
   <DigestMethod>
   <DigestValue>
   </Reference>)+
 </SignedInfo>
 <SignatureValue>
 (<KeyInfo>)?
 (<Object ID?>)*
</Signature>

---

Reading an XML Shorthand Schema - A common shorthand for describing XML is to show the XML syntax with a set of "cardinality" indicators, the number of times that an element can occur. If there is always exactly one, there is no cardinality indicator. If there can be zero or one occurrence, the element or attribute is given a question mark (?) cardinality indicator. If the element or attribute can have one or more occurences, the element or attribute is given a plus sign (+) cardinality indicator. And finally, if the element or attribute can have zero or more occurences, the element or attribute is given an asterisk (*) cardinality indicator.

If an element has a cardinality indicator, it is usually wrapped in parentheses, and the cardinality indicator appears after the closing parenthesis. For example, in the XML Signature shorthand schema, the KeyInfo element is represented as (<KeyInfo>)?, which means that the KeyInfo can exist one or zero times. The Object element, shown as (<Object ID?>)*, can appear zero or more times, and its ID attribute can exist zero or one time within an Object attribute.

---

You need to familiarize yourself with this shorthand schema at a high level before you focus on each element. The more familiar you become with this schema, the better. A Signature must have at least a SignedInfo and a SignatureValue. A Signature can optionally have a KeyInfo or an Object. For now, just think of the Object as the place to put the thing that is being signed when you have an Enveloping reference.

At the next level, the SignedInfo must contain a CanonicalizationMethod, a SignatureMethod, and one or more Reference elements.

At a high level, canonicalization is a strategy for standardizing XML structures so that they compare the same across multiple platforms or different equivalent XML syntax. CanonicalizationMethod is a pointer to the actual algorithm used to do this. We discuss this in more detail in "The CanonicalizationMethod Element and Canonicalization" section later in this chapter.

SignatureMethod is a pointer to the signature algorithm (one you will be familiar with from Chapter 3) used to calculate the digital signature.

The Reference elements are the pointers to what is being signed. The Reference element has a URI attribute, which is the actual pointer we alluded to earlier. We talk more about URIs later, but you need to understand now that the power and flexibility of URIs to point to just about any type of resource are critical to the power and flexibility of XML Signature. The Reference element can optionally contain one or more Transform elements—a powerful, necessary, but potentially dangerous, way of changing the document in some fashion before it is digested. Finally, the Reference element has a DigestMethod that contains the one-way hash algorithm (for example, SHA1) used to calculate the DigestValue for the Reference.

These elements are in SignedInfo, which is the XML block representing the information that will be signed.

The SignatureValue element is a digital signature of the SignedInfo block. This is an important point: What is signed is the SignedInfo block, not what was referenced in the SignedInfo block. In reality, both are signed at the same time because, if you remember from Chapter 3, with a digital signature you are encrypting/signing a digest. By digitally signing the SignedInfo block, which contains the digest of the references, you are not only signing the references, but you are also signing critical information about the signature itself, such as which signature algorithm was used, so that these items are also protected. This is required because it might be possible, by fiddling with the type of information that is in the SignedInfo element, to compromise a signature. The SignatureValue has no children; it just has the Base-64 encoded value of the binary signature data in it.

These two elements, SignedInfo and SignatureValue, are the guts of an XML Signature. Optionally, you can have a KeyInfo block that either contains the key to use for verifying the signature or has information necessary to look up such a key. KeyInfo has many children and is fairly complex. Also, under the Signature element, you can have an Object element. We discuss both KeyInfo and Object in more detail later in this chapter.

Now that we have quickly gone through most of the elements that comprise an XML Signature, let's look at a fuller but still simplified snippet of an XML Signature in Listing 4.8.

Listing 4.8 A Fuller XML Signature Example

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
 <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>
 <SignatureValue>
  hTHQJyd3C6ww/OJz07P4bMOgjqBdznSUOsCh6P+0MpF69w2tln/PFLdx/EP4/VKX
 </SignatureValue>
 <KeyInfo>
  <KeyValue>
   <RSAKeyValue>
    <Modulus>
     uCiukpgOaOmrq1fPUTH3CAXxuFmPjsmS4jnTKxrv0w1JKcXtJ2M3akaV1d/karvJ
    </Modulus>
    <Exponent>
     AQBB
    </Exponent>
   </RSAKeyValue>
  </KeyValue>
  <X509Data>
   <X509SubjectName>
    CN=David Remy,O=BEA Systems Inc,ST=WA,C=US
   </X509SubjectName>
   <X509IssuerSerial>
    <X509IssuerName>
     CN=Test CA,O=GeoTrust Inc,ST=MA,C=US
    </X509IssuerName>
    <X509SerialNumber>167355</X509SerialNumber>
   </X509IssuerSerial>
   <X509Certificate>
    MIICeDCCAeGgAwIBAgIEOd3+iDANBgkqhkiG9w0BAQQFADBbMQswCQYDVQQGEwJJ
    ...
    C/I/k9xGr7fneoIW
   </X509Certificate>
  </X509Data>
 </KeyInfo>
</Signature>

As you can see, this XML Signature signs the Web page http://www.foo.com/securePage.html. Of course, you know this because you looked at the Reference element child of the Signature element (bold in the preceding code snippet). A lot of other information is also included in an XML Signature. As you will see in the following sections, each piece of information plays a significant role.

This chapter is from Securing Web Services Security with WS-Security, by Jothy Rosenberg and David Remy (Sams, 2004, ISBN: 0672326515). Check it out at your favorite bookstore today. Buy this book now.