XML Signature

The XML signature specification forms the basis for securely exchanging XML documents and conducting secure business transactions. The goal of XML signature is to ensure data integrity, message authentication, and non-repudiation of services. It is an evolving standard for creating and representing digital signatures using XML syntax and processing for XML-based data communication. XML signature evolved from the joint effort by the W3C and IETF working groups. To find out the current status of the XML signature specification from the W3C working group activities, refer to the W3C Web site at www.w3.org/Signature.

Motivation of XML Signature

The process of applying digital signature is analogous to a physical handwriting signature. It ensures that a message recipient can verify that the signed message from a sender originated from the sender and has not been altered or tampered with during transit or storage. In XML-based data exchange and business transactions, applying digital signatures signs the complete message or XML document. This removes the flexibility of signing specific parts and applying changes to a document that has multiple recipients. In a business scenario involving multiple parties, applying a digital signature to a complete document restricts the document to one party, and adding any further modifications by that party invalidates the originally signed document.

To meet the above requirements, XML-based digital signature mechanisms are designed to facilitate data integrity in secure XML communication and to provide support for involving multiple parties. In a nutshell, XML signature defines the syntax and processing rules that provide the flexibility to add multiple signatures to the different fragments of an XML document. Signatures intended for multiple parties associated with the content of the document can thus be preserved.

The Anatomy of XML Signature

XML signature allows signing any sort of digital content or data objects, such as XML or HTML documents, binary data, and images. The signatures are applied to the content via an indirection. The content requiring signing is digested using a message digest algorithm (such as DSA-SHA1 or RSA-SHA1), and the resulting hash value is placed in an XML element. The XML element is digested and cryptographically signed. The signed form of the XML element represents the XML signature.

Representing XML Signatures

According to the XML signature specification, based on the data and associated XML signature, there are three ways to represent XML signatures.

Enveloped signatures: The XML signature is embedded within the original XML content, where the XML signature is represented.

Example 6-1. Enveloped signature

<xmldocument no="xd001">      <business-element/>      <Signature>           ...           <Reference URI="xd001"/>           ...      </Signature> </xmldocument>

Enveloping signatures: The original XML content is embedded within the XML signature, where the XML content is represented as a child element within an <object> or identified as a URI <Reference> in the parent XML signature.

Example 6-2. Enveloping signature
```
<Signature>      ...      <Reference URI = "xyz"/>      ...      <Object >           <xmldocument>                <business-element/>           </xmldocument>      </Object> </Signature> 
```
Detached signatures: The XML content resides external to the signature and is identified via a URI or transform. It applies to separate data objects external to the signature document and for the data objects residing within the original XML document as sibling elements.

Example 6-3. Detached signature
```
<xmldocument>    <Signature>        ...          <Reference URI=    "http://www.coresecuritypatterns.com/xmldocument/"/>           ...    </Signature>      <business-elemt/> </xmldocument> 
```

Let's take a closer look at how to represent an XML signature, its structural elements, and its features.

Representation of XML Signature Structure and Elements

XML digital signatures are represented using XML elements. They are identified by a <Signature> element, where the original data is digested, signed, and embedded within the data structure. Example 6-4 is the structure of an XML signature represented by <Signature ?> as its root element. "?" in the element denotes zero or one occurrence, "+" denotes one or more occurrences, and "*" denotes zero or more occurrences).

Example 6-4. XML Signaturecore structure and elements

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

<Signature>

The <Signature> element is a parent element that identifies a complete XML signature within a given context. It contains the sequence of child elements: <SignedInfo>, <SignatureValue>, <KeyInfo>, and <Object>. Also, an optional Id attribute can be applied to the <Signature> element as an identifier. This is useful in the case of multiple <Signature> instances within a single context.

<SignatureValue>

The <SignatureValue> element contains the actual value of the digital signature, which is the digested value of <SignedInfo> element. The value is base64 encoded.

<SignedInfo>

The <SignedInfo> element contains the original data that is actually signed. The contents of this element also include a sequence of elements: <CanonicalizationMethod>, <SignatureMethod>, and one or more <Reference> elements. The <CanonicalizationMethod> and <SignatureMethod> elements describe the type of canonicalization and signature algorithms used in the generation of a <SignatureValue>. The <SignatureValue> element contains the digital signature value that is the digest of <SignedInfo> element. The <Reference> element defines the actual data using a data stream that is eventually hashed and transformed. The actual data stream is referenced by a URI.

<CanonicalizationMethod>

The <CanonicalizationMethod> element defines the representation of the physical structure by specifying the canonicalization algorithm applied to the <SignedInfo> element. To support security and interoperability, the XML signature specification recommends the use of XML-based canonicalization algorithms instead of text-based canonicalization algorithms (such as CRLF and charset normalization). It also mandates that the <SignedInfo> element be presented to the XML canonicalization methods as an XPath node set definition, mentioning the <SignedInfo>, its descendants, attributes, and namespace nodes of the <SignedInfo> element.

<SignatureMethod>

The <SignatureMethod> element specifies the cryptographic algorithm used for generating the signature. The algorithm also identifies other cryptographic functions involved in the signature operation, such as hash, public-key algorithms, MACs, and padding.

<Reference>

The <Reference> element contains the digest value of the data object. It optionally carries identifiers (URI) to the original data objects, including the list of transforms specifying transformations applied prior to computing the digest.

<Transforms>

The optional <Transforms> element contains an ordered list of <Transform> elements. It defines the steps required for obtaining the original data object that was digested. Each <Transform> serves as a transformation input to the next <Transform>. The input to the first <Transform> is the result of dereferencing the URI attribute of the <Reference> element. The output of the last <Transform> is the input for the <DigestMethod> algorithm.

<DigestMethod>

The <DigestMethod> contains the digest algorithm to be applied to the signed object. URIs identify the algorithms.

<DigestValue>

The <DigestValue> element contains the base64-encoded value of the digest.

<KeyInfo>

The optional <KeyInfo> element provides the ability to verify the signature using the packaged verification key. It contains keys, key names, certificates, and related information. This element also enables the integration of trust semantics within an application that utilizes XML signatures. The <KeyInfo> consists of a child element named <KeyValue>. The <KeyValue> element carries a raw RSA or DSA public key with child elements <RSAKeyValue> and <DSAKeyValue>, respectively. All information represented in the <KeyValue> element is represented in base64 encoding.

<Object>

The optional <Object> element is used mostly in enveloping signatures where the data object is part of the <Signature> element. The digest of the data object in this case would contain the <object> element along with its associated data objects. The <Object> elements also include optional MIME type, ID, and encoding attributes.

<Manifest>

The optional <Manifest> element is quite similar to the <SignedInfo> element in that it contains a list of <Reference> elements. In the case of the <Manifest> element, the processing of the <Reference> element is defined by the application.

<SignatureProperties>

The optional <SignatureProperties> element can contain additional information about the signature. This may include date, timestamp, serial number of cryptographic hardware, and other application-specific attributes.

Algorithms

In XML signature, algorithms are associated with an identifier attribute carrying a URI for <DigestMethod>, <SignatureMethod>, <CanonicalizationMethod>, and <Transform> elements. Most algorithms use implicit parameters such as key information for <SignatureMethod>. Some algorithms use explicit parameters with descriptive element names specific to the algorithm and within the XML signature or algorithm-specific namespace.

Let's take a brief look at the algorithms and their URIs discussed in the XML signature specification.

Signature Algorithms

Signature algorithms are used for creating the XML signature for given data objects. The algorithms used are a combination of message digests and public-key cryptography algorithms. The XML signature specification defines two signature algorithms, DSA and PKCS1 (RSA-SHA1), and their associated URIs. Both DSA and PKCS1 (RSA-SHA1) take no explicit parameters.

DSA: DSA-SHA1, also referred to as DSA algorithm, is specified with a URI identifier, http://www.w3.org/2000/09/xmldsig#dsa-sha1. For example, DSA is represented in <SignatureMethod> element as shown in Example 6-5.

Example 6-5. Signature method using DSA-SHA1
```
<SignatureMethod>       Algorithm=http://www.w3.org/2000/09/xmldsig#dsa-sha1   </SignatureMethod> 
```
The output of the DSA algorithm consists of a pair of integers referred to as an r,s pair, and the signature value contains the base64-encoded value of the concatenation of two-octet streams of the octet-encoding of the r,s pair. The integer-to-octet stream conversion is done according to RFC2437 (PKCS1) specifications. The resulting <SignatureValue> element of the DSA algorithm will look as shown in Example 6-6.

Example 6-6. Signature value output using the DSA algorithm
```
<SignatureValue>        BB4jRfH1bfJFj0JtFVtLotttzYyA==AyAorytrtur   </SignatureValue> 
```
RSA-SHA1: The RSA-SHA1, also referred to as PKCS1, algorithm is specified with a URI identifier, http://www.w3.org/2000/09/xmldsig#rsa-sha1. For example, RSA is represented in <SignatureMethod> element as shown in Example 6-7.

Example 6-7. Signature method using RSA-SHA1
```
 <SignatureMethod>            Algorithm=http://www.w3.org/2000/09/xmldsig#rsa-sha1          </SignatureMethod> 
```

The <SignatureValue> element of the RSA-SHA1 is represented using base64 encoding, and the octet string is computed according to RFC 2437 [PKCS1, section 8.1.1: Signature generation for the RSASSA-PKCS1-v1_5 signature scheme].

Canonicalization Algorithms

Two equivalent XML documents can possibly differ on representations such as physical structure, attribute ordering, character encoding, or insignificant placing of white space. In an XML signature, it is extremely important to prove the equivalence of XML documents while representing digital signatures, checksums, identifiers, version control, and conformance. The XML Canonicalization algorithms allow generating the canonical form of an XML document, which can be correctly compared, byte-by-byte, to canonical forms of other documents. In XML signature, the XML documents need to be canonicalized before they are signed to ensure the representation is logically byte-by-byte identical with equivalent XML documents. If it is not canonicalized, the validation of an XML signature will potentially fail due to any difference in its physical structure or its representation. The XML signature specification defines two canonicalization algorithms:

Canonical XML (omits comments)
Identifier: http://www.w3.org/TR/2001/REC-xml-c14n-20010315
Canonical XML with comments
Identifier: http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments

For example, the representation of the <CanonicalizationMethod> element in the signature will look as shown in Example 6-8.

Example 6-8. Canonicalization method using a canonicalization algorithm

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

Transform Algorithms

Applying transformations is mostly used to support canonicalization and to make sure the actual data object is processed, filtered, and represented in the right fashion before it is signed. Using transform algorithms, the XML signature can take an ordered list of transformations for a data object as required. Transform algorithms can be applied to the data objects referred to in the <Reference> element or the output of a previous <Transform> element. The XML signature specification defines three transform algorithms:

XSLT Transform
Identifier: http://www.w3.org/TR/1999/REC-xslt-19991116
Xpath Transform
Identifier: http://www.w3.org/TR/1999/REC-xpath-19991116
Enveloped Signature
Identifier: http://www.w3.org/2000/09/xmldsig#enveloped-signature

For example, the representation of <Transforms> element in the XML signature will look as shown in Example 6-9.

Example 6-9. Representing Transformation algorithms in XML signature

    <Transforms>      <Transform       Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">      </Transform>     </Transforms>

XML Signature Examples

Let's consider an example scenario of a financial institution that hosts a Web-services-based solution for delivering banking services for its business customers. The business customer uses a service requester application that sends and receives messages from the service provider. Based on requests, the service provider responds with an account statement for the customer that includes critical information, such as account balances, credit card transactions, and other financial data. Using XML signature, the services provider guarantees that all Web-services-based transactions transmitted to and from the service requester remain authentic and have not been altered or tampered with during transit.

Let's use the XML document shown in Example 6-10, a financial statement of a business customer for applying XML signature and its types.

Example 6-10. XML Document representing a financial statement

<BusinessAccountSummary >  <Customer >   <BusinessName>ABZ Company</BusinessName>   <Address>1 ABZ Drive, Newton, CA</Address>    <PrimaryContact>R Nagappan</PrimaryContact>   <BusinessAccount >      <AccountBalance>950000.00</AccountBalance>    </BusinessAccountNo>    <CreditCard no="1233-3456-4567">      <CreditBalance>45000.00</CreditBalance>    </CreditCard>     <CreditCard no="4230-3456-9877">      <CreditBalance>6000.00</CreditBalance>    </CreditCard>       </Customer> <BusinessAccountSummary>

Enveloped Signature

In the enveloped signature, the XML signature resides within the signed document. Example 6-11 represents the enveloped signature, where the XML signature is embedded as part of the signed XML document.

Example 6-11. Signed XML document using enveloped signature

<BusinessAccountSummary date="01/01/2004" docEmphStrong">ABCD54321">   <Customer >     <BusinessName>ABZ Company</BusinessName>      <Address>1 ABZ Drive, Newton, CA</Address>       <PrimaryContact>R Nagappan</PrimaryContact>      <BusinessAccount >         <AccountBalance>950000.00</AccountBalance>       </BusinessAccountNo>       <CreditCard no="1233-3456-4567">         <CreditBalance>45000.00</CreditBalance>       </CreditCard>       <CreditCard no="4230-3456-9877">         <CreditBalance>6000.00</CreditBalance>       </CreditCard>   </Customer>     <Signature                xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>   <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>   <SignatureMethod Algorithm=http://www.w3.org/2000/09/xmldsig#dsa-sha1 />   <Reference URI="#ABCD54321">     <Transforms>     <Transform    Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature">   </Transform>   </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />     <DigestValue>jav7lwx3rvLPO0vKVu8nk===</DigestValue>   </Reference> </SignedInfo>    <SignatureValue>MC0E~LE=</SignatureValue>  <KeyInfo>    <X509Data> <X509SubjectName>CN=RRN,O=CS,ST=BOSTON,C=MA</X509SubjectName>    <X509Certificate>      MIID5jCCA0+gA...lYZ==    </X509Certificate>   </X509Data>   </KeyInfo> </Signature> </BusinessAccountSummary>

In Example 6-11, the data object signed is the <BusinessAccountSummary> element that is identified by the URI attribute of the <Reference> element. As the XML signature is added, it changes the original document with the embedded <Signature> element. To verify the signature, it also becomes necessary to compare the original document without the signature. The XML digital signature recommendation defines an enveloped signature transformation algorithm for removing the <Signature> from the original document. The enveloped signature transform algorithm is defined in the specification with the URI identifier: http://www.w3.org/2000/09/xmldsig#enveloped-signature.

Enveloping Signature

In the enveloping signature, the XML signature encloses the signed XML document as its child element. Example 6-12 represents the enveloping signature, where the XML document is contained with the <Object> element within the XML signature.

Example 6-12. Signed XML document using enveloping signature

<Signature                xmlns="http://www.w3.org/2000/09/xmldsig#">   <SignedInfo>   <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>   <SignatureMethod Algorithm=http://www.w3.org/2000/09/xmldsig#dsa-sha1 />   <Reference URI="#ABCD54321">     <Transforms>     <Transform   Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">   </Transform>     </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /> <DigestValue>mnmasdvlwx3rvLP0vKVu8nk===</DigestValue> </Reference> </SignedInfo> <SignatureValue>LMC0E~LE=</SignatureValue> <KeyInfo> <X509Data> <X509SubjectName>CN=RRN,O=CS,ST=BOSTON,C=MA</X509SubjectName> <X509Certificate>   MIID5jCCA0+gA...lYZ== </X509Certificate> </X509Data> </KeyInfo> <Object docEmphStrong">ABCD54321"> <BusinessAccountSummary >  <Customer >   <BusinessName>ABZ Company</BusinessName>   <Address>1 ABZ Drive, Newton, CA</Address>    <PrimaryContact>R Nagappan</PrimaryContact>   <BusinessAccount >      <AccountBalance>950000.00</AccountBalance>    </BusinessAccountNo>    <CreditCard no="1233-3456-4567">      <CreditBalance>45000.00</CreditBalance>    </CreditCard>     <CreditCard no="4230-3456-9877">      <CreditBalance>6000.00</CreditBalance>    </CreditCard>       </Customer> <BusinessAccountSummary>  <Object> </Signature>

Detached Signature

In the detached signature, both the XML document and XML signature reside independentlythey are detached with external references or within the document as sibling elements. The URI attribute of the <Reference> element holds the identifier of the external reference, pointing to an external resource or pointing to an element id that is a sibling XML fragment residing as part of the same document. Example 6-13 represents a detached signature, where the XML signature <Signature> and the signed XML document <BusinessAccountSummary> are siblings of the main document.

Example 6-13. Signed XML document using detached signature

<Document> <BusinessAccountSummary date="01/01/2004" docEmphStrong">ABCD54321">   <Customer >     <BusinessName>ABZ Company</BusinessName>     <Address>1 ABZ Drive, Newton, CA</Address> <PrimaryContact>R Nagappan</PrimaryContact>     <BusinessAccount >       <AccountBalance>950000.00</AccountBalance>     </BusinessAccountNo>     <CreditCard no="1233-3456-4567">       <CreditBalance>45000.00</CreditBalance>      </CreditCard>      <CreditCard no="4230-3456-9877">        <CreditBalance>6000.00</CreditBalance>      </CreditCard>    </Customer>  </BusinessAccountSummary>    <Signature                xmlns="http://www.w3.org/2000/09/xmldsig#">    <SignedInfo>    <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>   <SignatureMethod      Algorithm=http://www.w3.org/2000/09/xmldsig#dsa-sha1 />      <Reference URI="#ABCD54321">     <Transforms>       <Transform     Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">    </Transform>   </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />    <DigestValue>jav7lwx3rvLPO0vKVu8nk===</DigestValue>     </Reference>   </SignedInfo>   <SignatureValue>MC0E~LE=</SignatureValue>   <KeyInfo>  <X509Data> <X509SubjectName>CN=RRN,O=CS,ST=BOSTON,C=MA</X509SubjectName> <X509Certificate>     MIID5jCCA0+gA...lYZ==    </X509Certificate>   </X509Data>   </KeyInfo>   </Signature> </Document>

In Example 6-13, the data object signed is the <BusinessAccountSummary>, and it is identified by the URI attribute of the <Reference> element.

Creating an XML Signature

The steps for creating an XML signature in compliance with the specification are as follows:

1.	Identify the XML document, its parts of data objects, or other content resources that need to be signed. These data items are identified as a referenced resource through a URI. For example, a reference to an XML document with an HTTP URL will look like this: http://www.robmebank.com/statements/account.xml.
2.	Apply transformations to the identified data object, specifying any encoding rules, canonicalization instructions, and XSLT transformations that need to be applied to the signed data. The <Transform> element identifies the transform algorithms to be applied.
3.	After transformation, calculate the digest by applying message digest algorithms for each referenced URI resource identified by the <Reference> element. The <DigestMethod> element identifies the applied algorithm and the <DigestValue> element holds the calculated digest.
4.	Construct a <SignedInfo> element that collects all <Reference> elements, including the <DigestMethod> and <DigestValue>.
5.	Canonicalize the <SignedInfo> element using the canonicalization algorithm specified through the <CananonicalizationMethod> element. If canonicalization is not applied, the validation of an XML signature may fail due to possible differences of the XML structure or its representation.
6.	Calculate the digest of the <SignedInfo> element and sign it by applying the signature algorithm identified by the <SignatureMethod> element. The resulting signed value is represented under the <SignatureValue> element.
7.	It is optional to include the <KeyInfo>, such as X.509 certificates and whether a public key is required for validating the signature.
8.	Finally, construct the <Signature> element, including the <SignedInfo>, <SignatureValue>, and the <KeyInfo> that represent an XML signature of the given XML document or data objects.

Verifying and Validating an XML Signature

The following two steps are applied for verifying and validating an XML signature.

Verify and validate the digests: Recalculate the digests represented within the <Reference> elements. This includes applying transformations specified in the <Transforms> element and digesting the resulting value by applying the algorithm specified in the <DigestMethod> element. Compare the digested value against the value specified in the <DigestValue> element.

Verify and validate the signature: Recalculate the signature within the <SignedInfo> element using the key information included in the <KeyInfo> element or obtained from external sources. It is important to apply the canonicalized method and use the canonical form of the <SignatureMethod>, because the specified URI may be changed by the canonicalization of the <SignedInfo> element. Compare the signature value against the specified value in the <SignatureValue> element.