This section provides four examples of XML digital signatures, starting with simple cases and working toward more complex cases. Two of the examples are protocol oriented, and two are form/paper oriented.
10.3.1 Simple Protocol Example
Assume you want to efficiently secure protocol messages between two parties. One technique would be to use efficient shared secret key message authentication, like that shown in Example 10-6. In this example, the Data element in a protocol message needs to be authenticated. Because we assume that it is an established connection for a simple protocol, the sender and receiver have already agreed on a key, and thus no KeyInfo is present.
Example 10-6 Simple protocol signature
[L01] <PDU> [L02] <Data>...</Data> [L03] <Signature> [L04] <SignedInfo> [L05] <CanonicalizationMethod [L06] Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> [L07] <SignatureMethod Algorithm= [L08] "http://www.w3.org/2001/04/xmldsig-more#hmac-md5"/> [L09] <Reference> [L10] <DigestMethod [L11] Algorithm="http://www.w3.org/2001/04/xmldsig-more#md5"/> [L12] <DigestValue>Zu0kJL/V1YVZWWdnZ7lfXw== </DigestValue> [L13] </Reference> [L14] </SignedInfo> [L15] <SignatureValue>w5smJq3//01VVUvd3d0BAQ== </SignatureValue> [L16] </Signature> [L17] </PDU>
[L02] The element that needs to be authenticated.
[L03] Beginning of the authenticating Signature element, which extends to L16.
[L04] Beginning of the element across which the SignatureMethod is actually applied and which is linked to the data by a digest.
[L05/06] How the SignedInfo is canonicalized when verifying the signature. Exclusive XML Canonicalization, as specified, is usually the appropriate algorithm for signatures.
[L07/08] The authentication algorithm. It is applied, using the shared secret key, to SignedInfo to produce the SignatureValue. It includes performing the MD5 hash algorithm on the results of applying the CanonicalizationMethod to SignedInfo.
[L09] This Signature element has only one Reference to authenticated information. Because of the simple nature of this protocol and previous agreement between the parties, no "URI=" attribute is needed. The receiver knows that the Data element is being authenticated.
[L10/11] The algorithm applied to the data to be authenticated. Because the data consist of parsed XML (the Data element), the data will automatically be subject to Canonical XML, producing a standardized serialization to feed to the MD5 hash algorithm.
[L12] The hash value output of MD5 in base-64.
[L15] The authentication value output of the HMAC-MD5 in base-64.
10.3.2 Simple Document Example
Example 10-7 shows a simple case of a more document-oriented signature.
Example 10-7 Simple document signature
[L20] <Document...> [L21] <Field1 ...> [L22] ...myriad content... [L23] </Field1> [L24] <Field2>...<subF2>...<subsubF2 a="b"/>...</subF2>... </Field2> [L25] <Signature> [L26] <SignedInfo> [L27] <CanonicalizationMethod Algorithm= "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/> [L28] <SignatureMethod Algorithm= "http://www.w3.org/2001/04/xmldsig-more#rsa-sha1"/> [L29] <Reference URI=""> [L30] <Transforms><Transform Algorithm= "http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> </Transforms> [L31] <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> [L32] <DigestValue>Szbv70MrKxJjY6bx8daFhQjV1fk= </DigestValue> [L33] </Reference> [L34] </SignedInfo> [L35] <SignatureValue> yFw+PrsMDBmvr0kaGme1tVwQEOLa2qiIiCZycoFDQ+jQ0F 58fHf4+BGAgA8mJvRLS067u/Sbm8NDQ18GBsoPDw= </SignatureValue> [L36] <KeyInfo><X509Data><X509Certificate> zPrj46nf38G5ufIEBG7w8G5dXVaEhNBZWaqMjJiwsL/Dwz UhIdOlpVYTE1bPz/rj4y/s7GNtbdaHh9t3dzxRUfqHh6Qj ... </X509Certificate></X509Data></KeyInfo> [L37] </Signature> [L38] </Document>
[L20] This document has an embedded signature that covers all of the document except for the signature itself.
[L21/24] Assorted complex document content.
[L25] The signature, which extends to L37.
[L26] The actual element SignedInfo to which the SignatureMethod is applied. It extends to L34.
[L27] The canonicalization algorithm used to serialize SignedInfo that is, Canonical XML.
[L28] The signature algorithm in this case, the RSA algorithm coupled with the SHA-1 hash (see Chapter 17 for information on algorithms).
[L29] The Reference to the data signed. The null URI indicates the entire document in which this Reference element appears. The Reference extends to L33.
[L30] Because a signature cannot sign itself, you must specify a transform to drop the signature out of the data being signed.
[L31] The SHA-1 hash that links the data to the SignedInfo.
[L32] The base-64 representation of the SHA-1 hash of our document after the Transforms drop out the Signature element.
[L35] The base-64 encoding of the output from the SignatureMethod (including SHA-1) applied with our private key to the serialization of SignedInfo by the specified CanonicalizationMethod.
[L36] To make this signature verifiable by users with whom we do not have a prior relationship, we include an X509 Certificate with our public key. If someone believes that certificate, presumably because he or she can trace it back through a chain of certificates to a trusted Certification Authority, the user will trust our signature as well.
10.3.3 More Complex Protocol Example
Example 10-8 and Figure 10-4 show a more complete example of a simple protocol message. This example features two Reference elements and uses a Manifest element. In addition, it includes a hypothetical Routing element, which might influence the path followed by the object from source process to destination process. Likewise, it has a hypothetical Hopcount element, whose integer content is decremented for each application node through which it is transmitted, so that excess forwarding (probably a routing loop) can be detected and the object discarded or logged. Because Hopcount and Routing have no significance for the destination and the Hopcount element must change anyway, they are not signed. In actual use, the code might include more signed parts with different signatures and signers and intended for different ultimate recipients after forwarding.
Figure 10-4. Complex protocol signature example
Example 10-8 More complex protocol signature
[L40] <PDU> [L41] <Hopcount>3</Hopcount> [L42] <Routing>...</Routing> [L43] <unsigned>...</unsigned> [L45] <Signature> [L46] <SignedInfo> [L47] <CanonicalizationMethod Algorithm= [L48] "http://www.w3.org/2001/10/xml-exc-c14n#"/> [L49] <SignatureMethod Algorithm= "http://www.w3.org/2000/09/xmldsig#hmac-sha1"/> [L50] <Reference URI="#foo"> [L51] <DigestMethod Algorithm= "http://www.w3.org/2000/09/xmldsig#sha1"/> [L52] <DigestValue>...</DigestValue> [L53] </Reference> [L54] <Reference URI="#foo2" Type= "http://www.w3.org/2000/09/xmldsig#Manifest"> <DigestMethod Algorithm= "http://www.w3.org/2000/09/xmldsig#sha1"/> <DigestValue>...</DigestValue> </Reference> [L55] </SignedInfo> [L56] <SignatureValue>...</SignatureValue> [L57] <KeyInfo><KeyName>xyz</KeyName></KeyInfo> [L58] <Object > <signed>...</signed> </Object> [L59] <Object><Manifest > [L60] <Reference URI="ftp://bar.example/data.bin"> <DigestMethod Algorithm= "http://www.w3.org/2000/09/xmldsig#sha1"/> <DigestValue>...</DigestValue> </Reference> </Manifest></Object> [L61] </Signature> [L62} </PDU>
[L40] A more complex protocol data unit extending to L62.
[L41/43] A variety of unsigned material, including the "unsigned" element, which might consist of protocol data such as performance or debugging information whose inclusion in the signature would perturb what was being studied.
[L45] The authentication structure, which extends to L61.
[L46] The SignedInfo element actually authenticated, which is linked to the authenticated data by digests. It extends to L55.
[L47] The canonicalization algorithm applied to serialize SignedInfo.
[L49] The authentication algorithm applied to SignedInfo and a secret shared key.
[L50] The first of two References. The URI attribute provided points to the Object element later in the Signature. It extends to L53.
[L51/52] The hash algorithm and hash value that cryptographically link the SignedInfo to the first piece of data being authenticated.
[L54] The second Reference, which points to a Manifest found later in the Signature. The hash of the Manifest element itself, under the hash function given, is included, linking the Manifest to this SignedInfo.
[L56] The base-64 encoded value of the SignatureMethod applied to the shared secret key and the serialization of SignedInfo by CanonicalizationMethod.
[L57] Identification of the shared secret key by name.
[L58] The Object element that holds the signed protocol information present in the PDU.
[L59] An Object element wrapping a Manifest. This Manifest element refers to a data file elsewhere and gives the hash value and hash algorithm that produces that value when applied to that file. It links the file contents to this Mani fest, which can be used to cryptographically authenticate a later retrieved copy of the file. If the file has been directly referenced from SignedInfo, then XMLDSIG would require that it be retrieved and its hash verified as part of core Signature verification.
10.3.4 More Complex Form Example
As our last example, we consider a more complex form with two signatures: an "applicant" and an "office" signature (see Example 10-9 and Figure 10-5). Most real-world forms would be substantially more complex than this one, having more structures, probably more different namespaces, and so on. For simplicity, we have used unqualified names for the elements in our examples.
Figure 10-5. Complex document/form example
Example 10-9 More complex document/form signature
[L80] <Document...> [L81] <Field ...>... </Field> [L82] <Field>...<subF2>...<subsubF2 a="b"/>...</subF2>... </Field> [L83] <Signature> <!-- Applicant --> <SignedInfo> [L84] <CanonicalizationMethod .../> [L85] <SignatureMethod .../> [L86] <Reference URI=""> [L87] <Transforms><Transform Algorithm= "http://www.w3.org/TR/1999/REC-xpath-19991116"> <XPath> (//.|//@*//namespace::*)[ancestor-or-self::Field] </XPath></Transform></Transforms> <DigestMethod>...</DigestMethod> <DigestValue>...</DigestValue> </Reference> [L88] <Reference URI="key">...</Reference> </SignedInfo> <SignatureValue>...</SignatureValue> [L89] <KeyInfo ><X509Data><X509Certificate> cxeFhewnJ0+Xlwv09OZcXKVJSfQYGHnX1wSnp9Plyzj... </X509Certificate></X509Data></KeyInfo> [L90] </Signature> [L91] <Office ...>...</Office> [L92] <Signature> <!-- Office --> [L93] <SignedInfo><CanonicalizationMethod .../> <SignatureMethod .../> [L94] <Reference URI=""> [L95] <Transforms><Transform Algorithm= "http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> </Transforms> <DigestMethod>...</DigestMethod> <DigestValue>...</DigestValue> </Reference> </SignedInfo> <SignatureValue>...</SignatureValue> [L96] <KeyInfo><X509Data><X509Certificate> qUDa2mPi4ikODuC2tv4NDeoUFNZxceRzcxsVFRUfH6Y... </X509Certificate></X509Data></KeyInfo> [L97] </Signature> [L98] </Document>
[L80] Our more complex form, which extends to L98.
[L81/82] Fields filled in by an applicant. All use the element name Field, so presumably you can tell by attributes or content which is which.
[L83] The applicant's signature, extending to L90.
[L84/85] The CanonicalizationMethod applied to SignedInfo and the SignatureMethod used in the applicant signature.
[L86] The first Reference for the applicant signature. It starts with the entire document containing this Reference due to the null URI specified.
[L87] A transform that cuts down what the applicant signs to just nodes that have a "Field" element as an ancestor. In this example, those nodes include exactly those fields that the applicant filled in and wants to sign.
[L88] A second Reference in the applicant's signature, whereby the applicant also signs the keying information provided.
[L89] The applicant provides an X.509 certificate to back up the applicant's signature.
[L91] Information added to the form by the office.
[L92] The signature, by the office over the entire form, including the applicant data and signature, but excluding the office signature itself. It extends to L97.
[L93] The SignedInfo, the CanonicalizationMethod used to serialize it, and the SignatureMethod used by the office.
[L94] The Reference to the entire document for the office signature.
[L95] A transform, identified by its well-known URI, to drop out the office signature itself so that the office does not try to sign its own signature, which does not work.
[L96] The office's key information.