The Structure of an XMLDSIG Signature

for RuBoard

We turn our attention now to the structure of an XMLDSIG signature object and its various subcomponents. Our goal in this section is to provide a comprehensive guide to an XMLDSIG Signature element and its various subcomponents. We will walk through the Signature structure in a top-down fashion, first describing the high-level components of a signature and then describing the various subcomponents in more detail.

Figure 32.5 shows a graphical block diagram of the major components that together comprise an XMLDSIG signature object, and the corresponding XML structure is shown in Listing 32.3.

Figure 32.5. Block diagram of the top-level components of an XMLDSIG signature.

Listing 32.3 A High-Level Representation of an XMLDSIG Signature

 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>     <CanonicalizationMethod Algorithm="  URI identifier for canonicalization algorithm  " />     <SignatureMethod Algorithm="  URI identifier for signature algorithm  " />     <Reference URI="  URI pointing to the signed content  ">       <DigestMethod Algorithm="  URI identifier for hash algorithm  " />       <DigestValue>  hash value of the signed content  </DigestValue>     </Reference>   </SignedInfo>   <SignatureValue>  Signature computed over the hash of the canonicalized SignedInfo element  </SignatureValue>   <KeyInfo>  optional key-related information goes here  </KeyInfo>   <Object Id="  ID value so this object may be referenced via fragment URI  ">  optional embedded objects go here  </Object> </Signature> 

In Listing 32.3, every XMLDSIG signature is represented by an XML element tag named Signature in the XMLDSIG namespace. By definition in the specification, the XMLDSIG namespace is identified by the URL http://www.w3.org/2000/09/xmldsig# , so the top-level element of an XMLDSIG signature will look as follows : <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"></Signature>

or, alternatively, the namespace will be bound to some prefix and look like the following, where ds is the local prefix bound to the XMLDSIG namespace:

 <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> ... </Signature> 

NOTE

The XMLDSIG standard assumes that readers and implementers have a good background with core XML specifications, including the base XML specification, XML namespaces, and XML Schema. Understanding core XML processing and namespaces is vital to understanding some of the nuances of the XMLDSIG standard.

For ease of reference, we will subsequently assume that this namespace URL is defined as the ds namespace, which allows us to use XML prefix qualification for all XMLDSIG tag names . For example, from now on, we will write the XMLDSIG Signature element as <ds: Signature >...</ds: Signature > to represent the fact that Signature is defined in the XMLDSIG namespace.

Our descriptions of each of the elements in an XMLDSIG signature will adhere to the following pattern. First, we will show the XML Schema description for the element and a sample of how the element is used. We will then identify attributes and child elements that can appear within the structure.

NOTE

Many elements in the XMLDSIG standard are defined with optional Id attributes that can be used to name and reference the element elsewhere within the document. Except where specifically interesting, such as the use of Id elements to reference a ds:Object within a ds:SignedInfo for a wrapped signature, we will ignore the presence of the Id attributes in the schema.

The ds:Signature Element

We begin our tour of XMLDSIG elements at the top, with the ds:Signature element itself. Listings 32.4 and 32.5 show the XML Schema for the ds:Signature element and an example ds:Signature element, respectively. (The detailed contents of the child element have been omitted for readability.)

Listing 32.4 XML Schema for the ds:Signature Element

 <element name="Signature" type="ds:SignatureType"/>    <complexType name="SignatureType">      <sequence>        <element ref="ds:SignedInfo"/>        <element ref="ds:SignatureValue"/>        <element ref="ds:KeyInfo" minOccurs="0"/>        <element ref="ds:Object" minOccurs="0" maxOccurs="unbounded"/>      </sequence>      <attribute name="Id" type="ID" use="optional"/>    </complexType> 

Listing 32.5 Sample ds:Signature Element

 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>     <!-- SignedInfo contents -->   </SignedInfo>   <SignatureValue>46qK2Zz3FuyXkjN5jDkrU947hXl8BwMQjC8qS+pzt4JOouHWva     CKUY8E7SaxeRnnDaWlBCOHWK7XIA1o8j2CtlZvjrv5itNEBcAOIZejtoSucEYIf7UM     cZUgtVX4ORlNuhSygJVbSwggkLPVwkdBATdKULAF2Pz+bRCUpYyOgUE=   </SignatureValue>   <KeyInfo>   </KeyInfo>   <Object Id="object">     <!--Object contents -->   </Object> </Signature> 

Every ds:Signature element contains at least two child elementsa ds:SignedInfo element and a ds:SignatureValue element. The ds:SignatureValue element is exactly as it is named; it is a text node whose value is a Base64-encoded binary value corresponding to a digital signature computation. The ds:SignedInfo element specifies the XML content that was signed to produce the ds:SignatureValue . These two elements, ds:SignedInfo and ds:SignatureValue , hold the two core pieces of information carried in every XMLDSIG signaturewhat was signed and the value of the signature.

Table 32.2 lists the defined child elements of a ds:Signature element.

Table 32.2. Children of the ds:Signature Element

Element/Attribute Name	Contents	Mandatory or Optional	Number Appearing
SignedInfo (element)	Pointers (hash references) to the signed content	Mandatory	1
SignatureValue (element)	The actual digital signature value, Base64-encoded	Mandatory	1
KeyInfo (element)	Information related to the key used to generate the digital signature	Optional	Exactly 1 if presen
Object (element)	Any XML content, but generally used with wrapped signatures to include signed content within the Signature element	Optional	Any number may be present

A ds:Signature element can optionally contain two additional types of elements in addition to the ds:SignedInfo and ds:SignatureValue elements. The first optional component, the ds:KeyInfo element, can only occur once in the ds:Signature block if present. The ds:KeyInfo element holds information that is intended to help the signature verifier find the public key needed to verify the signature. Essentially , ds:KeyInfo is a container for carrying any and all key-related information that the signature constructor thinks will be helpful to the verifier. For example, ds:KeyInfo can contain elements that specify the actual values of the public verification key. The ds:KeyInfo element could contain certificates for the verification key, intended to be used by the recipient (signature verifier) to validate that the key pair used to sign the message should be trusted to make the statements it did. It is also possible (and in many scenarios likely) to embed within the ds:KeyInfo element pointers (URIs) to structures that contain key-related information, so a signature verifier can find the information if necessary. We will see detailed examples of the various uses of ds:KeyInfo in the "Creating XMLDSIG-Compliant Signatures Using the .NET Framework" section later in this chapter.

Finally, a ds:Signature can optionally include one or more ds:Object elements. The ds:Object element is a wrapper element that is used to include any desired additional data within a ds:Signature . Usually ds:Object elements are used to embed to-be-signed content when creating "wrapped" signatures, in which case, the ds:Object will be explicitly referenced by one or more components of its sibling ds:SignedInfo element. However, the ds:Object element can also be used to carry unsigned information along with the signature if that is desired by the application.

The ds:SignatureValue Element

The ds:SignatureValue element is the child element of a ds:Signature that contains the actual digital signature value. It is always the second child of the ds:Signature element; we describe it here first because its structure is simple compared to ds:SignedInfo . Listing 32.6 shows the XML Schema for ds:SignatureValue elements and a sample element is shown in Listing 32.7. A ds:SignatureValue element contains only text content, and that text content must be of type base64Binary , which means simply that it is the Base64-encoding of an arbitrarily large binary value. The interpretation of the contents of the ds:SignatureValue element varies depending on the exact algorithm used to create the signature, so it is impossible to parse or understand the contents of the ds:SignatureValue element without first looking in the ds:SignedInfo element to see what algorithm was used to compute the signature.

Listing 32.6 XML Schema for the ds:SignatureValue Element

 <element name="SignatureValue" type="ds:SignatureValueType"/> <complexType name="SignatureValueType">   <simpleContent>     <extension base="base64Binary">       <attribute name="Id" type="ID" use="optional"/>     </extension>   </simpleContent> </complexType> 

Listing 32.7 Sample ds:SignatureValue Element

 <SignatureValue>46qK2Zz3FuyXkjN5jDkrU947hXl8BwMQjC8qS+pzt4JOouHWva   CKUY8E7SaxeRnnDaWlBCOHWK7XIA1o8j2CtlZvjrv5itNEBcAOIZejtoSucEYIf7UM   cZUgtVX4ORlNuhSygJVbSwggkLPVwkdBATdKULAF2Pz+bRCUpYyOgUE= </SignatureValue> 

The ds:SignedInfo Element

The ds:SignedInfo element identifies the exact content signed by the digital signature and is always the first child element of every ds:Signature element. The content contained within a ds:SignedInfo element answers three questions: what content is signed by the digital signature, how is the ds:SignedInfo element to be canonicalized, and what signature algorithm was used to generate the signature. Listings 32.8 and 32.9 show the XML Schema for the ds:SignedInfo element and a sample instance, respectively.

Listing 32.8 XML Schema for the ds:SignedInfo Element

 <element name="SignedInfo" type="ds:SignedInfoType"/>  <complexType name="SignedInfoType">    <sequence>      <element ref="ds:CanonicalizationMethod"/>      <element ref="ds:SignatureMethod"/>      <element ref="ds:Reference" maxOccurs="unbounded"/>    </sequence>    <attribute name="Id" type="ID" use="optional"/>  </complexType> 

Listing 32.9 Sample ds:SignedInfo Element

 <SignedInfo>   <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />   <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />   <Reference URI="http://tempuri.org/">     <!--Reference content goes here -->   </Reference> </SignedInfo> 

Recall from the "XMLDSIG Design Principles and Modes of Use" earlier in this chapter the requirement that XMLDSIG signature be applied to entire XML documents, partial XML documents, and even non-XML content. This requirement forces XMLDSIG to support detached signatures (signatures separate from the signed content), and, as a result, XMLSIG uses a detached signature model for creating all of its signatures. In an XMLDSIG signature, the digital signature is computed over the contents of just the ds:SignedInfo element, and the ds:SignedInfo element in turn contains cryptographic references to the actual content. That is, a ds:SignedInfo element is really a collection of "hash references" to the to-be-signed content, where each reference identifies the to-be-signed content and the value obtained by applying a cryptographic hash function to the content. When the ds:SignedInfo element is hashed and signed, these hash references are implicitly included in the signature. Changing a single bit in the signed content will change its hash value, which will change the hash of the ds:SignedInfo element and cause the digital signature of the ds:SignedInfo element to change.

A ds:SignedInfo element contains at least three child elements, as shown in Table 32.3. The first child is the ds:CanonicalizationMethod element, which indicates how the ds:SignedInfo element itself was canonicalized before being signed. The second child element is the ds:SignatureMethod element, which identifies the digital signature algorithm used to sign the canonical form of the ds:SignedInfo element. Remaining child elements are ds:Reference elements that are hash references to the to-be-signed content.

Table 32.3. Children of the ds:SignedInfo Element

Element/Attribute Na me	Contents	Mandatory or Optional	Number Appearing
CanonicalizationMethod	Algorithm to use to canonicalize the ds:SignedInfo element	Mandatory	1
SignatureMethod	Algorithm to use to compute the signature of the ds:SignedInfo element	Mandatory	1
Reference	Structure that identifies to-be- signed content along with its cryptographic hash value	Mandatory	At least 1

While it is possible to specify and use any canonicalization algorithm to canonicalize ds:SignedInfo , it is almost always the case that the mandatory-to-implement Canonical XML algorithm is used. The schema for ds:CanonicalizationMethod is shown in Listing 32.10. The schema specifies one mandatory attributea URI identifying the canonicalization algorithmand optional substructure for specifying any parameters of the canonicalization algorithm.

Listing 32.10 XML Schema for the ds:CanonicalizationMethod Element

 <element name="CanonicalizationMethod" type="ds:CanonicalizationMethodType"/>    <complexType name="CanonicalizationMethodType" mixed="true">      <sequence>        <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>      </sequence>      <attribute name="Algorithm" type="anyURI" use="required"/>    </complexType> 

When canonical XML is used as the canonicalization method, the resulting ds:CanonicalizationMethod contains only an algorithm identifier and looks as follows:

 <CanonicalizationMethod Algorithm= "http://www.w3.org/TR/2001/REC-xml-c14n-20010315" /> 

The ds:SignatureMethod element is structurally very similar to the ds:CanonicalizationMethod element in that it specifies the signature algorithm by URI in an attribute and allows optional algorithm parameters to be embedded as substructure. For DSA and RSA signatures, the SignatureMethod elements will appear as follows:

 <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" /> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1" /> 

An HMAC-SHA1 ds:SignatureMethod will appear in one of two forms depending on whether the optional parameter is used.

The following are sample HMAC-SHA1 SignatureMethod s using 160 bits (full output) and 40 bits (truncated):

 <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1" /> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1">   <HMACOutputLength>40</HMACOutputLength> 

Listing 32.11 shows the entire schema for ds:SignatureMethod . Notice that the only difference between this schema and the schema for ds:CanonicalizationMethod shown in Listing 32.10 is the specification of an optional parameter that is used with HMAC-SHA1 "signatures."

Listing 32.11 XML Schema for the ds:SignatureMethod Element

 <element name="SignatureMethod" type="ds:SignatureMethodType"/>    <complexType name="SignatureMethodType" mixed="true">      <sequence>        <element name="HMACOutputLength" minOccurs="0" type="ds:HMACOutput LengthType"/>        <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>        <!-- (0,unbounded) elements from (1,1) external namespace -->       </sequence>     <attribute name="Algorithm" type="anyURI" use="required"/>    </complexType> 

NOTE

Recall from Chapter 31 that a keyed MAC function, such as HMAC-SHA1, can be used to provide integrity protection between two parties that share a secret key. XMLDSIG allows HMAC-SHA1 (and any other keyed MAC) to be used as a "signature" algorithm between parties sharing secret key material by simply using the output of the keyed MAC as the signature value. The optional parameter for HMAC-SHA1 is a desired output length that tells XMLDSIG to use only a portion of the computed HMAC-SHA1 value as the actual signature value. Unless specifically required, you will always want to use the full length (160 bits) output by HMAC-SHA1 when it is your signature algorithm.

The ds:Reference Element

The remaining children of a ds:SignedInfo element are ds:Reference elements that identify the actual content signed by the signature. At least one ds:Reference element must be present in a ds:SignedInfo , because the signature must protect some content. Multiple distinct pieces of to-be-signed content can be jointly protected by a single signature by including multiple ds:Reference elements within a ds:SignedInfo .

The schema for a ds:Reference element is shown in Listing 32.12 and its child elements and attributes are summarized in Table 32.4. Each hash reference needs to contain information exactly identifying the to-be-signed content, the hash algorithm used to hash the content, and the actual hash value. The hash algorithm and hash value are contained in child elements ds:DigestMethod and ds:DigestValue , respectively. The schema for ds:DigestMethod (shown in Listing 32.13) is basically the same structure used previously for ds:CanonicalizationMethod an Algorithm attribute whose value is a URI identifying the hash algorithm to use and optional open substructure that can be used to hold algorithm parameters. The ds:DigestValue is simply another Base64-encoded binary value, so its schema (Listing 32.14) is essentially the same as that of ds:SignatureValue .

Listing 32.12 XML Schema for the ds:Reference Element

 <element name="Reference" type="ds:ReferenceType"/> <complexType name="ReferenceType">   <sequence>     <element ref="ds:Transforms" minOccurs="0"/>     <element ref="ds:DigestMethod"/>     <element ref="ds:DigestValue"/>   </sequence>   <attribute name="Id" type="ID" use="optional"/>   <attribute name="URI" type="anyURI" use="optional"/>   <attribute name="Type" type="anyURI" use="optional"/> </complexType> 

Table 32.4. Children of the ds:Reference Element

Element/Attribute Na me	Contents	Mandatory or Optional	Number Appearing
URI (attribute)	URI for the source of the to-be- signed content	Optional	At most 1
Type (attribute)	Optional attribute used to identify the type of content to be retrieved from the URI in the URI attribute	Optional	At most 1
Transforms (element)	If present, contains a sequence of algorithms that transform content obtained from the URI before signing	Optional	At most 1
DigestMethod	The hash algorithm to use when calculating the hash of the to-be- signed content	Mandatory	1
DigestValue	The hash value of the to-be-signed conten	Mandatory	1

Listing 32.13 XML Schema for the ds:DigestMethod Element

 <element name="DigestMethod" type="ds:DigestMethodType"/>    <complexType name="DigestMethodType" mixed="true">      <sequence>        <any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/  >      </sequence>      <attribute name="Algorithm" type="anyURI" use="required"/>    </complexType> 

Listing 32.14 XML Schema for the ds:DigestValue Element

 <element name="DigestValue" type="ds:DigestValueType"/> <simpleType name="DigestValueType">   <restriction base="base64Binary"/> </simpleType> 

The basic idea behind the Reference Processing Model is that to-be-signed content is defined as the result of taking some input content and processing that content through a series of transformations. A graphical depiction of the Reference Processing Model is shown in Figure 32.6. The input content to be processed is specified via the URI attribute; the value of this attribute is the URI of the content to be retrieved and input for processing. The ds:Transforms element contains one or more individual transformationseach specified by a single ds:Transform elementthat define a stage of processing to be performed on the input. The transforms are chained together, so the output from the first transform in the chain is the input to the second transform in the chain, the output from the second transform is the input to the third transform, and so on, until the chain is completed. The output from the final transform in the chain is the to-be-signed content that needs to be hashed.

Figure 32.6. The Reference Processing Model.

Let's now look at some examples of the Reference Processing Model in action and see how it allows us to easily specify entire documents and portions of document. Referencing an entire document is easywe put the URI to the document in the URI attribute. No transforms need to be specified if we want to sign the entire contents of a URI, so we omit the entire ds:Transforms element. The following is an example of a full-document reference:

 <Reference URI="http://www.farcaster.com/document.xml">   <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />   <DigestValue>XoaHIm+jLKnPocR7FX0678DUOqs=</DigestValue> </Reference> 

The ds:Reference element simply contains the URI of the document to be signed. Because no transforms are specified, the to-be-signed content is exactly the input content retrieved from URI http://www.farcaster.com/document.xml . (Note that in this example, we have not explicitly specified the default namespace and have assumed it has been specified at a higher level. In general, namespace declarations will appear only on the top-level ds:Signature element and be automatically inherited by child elements.) The content is then hashed with SHA1 (identified by the Algorithm attributed on the ds:DigestMethod element) and the result of hashing the content is the Base64-encoded value in the ds:DigestValue element.

Now let's look at how we sign only a portion of a document. If the portion of the document we want to sign is a single element within the document that has an Id attribute, we can reference that single element using a fragment URI. For example, if the document at http://www.farcaster.com/document.xml contains three MyDocumentForm elements, identified as Form1 , Form2 , and Form3 as shown in the following

 <MyDocumentForm Id="Form1">   <!--complex form data goes here --> </MyDocumentForm> <MyDocumentForm Id="Form2">   <!--complex form data goes here --> </MyDocumentForm> <MyDocumentForm Id="Form3">   <!--complex form data goes here --> </MyDocumentForm> 

then we can sign just the content in the Form2 element by using a URI fragment reference as follows:

 <Reference URI="http://www.farcaster.com/document.xml#Form2">   <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />   <DigestValue>XoaHIm+jLKnPocR7FX0678DUOqs=</DigestValue> </Reference> 

The # character is the URI fragment separator; it indicates that the URI references just the sub-element of the document with Id attribute equal to the portion of the URI occurring after the separator.

We could also indicate that the to-be-signed content is just the contents of the Form2 by referencing the entire document in the URI attribute and then selecting the portion we want using a transform. Listing 32.15 shows our first example of using a ds:Transforms element with a URI attribute to invoke the full Reference Processing Model:

Listing 32.15 Sample XMLDSIG Signature Using a Transform

 <Reference URI="http://www.farcaster.com/document.xml>   <Transforms>     <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">       <XPath>         ancestor-or-self::node()[@Id="Form2"]       </XPath>     </Transform>   </Transforms>   <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />   <DigestValue>XoaHIm+jLKnPocR7FX0678DUOqs=</DigestValue> </Reference> 

This ds:Reference says that the to-be-signed content is the result of applying an XPath transform to the content obtained from http://www.farcaster.com/document.xml . XPath (short for XML Path Language) is a W3C Recommendation that defines a language for addressing parts of an XML document. The XPath expression ancestor-or-self::node()[@Id="Form2"] says to select from the input document all elements that have an Id attribute with a value of Form2 .

NOTE

The XPath language is very rich and complex, and we do not have space in this chapter to properly show off all the neat tricks you can perform with XPath expressions. The combination of XPath transforms and XMLDSIG references is very powerful and allows you to sign complicated subsets of XML documents. Support for XPath transforms is RECOMMENDED in the XMLDSIG standard, which means most XMLDSIG implementations will support XPath transforms, but support is not guaranteed . The .NET Framework implementation of XMLDSIG does support XPath transforms through the XmlDsigXPathTransform object, as described in the "Creating XMLDSIG-Compliant Signatures Using the .NET Framework" section later in this chapter.

So far, we have only used a single transform on the content retrieved from the URI in the URI attribute, but the Reference Processing Model permits an unlimited number of transformations to be applied in sequence to the retrieved content. The following is an example showing how multiple sequential transforms can be used. Continuing the previous example, suppose that each MyDocumentForm element contains within it a Picture element, and that the content of the Picture element is a Base64-encoded binary image of some sort . An example MyDocumentForm element would look something like the following (we've omitted other portions of the element that are not relevant to this example):

 <MyDocumentForm ID="Form2">   <!-- some form data goes here -->   <!--  here is an image -->   <Picture>     SSBhbSB0a.......     .......GUgdGV4dC4=   </Picture>   <!-- some more form data goes here --> </MyDocumentForm> 

Now, suppose we want to sign just the binary content of the Picture element in the MyDocumentForm with ID Form2 . We need to construct a chain of transforms that will select the Picture element of the MyDocumentForm in which we are interested and then Base64-decode the encoded image data. XMLDSIG defines a Base64 decoding transform, so we can accomplish this task by combining an XPath transform with a Base64 decoding transform, as shown in the following:

 <Reference URI="http://www.farcaster.com/document.xml>   <Transforms>     <Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">       <XPath>         ancestor-or-self::Picture/../self::node()[@Id="Form2"]       </XPath>     </Transform>     <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#base64" />   </Transforms>   <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />   <DigestValue>XoaHIm+jLKnPocR7FX0678DUOqs=</DigestValue> </Reference> 

The input content to the chain of transformations is the entire document retrieved from http://www.farcaster.com/document.xml . This document is input into the first transform (the XPath transform). Notice that we changed the expression in the XPath transform slightly from the previous example to extract just Picture elements with parent nodes that have an Id attribute with value Form2 . The output of the XPath transform becomes the input to the Base64 decoding transform. By definition (see Section 6.6.2 in the XMLDSIG standard, "XML-Signature Syntax and Processing"), when passed an XML node set, the Base64 decoding transform operates on the text contained within the node, so the Base64 transform will strip off the enclosing <Picture>...</Picture> tags and just decode the encoded content. The resulting decoded bytestream is the to-be-signed content that is then hashed with SHA1.

XMLDSIG defines identifiers for two other types of transformations, which we mention here briefly for completeness. The Extensible Stylesheet Language (XSL) is another W3C Recommendation for describing XML document transformations. XMLDSIG allows any XSL transformation to be used as a ds:Transform by simply including the <xsl:stylesheet> content within a transform as follows:

 <Transform Algorithm="http://www.w3.org/TR/1999/REC-xslt-19991116">   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"     xmlns="http://www.w3.org/TR/xhtml1/strict" version="1.0">     <!-- XSL expression goes here -->   </xsl:stylesheet> </Transform> 

The other transform defined within the XMLDSIG Recommendation is the Enveloped Signature Transform, which is used when an XMLDSIG signature is to be embedded within the signed content (an "enveloped signature" as defined previously in the "XMLDSIG Design Principles and Modes of Use" section). Examples showing uses of the enveloped signature transform are provided in the "Creating XMLDSIG-Compliant Signatures Using the .NET Framework" section later in this chapter.

To conclude our discussion of the ds:Reference element, we need to make two final notes about URIs and the processing model of transform chains. First, in our previous examples, we have also used fully qualified URIs to identify content, but XMLDSIG also allows relative URIs to be used with specific meaning. The following is a list of the special forms of URLs that can appear in a ds:Reference URI attribute:

• The URI "" , the empty-string URI, is always interpreted as the content of the XML resource containing the ds:Reference node. This is typically used with enveloped signatures; the empty-string URI is interpreted to mean the enclosing XML document that contains the embedded signature. (XML comment nodes are excluded from the content of the enclosing document when referenced with an empty-string URI.)

• A fragment URI, such as #Form2 , is interpreted to mean the element with the unique ID matching the fragment appearing in the enclosing document that contains the embedded signature.

• Because the URI attribute is optional, it is possible to omit the attribute entirely from the ds:Reference element. If the URI attribute is omitted, it is assumed that the receiving application verifying the signature has implicit knowledge of the to-be-signed content. Obviously, omitting the URI attribute means that the resulting ds:Reference will only have meaning to those applications with implicit knowledge and will not, in general, be interoperable.

The other closing comment on ds:Reference concerns implicit conversions that occur between transforms in the transform chain. In XMLDSIG, an individual transform (that is, something defined by a ds:Transform element) can accept as input either an octet stream (a stream of arbitrary bytes) or an XML node-set (a parsed XML object), and their output can be either an octet stream or a node-set. When chaining transforms, if the output format of a transform does not match the input format of the next transform in the chain, an implicit conversion is performed automatically by the XMLDSIG implementation. One of two conversions is possible, depending on whether the necessary conversion is octet stream to node-set or node-set to octet stream:

• To convert an octet stream to a node-set, the octet stream is parsed by an XML parser. The octet stream must contain a well- formed serialization of an XML object.

• To convert a node-set to an octet stream, the node-set is canonicalized using the Canonical XML algorithm. (The output of the Canonical XML algorithm is always an octet stream because it is intended to be cryptographically hashed.)

Because the to-be-signed content (the final output of the chain of transformations) is intended to be hashed by the hash algorithm specified in ds:DigestMethod , XMLDSIG implementations force the output of the last stage of the transformation chain to be an octet stream. If the output of the last stage of the chain is a node-set, that node-set will be canonicalized with Canonical XML to create the octet stream to hash. Thus, when the ds:Reference shown in Listing 32.15 is processed, the following steps occur:

1. The content of http://www.farcaster.com/document.xml is retrieved over the network as an octet stream.

2. The octet-stream is implicitly converted, via XML well-formed processing, into a node-set for input into the XPath transform.

3. The XPath transform is applied to the input node-set yielding an output node-set.

4. The node-set output by the XPath transform is implicitly converted into an octet stream by application of the Canonical XML algorithm.

5. The resulting octet stream is input to the SHA1 hash algorithm to compute a hash value.

The implicit conversion rules have the effect of significantly shortening the size and complexity of the ds:Transforms elements in a ds:Reference .

The ds:KeyInfo Element

We now turn our attention to the last major type of child element that can be present in a ds:Signature element. The ds:KeyInfo element is an optional child of ds:Signature that contains information intended to help applications receiving an XMLDSIG signature find the keys necessary to validate that signature. This statement of purpose for the ds:KeyInfo element is somewhat vague because lots of different types of information can appear within a ds:KeyInfo element. For example, a single ds:KeyInfo element might contain one or more of the following types of information:

• An explicit copy of the public key needed to validate the signature

• A symbolic name that identifies the validation key to a receiving application

• A pointer to a URI where a copy of the validating key may be obtained

• A digital certificate (in one or more formats) for the public key that validates the signature

• Revocation information for digital certificates for the validating public key

• Trust management information about the key that generated the signature that will help convince an application receiving the signature that it should take some action

Although many different types of information can appear within a ds:KeyInfo element, the goal of all such information is the sameto provide hints to a signature verifier as to how to find the key necessary to cryptographically validate the signature and convey additional trust information that may be appropriate to the particular application. A copy of the XML schema for the ds:KeyInfo element is shown in Listing 32.16.

CAUTION

It should be stressed that the information provided in a ds:KeyInfo element is advisory in nature and should never be implicitly trusted by a signature verifier. In particular, the presence of some information within the ds:KeyInfo element does not in and of itself imply agreement with the content signed by the signature. Normally, the contents of the ds:KeyInfo element are not covered by the signature, although it is possible to do so by using an Id attribute on the ds:KeyInfo element and referencing the element through a fragment URI in a ds:Reference .

Listing 32.16 XML Schema for the ds:KeyInfo Element

 <element name="KeyInfo" type="ds:KeyInfoType"/> <complexType name="KeyInfoType" mixed="true">   <choice maxOccurs="unbounded">     <element ref="ds:KeyName"/>     <element ref="ds:KeyValue"/>     <element ref="ds:RetrievalMethod"/>     <element ref="ds:X509Data"/>     <element ref="ds:PGPData"/>     <element ref="ds:SPKIData"/>     <element ref="ds:MgmtData"/>     <any processContents="lax" namespace="##other"/>     <!-- (1,1) elements from (0,unbounded) namespaces -->   </choice>   <attribute name="Id" type="ID" use="optional"/> </complexType> 

The child elements of the ds:KeyInfo element defined within the XMLDSIG standard fall into three broad categoriesdirect inclusion of key material, indirect pointers to key material, and trust management information related to signature keys. A summary of all of the defined child elements of the ds:KeyInfo element is contained in Table 32.5.

NOTE

Note that as the entire ds:KeyInfo element is optional, the presence of any specific type of child element is also optional. Conforming implementations of the XMLDSIG standard are required to recognize only the ds:KeyInfo element, the ds:KeyValue child of ds:KeyInfo , and the ds:DSAKeyValue child of ds:KeyValue . Support for all other children of ds:KeyInfo is implementation dependent.

Table 32.5. Children of the ds:KeyInfo Element

Element/Attribute Na me	Contents	Mandatory or Optional	Number Appearing
KeyValue	A single public key value that may be useful in validating the signature.	Optional	Any number
KeyName	A string value intended to identify a key to the recipient of the signature.	Optional	Any number
RetrievalMethod	A reference to KeyInfo information stored external to the signature itself.	Optional	Any number
X509Data	One or more identifiers of keys, X.509v3 certificates, or X.509v2 certificate revocation lists (CRLs) related to the key necessary to validate the signature.	Optional	Any number
PGPData	Information related to PGP public key pairs and signatures.	Optional	Any number
SPKIData	Information related to SPKI public key pairs, SPKI certificates, or other SPKI data.	Optional	Any number
MgmtData	In- band key distribution or agree- ment data. No longer recommended for use as it is being superceded by work done as part of the XML Encryption standard.	Optional	Any number

The most commonly used child element of ds:KeyInfo is the ds:KeyValue element, which is used to directly include a copy of a public key in a signature. For example, Listing 32.17 shows a ds:KeyInfo element, that includes an RSA public key (presumably the public key necessary to validate the signature), and Listing 32.18 shows the equivalent structure for including a DSA public key. Public keys related to a signature are always included as child elements of a ds:KeyValue element, which itself is a child of ds:KeyInfo . The XMLDSIG standard defines structures for holding DSA and RSA public keys (the ds:DSAKeyValue and ds:RSAKeyValue elements, respectively), but public keys for other algorithms can also appear under a ds:KeyValue element.

Listing 32.17 Sample ds:KeyInfo/ds:KeyValue/ds:RSAKeyValue Element

 <KeyInfo>   <KeyValue xmlns="http://www.w3.org/2000/09/xmldsig#">     <RSAKeyValue>       <Modulus>qpkTNcNBXONxOCW+WPlNFeniABN8tkJYa2Y2IhcHfY3Qy3v01SeEWe         CRYYPcli24CKml1DU1dEE/jqNWF/8eypJakyztz1xFSrNp+12o5KsmCWmLzcc         940Fcb9I1eDffUm++GM0+FHARDEA9DZzFoJTLblyGd9XQS0rb4AVvnGc=       </Modulus>       <Exponent>AQAB</Exponent>     </RSAKeyValue>   </KeyValue> </KeyInfo> 

Listing 32.18 Sample ds:KeyInfo/ds:KeyValue/ds:DSAKeyValue Element

 <KeyInfo>   <KeyValue xmlns="http://www.w3.org/2000/09/xmldsig#">     <DSAKeyValue>       <P>3vd/2Pj3yZbWjgO1PLh2ebVIem0nwjPYUcq+1qbDBz42xa5KEug6         wIwVXUe+It3c1i1yt5uLZmdTFiYwI8v8QVGiG9+MH1hOVH3vmArcwEuHy         SG/BmEYZD2Iivsi3iabzKI82C7RgIkSn9dMeQyDAHEkfYqNXy/aDldgEkTDvHs=       </P>       <Q>7djIzh61c7hJ2dfDVyGy47Zrbn0=</Q>       <G>zpbWQ7ZHqb59WobUgTzXarfH0jxBw6ZdqFbGBGnHePXUYLLBSZADuZGzSf9cZnx2Pr         n8unzcSVHi4V1VWpl0c8Y6cyN6zbPlixHBfhfEB2iBq5rE5s24KHUQJ4QyelTJUm1frdpy         OPC5qGrlUWCONTPS6X6u4LH6zNY1fyX8mT0=       </G>       <Y>uFFFYABM7c4XQ6qjxtFYihGy+y8X6aplcTA6F0pc2iQssm99AKQ1ceody+9uZ1t         BaItsMkGT2xqTZGMNAccb8BQ4a9emRwqvSOlufac40CPcIbuNtkLpnrU2Nr2kL1dO         Cw6jYhoq9TWHVW7/nwceyR/MRRDakM7u6ZMtQqhcSpY=       </Y>       <J>7/v6mMmxG6/TJuzKu1ue0Iiz/KXzdfbQrlKFxedUJtqRJ/xobwCITelA/yIB         Kc5pqURCkeyx7jlBZq6bx97qqW3cdi9XgwcOwB+ThnE7G4F5Dz2KLEDicRjPDLr         /Wmyw4TKbjGFBuwd42PWC       </J>       <Seed>6cyvB3e5AUAZ9dNQVxF8acDQeD0=</Seed>       <PgenCounter>Eg==</PgenCounter>     </DSAKeyValue>   </KeyValue> </KeyInfo> 

NOTE

Note that the .NET Framework uses the same XML format as the ds:RSAKeyValue and ds:DSAKeyValue structures for representing RSA and DSA public keys. For example, calling the ToXmlString(false) method on an RSA key in the .NET Framework will produce a string serialization of the appropriate ds:RSAKeyValue structure. See the "Using Asymmetric Algorithms" section in Chapter 30 for more details on the use of the FromXmlString and ToXmlString methods on AsymmetricAlgorithm objects to import and export public keys in ds:KeyValue -compatible formats.

XMLDSIG defines two elements to support indirect pointers to key materialthe ds:KeyName and ds:RetrievalMethod elements. The ds:KeyName child element of ds:KeyInfo is intended to communicate a key identifier to the application verifying the digital signature. The content of a ds:KeyName element is always just a string, and the interpretation of that string is left unspecified by XMLDSIG and must be determined by application context. Typically, ds:KeyInfo is used as part of a series of communications between two parties where public keys were exchanged initially and then simply referenced by name in later signed messages. The following is an example use of ds:KeyName within ds:KeyInfo :

 <KeyInfo>   <KeyName>Alice's public key created on 9/26/2001</KeyName> </KeyInfo> 

The ds:RetrievalMethod child element of ds:KeyInfo allows a signature constructor to include a reference to a ds:KeyInfo element stored elsewhere. The schema for ds:RetrievalMethod is shown in Listing 32.19. The schema is very similar to the schema for the ds:Reference element; in fact, ds:RetrievalMethod elements are processed using the same Reference Processing Model described earlier, except that a ds:RetrievalMethod is not a hash reference and thus does not contain hash algorithm and value sub-elements like ds:DigestMethod and ds:DigestValue . (Also, the URI attribute must be present in a ds:RetrievalMethod .)

Listing 32.19 XML Schema for the ds:RetrievalMethod Element

 <element name="RetrievalMethod" type="ds:RetrievalMethodType"/> <complexType name="RetrievalMethodType">   <sequence>     <element ref="ds:Transforms" minOccurs="0"/>   </sequence>   <attribute name="URI" type="anyURI"/>   <attribute name="Type" type="anyURI" use="optional"/> </complexType> 

There are three defined elements in the XMLDSIG standard for carrying trust management information related to signature keys within a ds:KeyInfo elementthe ds:X509Data , ds:PGPData , and ds:SPKIData elements. These three elements correspond to the three separate trust models that have been standardized by the IETFX.509v3 certificates (standardized in the PKIX Working Group within the IETF), PGP messages (based on the "Open Specification for Pretty Good Privacy" developed by the OpenPGP Working Group), and Simple Public Key Infrastructure certificates (based on the work of the SPKI Working Group ), respectively. By far, the most complex of the three elements is the ds:X509Data element; it is also the only one of the three that is natively supported in the initial release of the .NET Framework. The ds:X509Data element can contain X.509v3 certificates, identifiers for certificates, and even entire certificate revocation lists (CRLs). The schema for the ds:X509Data element is shown in Listing 32.20, and a summary of the possible child elements of ds:X509Data is provided in Table 32.6. Notice that the ds:X509Data element is extensible; other element types can be included in an instance of ds:X509Data , but only the element types listed in Table 32.6 are defined by the standard.

Listing 32.20 XML Schema for the ds:X509Data Element

 <element name="X509Data" type="ds:X509DataType"/> <complexType name="X509DataType">   <sequence maxOccurs="unbounded">     <choice>       <element name="X509IssuerSerial" type="ds:X509IssuerSerialType"/>       <element name="X509SKI" type="base64Binary"/>       <element name="X509SubjectName" type="string"/>       <element name="X509Certificate" type="base64Binary"/>       <element name="X509CRL" type="base64Binary"/>       <any namespace="##other" processContents="lax"/>     </choice>   </sequence> </complexType> <complexType name="X509IssuerSerialType">   <sequence>     <element name="X509IssuerName" type="string"/>     <element name="X509SerialNumber" type="integer"/>   </sequence> </complexType> 

Table 32.6. Children of the ds:X509Data Element

Element/Attribute Na me	Contents	Mandatory or Optional	Number Appearing
X509IssuerSerial (element)	An issuer name/serial number pair, which is one way to reference an X.509v3 certificate	Optional	Any number
X509SKI (element)	An X.509v3 Subject Key Identifier, which is an extension that may appear in a certificate	Optional	Any number
X509SubjectName (element)	An X.509v3 subject distinguished name (the subject name bound to the public key in a certificate)	Optional	Any number
X509Certificate (element)	A Base64-encoded X.509v3 certificate	Optional	Any number
X509CRL (element)	A Base64-encoded certificate revocation list (CRL)	Optional	Any number

The first three elements in Table 32.6- ds:X509IssuerSerial , ds:X509SKI , and ds:X509SubjectName all represent different mechanisms for referencing a certificate or set of certificates. The ds:X509IssuerSerial element always names exactly one certificate; it contains a simple structure holding a pair consisting of an X.509v3 issuer distinguished name (a string) and a serial number. When a certificate issue creates a new certificate, it is required to generate a new, unique serial number for that certificate, so an issuer name/serial number pair is a unique identifier for a single certificate. The ds:X509SubjectName element contains a string value that is a subject distinguished name of one or more certificates (because multiple certificates can be issued to the same subject entity). The ds:X509SKI element contains the Base64 encoding of the subject key identifier (SKI) extension in a certificate, which is usually derived from the subject public key through some mathematical operation (such as hashing the public key value). Because multiple certificates can be issued for the same subject public key, there can be multiple certificates that share the same ds:X509SKI extension.

The XMLDSIG standard imposes three restrictions on the types of certificates that can be referenced by ds:X509IssuerSerial , ds:X509SKI , and ds:X509SubjectName and how that data must be organized within a ds:KeyInfo element. First, all references to certificates within these three types of elements must be to certificates that contain the signature validation key as its subject public key. Second, all instances of these three elements that refer to the same single certificate must be grouped together within a single ds:X509Data element. Third, all instances of these three elements that refer to the same subject public key but different certificates must appear within the same ds:KeyInfo but can appear within different ds:X509Data elements inside that ds:KeyInfo element.

It is also possible to directly encode X509v3 certificates in a signature by using the ds:X509Certificate child of ds:X509Data . All certificates appearing within a ds:X509Data element must either contain the validation key as its subject public key or be part of a chain of certificates whose end-entity certificate has the validation key as its subject. Thus, it is possible to include an entire X.509v3 certificate chain within a single ds:X509Data element by simply using multiple ds:X509Certificate elements.

NOTE

The .NET Framework does not contain explicit support for the other types of KeyInfo elements that are defined in the XMLDSIG standard: ds:PGPData , ds:SPKIData , and ds:MgmtData . When encountered in an XMLDSIG ds:Signature element, these three types of KeyInfo will be represented in the .NET Framework as KeyInfoNode objects. The Value property of a KeyInfoNode contains the entire XML content of the element that was not explicitly recognized.

This concludes our tour of the ds:Signature element and the sub-elements that can appear within it. In the next section, we discuss the objects and methods included in the .NET Framework for creating and validating XMLDSIG signatures.

for RuBoard