XML Signature Structure

In the following sections, we review the XML Signature element's basic structure and discuss its most significant aspects. We stay high level at first and then provide more detail further into the chapter.

Basic Structure

Before we delve deeply into the syntax of the Signature element, let's discuss it in concept first. At a very basic level, an XML Signature contains four major items, with the third and fourth being optional:

• A set of pointers (references) to things to be signed

• The actual signature

• (Optional) The key (or a way to look up the key) for verifying the signature

• (Optional) An Object tag that can contain miscellaneous items not included in the first three items

The syntax of the Signature element is shown in Listing 4.1.

Listing 4.1. The Syntax of the <Signature> Element

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

Listing 4.2 is a highly oversimplified XML Signature snippet to give you a feel for what an XML Signature might look like if it is cut down to its bare essence.

Listing 4.2. A Highly Simplified XML Signature Snippet

 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>     <Reference URI="http://www.foo.com/secureDocument.html" />   </SignedInfo>   <SignatureValue>...</SignatureValue>   <KeyInfo>...   </KeyInfo> </Signature> 

In this example, the three children of the Signature element are the SignedInfo element, the SignatureValue element, and the KeyInfo element. The SignedInfo element contains information about what is being signed, the SignatureValue element contains the actual signature bits, and the KeyInfo element contains information about the public key needed to validate this digital signature. Of course, this example is highly simplified; there is more detail to each of these elements, and there are more elements to discuss. However, these are the most significant three elements within a typical XML Signature.

Specifying the Items Being Signed

The set of pointers, represented by the Reference element, can point to an internal resource in the XML document, in which case they point to an XML node, or they can be external. If they are external, they can point to a binary or non-XML file (for example, an image or text document), or they can point to another XML document or even a node within another XML document. We discuss this usage in more depth in the section titled "The Reference Element." The content behind these references is what is being signed.

Understanding this reference concept is important because it can affect the meaning and usage of XML Signatures substantially. Most descriptions of XML Signature describe three classifications of XML Signatures: Enveloping, Enveloped , and Detached . Each reflects where the Reference element is pointing. Let's go through these three types of XML Signatures and then come back to that point.

Types of XML Signatures

As we mentioned previously, when reading about or discussing XML Signature, you will often hear about three different types of XML Signatures: Enveloping, Enveloped, and Detached. In the next three sections, we describe each of these signature types and show you how they work.

Enveloping Signatures

An Enveloping Signature wraps the item that is being signed, as shown in Figure 4.1. Later, we discuss specifically how this is done, but for now suffice it to say that the reference is to an XML element within the Signature element itself. The following simplified example in Listing 4.3 shows what an Enveloping Signature might look like (notice that the URI points to an item within the Signature Object element):

Listing 4.3. A Simplified Enveloping Signature

 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>     <Reference URI="#111" />   </SignedInfo>   <SignatureValue>...</SignatureValue>   <KeyInfo>...</KeyInfo>   <Object>      <SignedItem id="111">Stuff to be signed</SignedItem>   </Object> </Signature> 

Figure 4.1. Structure of an Enveloping Signature.

Enveloped Signatures

In an Enveloped Signature , the reference points to a parent XML element, as shown in Figure 4.2. The following simplified example in Listing 4.4 shows what an Enveloped Signature might look like (notice that the Reference is to an element that is a parent of the Signature):

Listing 4.4. A Simplified Enveloped Signature

 <PurchaseOrder id="po1">   <SKU>125356</SKU>   <Quantity>17</Quantity>   <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">     <SignedInfo>       <Reference URI="#po1" />     </SignedInfo>     <SignatureValue>...</SignatureValue>     <KeyInfo>...</KeyInfo>   </Signature> </PurchaseOrder> 

Figure 4.2. Structure of an Enveloped Signature.

Detached Signatures

Finally, a Detached Signature points to an XML element or binary file outside the Signature element's hierarchy. In other words, the item being pointed to is neither a child (Enveloping Signature) nor a parent (Enveloped Signature) of the Signature element. Therefore, a Detached Signature could point to an element within the same document, as shown in Figure 4.3, or to a another resource completely outside the current XML document, as shown in Figure 4.4. The following example in Listing 4.5 of a Detached Signature points to another XML element within the same XML document but is not an ancestor or child of the Signature:

Listing 4.5. Structure of a Detached Signature

 <PurchaseOrderDocument>   <PurchaseOrder id="po1">     <SKU>12366</SKU>     <Quantity>17</SKU>   </PurchaseOrder>   <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>     <Reference URI="#po1" />   </SignedInfo>   <SignatureValue>...</SignatureValue>   <KeyInfo>...</KeyInfo> </Signature> 

Figure 4.3. Structure of a Detached Signature within the same XML document.

Figure 4.4. Structure of Detached Signature referencing an external resource.

A Detached Signature can also point to an external resource such as another XML document, a node in another XML document, a text file, or generally any type of resource that can be referenced by a URI, as shown in Figure 4.4. The following simplified example in Listing 4.6 of a Detached Signature points to a JPEG file:

Listing 4.6. A Detached Signature of an External JPEG File

 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>     <Reference URI="http://www.foo.com/picture.jpg" />   </SignedInfo>   <SignatureValue>...</SignatureValue>   <KeyInfo>...</KeyInfo> </Signature> 

Even though these are often called signature types, even in the XML Signature specification, they are really about references. It would be more accurate to describe them as Enveloping Reference, Enveloped Reference, and Detached Reference . Then the next statement becomes more understandable. An XML Signature can be enveloping, enveloped, and detached all at the same time! This means that the Signature element can contain more than one Reference element, and a Reference element can be enveloping, enveloped, or detached.

We wanted to give you the highest level overview of XML Signature and emphasize that XML Signature is mostly just one or more pointers (references) that can point to XML elements, internal or external to the Signature itself, or to an external resource. These pointers are dereferenced and grouped together; then they go through a signature process resulting in a signature. All of this ”the pointers, the signature itself, and, optionally , the key information to validate the signature ”goes into an XML Signature element.

Now let's go to the next level of detail and explore the different aspects of the Signature element.

The Signature Element Schema

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

^[1] XML Signature Specification, http://www.w3.org/TR/xmldsig- core

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.