Getting Started with XML Security

Key Concepts

The following concepts are central to understanding XML digital signatures:

1. A signature is only valid if the signed content has not changed. This content is represented using a short, fixed-length digest, designed to change if the content changes. Thus a signature will only be valid if a digest used to create a signature is the same as a digest used to verify it later. A verifier can create a digest to see if it is the same.
2. An XML <Signature> element is an XML structure that contains a cryptographic signature value in a <SignatureValue> element as well as an XML structure that has been signed, the <SignedInfo> structure. This means that the contents of the <SignedInfo> structure should not change for the signature to be valid.
3. The signer creates a <Reference> for each item to be included in a signature. Each <Reference> includes a digest of the item and a unique identifier (URI) for the item. It also identifies how to recreate the digest, specifying the algorithm and other necessary information. Each Reference is part of the <SignedInfo> structure.
4. To verify a signature, a recipient must validate each <Reference> by independently generating the same digest for the item. The verifier may use the URI to aid locating the item, and the algorithm information to know how to generate the digest. If the item has not changed, the digest should be the same.
5. A reference may refer to anything using a URI, including non-XML content such as image and text files. It is not required to obtain the item using the URI, but it is often useful. A special form of URI may be used to refer to XML elements within the same document as the signature, allowing signatures to be transferred along with XML content to be signed.
6. A <Reference> may specify one or more transforms to be applied to an item before creating the digest. One use is to sign parts of an XML document that are known not to change - such as boilerplate for example. This may be done by defining transform to extract the portion of the document to be signed, using standard XML XPath expressions for example.
7. Digest algorithms require content to be exactly the same to produce the same digest. Even a minor change that does not change the meaning, such as adding an extra space, will invalidate the digest. XML, on the other hand, allows some variation in the syntax of the XML text without changing the document. In other words, two XML documents may be considered the same even if they do not have the exact same text. For example, one XML document may use single quotes for an attribute and another double quotes. These are the same to an XML parser, but very different to a digest algorithm. There is an entire list of such potential issues for digests. To get around this problem, a Canonicalization transform may be used, one that converts any XML document to a form using a single set of rules, such as always using a certain type of quote for attributes.

Examples

Once created, an XML Digital Signature may be stored separately from the signed content (a detached signature) or embedded within the XML content that was signed (enveloped signature). In fact, signed content may also be placed within a signature itself (enveloping signature). To continue with the earlier PatientRecord example, suppose that the entire PatientRecord is to be signed by the Doctors office, and the signature is to be maintained as part of the PatientRecord. This would produce the following result, showing the layout of an XML Signature:

<PatientRecord xmlns="http://www.medical.org/">    
 <Name>John Doe</Name>    
 <account id="acct">123456</Account>    
 <Visit date="10pm March 10, 2002">    
   <Diagnosis>Broken second metacarpal</Diagnosis>    
   <lab:Diagnosis>    
     <lab:Xray>xhzhez</lab:Xray>    
   </lab:Diagnosis>    
 </Visit>    
 <Signature xmlns='http://www.w3.org/2000/09/xmldsig#'>    
       
   <!-- the SignedInfo element and all it contains    
        is what is signed -->    
   <SignedInfo>    
         
     <!-- Canonicalization is used to ensure    
          that XML is handled consistently    
          by different XML processors    
          in light of white space and other    
          variations. -->    
     <CanonicalizationMethod algorithm="URI for algorithm" />    
         
     <!-- the SignatureMethod is protected    
          by the signature, avoiding substitution    
          attacks and defines how the signature    
          is created  -->    
     <SignatureMethod    
Algorithm="http://www.w3.org/2000/07/xmldsig#rsa-sha1" />    
         
     <!-- each item to be signed, XML document,    
          portion of XML document or arbitrary    
          content is represented using a    
          Reference. Each Reference contains    
          a digest of the item, a URI to    
          refer to the item, and possibly    
          transforms to apply to the item    
          before creating the digest  -->    
     <Reference URI="">    
       <Transforms    
Algorithm="http://www.w3.org/TR/2000/WD-xml-c14n-20000710" />    
       <DigestMethod    
Algorithm="http://www.w3.org/2000/07/xmldsig#sha1" />    
       <DigestValue>    
         Short, fixed-length "fingerprint" of referenced item    
       </DigestValue>    
     </Reference>    
   </SignedInfo>    
   <SignatureValue>    
     encoded output of signature algorithm    
   </SignatureValue>    
       
   <!-- Optional KeyInfo used to convey key    
        information needed to verify    
        signature -->    
   <KeyInfo>    
     <KeyName>Sally Smith's Integrity Key</KeyName>    
   </KeyInfo>    
       
   <!-- optional Object to allow additional    
        information to be associated with    
        signature, such as meta information    
        for example (time and purpose of    
        signing) -->    
   <Object>    
     <SignatureProperties>    
       <p:Purpose xmlns:p="http://www.myexample.com/schemas">    
         Integrity    
       </p:Purpose>    
     </SignatureProperties>    
   </Object>    
 </Signature>    
</PatientRecord>
Example 4 - Detailed XML Signature Example

Note that there is a single reference with URI "", meaning "this document". If only the <Account> element were to be signed, it could be referenced using the id attribute value, as follows: <Reference URI="#acct">. If there was no id attribute (perhaps signing wasn't anticipated), an XPath expression could be used, producing the following <Reference>:

<Reference URI="">    
   <Transforms>    
       <Transform    
Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">    
           <XPath>    
               /PatientRecord/account    
           </XPath>    
       </Transform>    
       <Transform    
Algorithm="http://www.w3.org/TR/2000/WD-xml-c14n-20000710" />    
   </Transforms>    
   <DigestMethod    
Algorithm="http://www.w3.org/2000/07/xmldsig#sha1" />    
   <DigestValue> kjsdf </DigestValue>    
</Reference>
Example 5 - Reference Transform Using XPath