While SignedInfo can be considered the meat of an XML Signature, in turn the Reference element can be considered the meat of SignedInfo.

---

Tip - When you are reading an XML Signature, which can often be remarkably long, the first place you usually look to get a feel for what is being signed is the Reference element(s). The URI attribute points to what is being signed.

---

As review, Listing 4.17 is the Reference XML fragment pulled from the Signature shorthand schema shown earlier.

Listing 4.17 XML Shorthand Schema for the <Reference> Element.

 (<Reference URI? >
  (<Transforms>)?
 <DigestMethod>
 <DigestValue>
 </Reference>)+

The objective of the Reference element is to point to a resource to be included in the overall XML Signature. There must be at least one Reference, which stands to reason because you have to be signing something. To say that this element points to the resource is actually oversimplifying because it also can contain Transform elements that manipulate the resource that is being pointed to prior to its being digested. Arguably, most of the power and complexity of XML Signatures come from the Reference element. That power comes from the power of the uniform resource identifier.

See the sidebar titled "The Powerful, Enigmatic, and Confusing Uniform Resource Indentifier (URI)" in Chapter 2 for more information about what a URI is and how to use it. In XML Signature, URIs can show up in a variety of ways; see the sidebar here titled "URI/URL Variants in XML Signature" for a review of the different ways a URI can show up as a Reference URI in an XML Signature.

---

URI/URL Variants in XML Signature - For XML Signature and most of the XML security standards, you need to understand URIs well. The locator aspect of URIs when referring to XML is quite a bit more involved than the equivalent HTML usage. Let's review the locator type URI options in XML Signature:

1. Refers to an external XML document. This is straightforward and might look like URI=http://www.mycompany.com/myDocument.xml.

2. Refers to the current XML document root. It is common, especially with enveloping references to specify the root of the document that contains the Signature element. This looks like URI="".

3. Uses the same document reference. If you are referring to an XML element in the same document, you can use a "same document reference," which looks like URI="#PurchaseOrder".

4. Uses external document "bare fragment." This is similar to a same document reference, except that it is to a portion of an external XML document. It looks something like URI="http://www.mycompany.com/myDocument.xml#PurchaseOrder".

5. Refers to a non-XML file (binary, text, and so on). This is similar to any URL you are already familiar with; it looks like URI="http://www.mycompany.com/myPicture.gif".

6. Uses an internal URI with an XPointer argument (this type is recommended but not required, so all toolkits might not support it). It looks like URI="#xpointer(/)", which refers to the root element. External URIs with XPointer arguments are not recommended.

Another fact to know about URIs is that they can be absolute or relative. An absolute URI is completely spelled out, including all parts of the URI, such as http://www.mycompany.com/ mySignatureExample. A relative URI contains a resource path and name that is meant to be resolved from the BaseURI. The BaseURI, if not made explicit, is the same directory as your current location. For example the relative URI myPicture.gif would look for myPicture.gif in the same directory where the XML document is located. Using relative URIs can provide the advantage of portability by allowing you to move a set of resources around without having to change references.

---

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.