Digital Signature Syntax | Effective XML: 50 Specific Ways to Improve Your XML

I'm going to give you just a brief overview of what a digitally signed XML document looks like. The arithmetic is far too complex for most humans to do by hand (even programmers). It's virtually certain that you'll use some software application or library to sign and verify your documents. XML documents aren't signed by hand.

There are three basic kinds of signatures.

An enveloping signature contains the data it signs.
An enveloped signature is contained inside the document it signs.
A detached signature signs data external to the document identified by a URL.

Before any XML document can be signed, it needs to be transformed into a canonical form that normalizes syntactically irrelevant details like attribute order and the amount of white space inside tags. For example, let us suppose we have a document that represents order and payment information, as shown in Example 48-1.

Example 48-1 An Order Document

 <?xml version="1.0"?> <Order>   <Item type="BackIssue">     <Title>Fables</Title>     <Issue>2</Issue>     <Publisher>DC</Publisher>   </Item>   <Item type="BackIssue">     <Title>Gen 13</Title>     <Issue>46</Issue>     <Publisher>Wildstorm</Publisher>   </Item>   <CreditCard type="VISA">     <Name>Elliotte Rusty Harold</Name>     <Number>5555 3142 2718 2998</Number>     <Expires>       <Month>06</Month>       <Year>2006</Year>     </Expires>   </CreditCard> </Order>

Suppose the comic shop wants to verify that I actually sent this order before charging my credit card. The store could require that I sign the document with my private key, which they would then verify with my public key.

The most common way to do this is with an enveloping signature. This includes the document being signed inside the signature. Example 48-2 demonstrates , using the order document from Example 48-1. The root element is now Signature instead of Order . However, the last child element of the Signature element is a dsig:Object element that contains the root Order element of the original document. This is what has been signed. After verifying the signature, you can extract the original element using any of the usual techniques. A tree-based API such as JDOM, XOM, or DOM is probably the simplest approach here.

Example 48-2 An 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="#Res0">       <Transforms>         <Transform Algorithm=           "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>       </Transforms>       <DigestMethod Algorithm=          "http://www.w3.org/2000/09/xmldsig#sha1"/>       <DigestValue>tRJGGSB544BQ1CVyj9UdR3+8/PE=</DigestValue>     </Reference>   </SignedInfo>   <SignatureValue>     GzgtyIj1DYTBX1idqH0wjae7U2lUBCXaAkuvBKeVIUWkwWyGHqBXqQ==   </SignatureValue>   <KeyInfo>     <KeyValue>       <DSAKeyValue>         <P>           /X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY           1Y+r/F9bow9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX           /rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOuK2HXKu/yIg           MZndFIAcc=         </P>         <Q>l2BQjxUjC8yykrmCouuEC/BYHPU=</Q>         <G>           9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+           ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWR           bqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZA           FMO/7PSSo=         </G>         <Y>           7bQ9Utz1cuAXbXGPwSC/v29fxGDiqXMO3nnyp3qvCzS351MWvYC3pf           zW4KAqxEUdMeBzSpysBAhBW4IwEYSTRZ3RFtJUf2hjHhxo93oakMKZ           /pfeg4MTPLM1rAQuTZ7tRI8jvXu/snhJknhhnGPGWGt1ZOePT24Mlx           f+1hTGRck=         </Y>       </DSAKeyValue>     </KeyValue>     <X509Data>       <X509IssuerSerial>         <X509IssuerName>           CN=Elliotte Harold,OU=Metrotech,O=Polytechnic,           L=Brooklyn, ST=New York,C=US</X509IssuerName>         <X509SerialNumber>1046543415</X509SerialNumber>       </X509IssuerSerial>       <X509SubjectName>         CN=Elliotte Harold,OU=Metrotech,O=Polytechnic,         L=Brooklyn,ST=New York,C=US</X509SubjectName>       <X509Certificate> MIIDJDCCAuECBD5g/DcwCwYHKoZIzjgEAwUAMHcxCzAJBgNVBAYTAlVTMREwDwYD VQQIEwhOZXcgWW9yazERMA8GA1UEBxMIQnJvb2tseW4xFDASBgNVBAoTC1BvbHl0 ZWNobmljMRIwEAYDVQQLEwlNZXRyb3RlY2gxGDAWBgNVBAMTD0VsbGlvdHRlIEhh cm9sZDAeFw0wMzAzMDExODMwMTVaFw0wMzA1MzAxODMwMTVaMHcxCzAJBgNVBAYT AlVTMREwDwYDVQQIEwhOZXcgWW9yazERMA8GA1UEBxMIQnJvb2tseW4xFDASBgNV BAoTC1BvbHl0ZWNobmljMRIwEAYDVQQLEwlNZXRyb3RlY2gxGDAWBgNVBAMTD0Vs bGlvdHRlIEhhcm9sZDCCAbgwggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUSKVLf Spwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4Ad NG/yZmC3a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUPBPuD9tPFHsMCNVQT WhaRMvZ1864rYdcq7/IiAxmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1AoGB APfhoIXWmz3ey7yrXDa4V7l5lK+7+jrqgvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0 SRZxI+hMKBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1kW6jfwv6ITVi8ftiegEk O8yk8b6oUZCJqIPf4VrlnwaSi2ZegHtVJWQBTDv+z0kqA4GFAAKBgQDttD1S3PVy 4BdtcY/BIL+/b1/EYOKpcw7eefKneq8LNLfnUxa9gLel/NbgoCrERR0x4HNKnKwE CEFbgjARhJNFndEW0lR/aGMeHGj3ehqQwpn+l96DgxM8szWsBC5Nnu1EjyO9e7+y eEmSeGGcY8ZYa3Vk549PbgyXF/7WFMZFyTALBgcqhkjOOAQDBQADMAAwLQIVAIQs 71E6P19ImxGIwBQfmB9ov0HTAhRtlgIWB6YUqt7ilNcSxfbHWOMKLA==       </X509Certificate>     </X509Data>   </KeyInfo>   <dsig:Object xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"                xmlns="" Id="Res0"><Order>   <Item type="BackIssue">     <Title>Fables</Title>     <Issue>2</Issue>     <Publisher>DC</Publisher>   </Item>   <Item type="BackIssue">     <Title>Gen 13</Title>     <Issue>46</Issue>     <Publisher>Wildstorm</Publisher>   </Item>   <CreditCard type="VISA">     <Name>Elliotte Rusty Harold</Name>     <Number>5555 3142 2718 2998</Number>     <Expires>       <Month>06</Month>       <Year>2006</Year>     </Expires>   </CreditCard> </Order></dsig:Object> </Signature>

Do not concern yourself excessively with the detailed syntax of this example. Even if the XML structure is intelligible to a person, the mathematics required to produce the Base64-encoded signature really aren't. I suppose it's theoretically possible that an arithmetical savant could do this by hand, but in practice it's always done by computer. You don't need to worry about the details unless you're writing the software to generate and verify digital signatures. Most programmers just use a library written by somebody else such as XML-Security from the XML Apache Project (http://xml.apache.org/security/) or XSS4J from IBM (http://www.alphaworks.ibm.com/tech/xmlsecuritysuite).

You should also not worry about the size. Since the original example was quite small, the signature markup forms a large part of the signed document. However, the size of the signature markup is almost constant. You could sign a multimegabyte document with the same number of bytes used here. The size of the signature is independent of the document signed and only lightly coupled to the size of the key or the algorithm used.

Sometimes it may be more convenient to keep the same root element but add the Signature element inside that document. This is a little tricky because verification needs to be careful to verify the document without considering the signature to be part of it. Still, although this caused a little extra work for the designers of the XML digital signature specification, the details are now encapsulated in the different libraries you might use, so it's not really any extra work for your code. Example 48-3 shows a version of Example 48-1 that contains an enveloped signature.

Example 48-3 An Enveloped Signature

 <Order>   <Item type="BackIssue">     <Title>Fables</Title>     <Issue>2</Issue>     <Publisher>DC</Publisher>   </Item>   <Item type="BackIssue">     <Title>Gen 13</Title>     <Issue>46</Issue>     <Publisher>Wildstorm</Publisher>   </Item>   <CreditCard type="VISA">     <Name>Elliotte Rusty Harold</Name>     <Number>5555 3142 2718 2998</Number>     <Expires>       <Month>06</Month>       <Year>2006</Year>     </Expires>   </CreditCard>   <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="">         <Transforms>           <Transform Algorithm=          "http://www.w3.org/2000/09/xmldsig#enveloped-signature"           />         </Transforms>         <DigestMethod Algorithm=             "http://www.w3.org/2000/09/xmldsig#sha1"/>         <DigestValue>pCD81qloCPf9UBbJ1CnTwMh+Wo4=</DigestValue>       </Reference>     </SignedInfo>     <SignatureValue>         dguuK7RO1THsftPd/yHJK+1ImHYd8dAy8mGk7GzAH/vVFxFkysJplQ==     </SignatureValue>   <KeyInfo>     <KeyValue>       <DSAKeyValue>         <P>           /X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY           1Y+r/F9bow9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX           /rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOuK2HXKu/yIg           MZndFIAcc=         </P>         <Q>l2BQjxUjC8yykrmCouuEC/BYHPU=</Q>         <G>           9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+           ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWR           bqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZA           FMO/7PSSo=         </G>         <Y>           7bQ9Utz1cuAXbXGPwSC/v29fxGDiqXMO3nnyp3qvCzS351MWvYC3pf           zW4KAqxEUdMeBzSpysBAhBW4IwEYSTRZ3RFtJUf2hjHhxo93oakMKZ           /pfeg4MTPLM1rAQuTZ7tRI8jvXu/snhJknhhnGPGWGt1ZOePT24Mlx           f+1hTGRck=         </Y>       </DSAKeyValue>     </KeyValue>     <X509Data>       <X509IssuerSerial>         <X509IssuerName>          CN=Elliotte Harold,OU=Metrotech,O=Polytechnic,          L=Brooklyn,ST=New York,C=US         </X509IssuerName>         <X509SerialNumber>1046543415</X509SerialNumber>       </X509IssuerSerial>       <X509SubjectName>         CN=Elliotte Harold,OU=Metrotech,O=Polytechnic,         L=Brooklyn,ST=New York,C=US</X509SubjectName>       <X509Certificate> MIIDJDCCAuECBD5g/DcwCwYHKoZIzjgEAwUAMHcxCzAJBgNVBAYTAlVTMREwDwYD VQQIEwhOZXcgWW9yazERMA8GA1UEBxMIQnJvb2tseW4xFDASBgNVBAoTC1BvbHl0 ZWNobmljMRIwEAYDVQQLEwlNZXRyb3RlY2gxGDAWBgNVBAMTD0VsbGlvdHRlIEhh cm9sZDAeFw0wMzAzMDExODMwMTVaFw0wMzA1MzAxODMwMTVaMHcxCzAJBgNVBAYT AlVTMREwDwYDVQQIEwhOZXcgWW9yazERMA8GA1UEBxMIQnJvb2tseW4xFDASBgNV BAoTC1BvbHl0ZWNobmljMRIwEAYDVQQLEwlNZXRyb3RlY2gxGDAWBgNVBAMTD0Vs bGlvdHRlIEhhcm9sZDCCAbgwggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUSKVLf Spwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4Ad NG/yZmC3a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUPBPuD9tPFHsMCNVQT WhaRMvZ1864rYdcq7/IiAxmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1AoGB APfhoIXWmz3ey7yrXDa4V7l5lK+7+jrqgvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0 SRZxI+hMKBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1kW6jfwv6ITVi8ftiegEk O8yk8b6oUZCJqIPf4VrlnwaSi2ZegHtVJWQBTDv+z0kqA4GFAAKBgQDttD1S3PVy 4BdtcY/BIL+/b1/EYOKpcw7eefKneq8LNLfnUxa9gLel/NbgoCrERR0x4HNKnKwE CEFbgjARhJNFndEW0lR/aGMeHGj3ehqQwpn+l96DgxM8szWsBC5Nnu1EjyO9e7+y eEmSeGGcY8ZYa3Vk549PbgyXF/7WFMZFyTALBgcqhkjOOAQDBQADMAAwLQIVAIQs 71E6P19ImxGIwBQfmB9ov0HTAhRtlgIWB6YUqt7ilNcSxfbHWOMKLA==       </X509Certificate>     </X509Data>   </KeyInfo>   </Signature> </Order>

A detached signature neither contains nor is contained in the document it signs. Instead it points to the document being signed with a URI. This allows it to sign things besides XML documents such as JPEG images and Microsoft Word files. The object signed is identified by the URI attribute of a Reference element. Example 48-4 is a detached signature for the order document shown in Example 48-1.

Example 48-4 A Detached 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=      "file:///home/elharo/books/effectivexml/examples/order.xml"     >       <DigestMethod Algorithm=         "http://www.w3.org/2000/09/xmldsig#sha1"/>       <DigestValue>J4qs6XERp3S9frY9Je3IiZL2yvs=</DigestValue>     </Reference>   </SignedInfo>   <SignatureValue>     TIptdglMXBgmHWFm1jOygQiMr4JJGGPAMW8XR65mGpjNeV469EiieQ==   </SignatureValue>   <KeyInfo>     <KeyValue>       <DSAKeyValue>         <P>           /X9TgR11EilS30qcLuzk5/YRt1I870QAwx4/gLZRJmlFXUAiUftZPY           1Y+r/F9bow9subVWzXgTuAHTRv8mZgt2uZUKWkn5/oBHsQIsJPu6nX           /rfGG/g7V+fGqKYVDwT7g/bTxR7DAjVUE1oWkTL2dfOuK2HXKu/yIg           MZndFIAcc=         </P>         <Q>l2BQjxUjC8yykrmCouuEC/BYHPU=</Q>         <G>           9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+           ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWR           bqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZA           FMO/7PSSo=         </G>         <Y>           7bQ9Utz1cuAXbXGPwSC/v29fxGDiqXMO3nnyp3qvCzS351MWvYC3pf           zW4KAqxEUdMeBzSpysBAhBW4IwEYSTRZ3RFtJUf2hjHhxo93oakMKZ           /pfeg4MTPLM1rAQuTZ7tRI8jvXu/snhJknhhnGPGWGt1ZOePT24Mlx           f+1hTGRck=         </Y>       </DSAKeyValue>     </KeyValue>     <X509Data>       <X509IssuerSerial>         <X509IssuerName>           CN=Elliotte Harold,OU=Metrotech,O=Polytechnic,           L=Brooklyn,ST=New York,C=US</X509IssuerName>         <X509SerialNumber>1046543415</X509SerialNumber>       </X509IssuerSerial>       <X509SubjectName>          CN=Elliotte Harold,OU=Metrotech,O=Polytechnic,          L=Brooklyn,ST=New York,C=US</X509SubjectName>       <X509Certificate> MIIDJDCCAuECBD5g/DcwCwYHKoZIzjgEAwUAMHcxCzAJBgNVBAYTAlVTMREwDwYD VQQIEwhOZXcgWW9yazERMA8GA1UEBxMIQnJvb2tseW4xFDASBgNVBAoTC1BvbHl0 ZWNobmljMRIwEAYDVQQLEwlNZXRyb3RlY2gxGDAWBgNVBAMTD0VsbGlvdHRlIEhh cm9sZDAeFw0wMzAzMDExODMwMTVaFw0wMzA1MzAxODMwMTVaMHcxCzAJBgNVBAYT AlVTMREwDwYDVQQIEwhOZXcgWW9yazERMA8GA1UEBxMIQnJvb2tseW4xFDASBgNV BAoTC1BvbHl0ZWNobmljMRIwEAYDVQQLEwlNZXRyb3RlY2gxGDAWBgNVBAMTD0Vs bGlvdHRlIEhhcm9sZDCCAbgwggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUSKVLf Spwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4Ad NG/yZmC3a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUPBPuD9tPFHsMCNVQT WhaRMvZ1864rYdcq7/IiAxmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1AoGB APfhoIXWmz3ey7yrXDa4V7l5lK+7+jrqgvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0 SRZxI+hMKBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1kW6jfwv6ITVi8ftiegEk O8yk8b6oUZCJqIPf4VrlnwaSi2ZegHtVJWQBTDv+z0kqA4GFAAKBgQDttD1S3PVy 4BdtcY/BIL+/b1/EYOKpcw7eefKneq8LNLfnUxa9gLel/NbgoCrERR0x4HNKnKwE CEFbgjARhJNFndEW0lR/aGMeHGj3ehqQwpn+l96DgxM8szWsBC5Nnu1EjyO9e7+y eEmSeGGcY8ZYa3Vk549PbgyXF/7WFMZFyTALBgcqhkjOOAQDBQADMAAwLQIVAIQs 71E6P19ImxGIwBQfmB9ov0HTAhRtlgIWB6YUqt7ilNcSxfbHWOMKLA==       </X509Certificate>     </X509Data>   </KeyInfo> </Signature>

If you're signing non-XML data, you must use a detached signature. If you're signing XML data, you should use either an enveloped or enveloping signature because they ignore XML-insignificant details like white space in tags and whether empty elements are represented with one tag or two. Whether you use enveloped or enveloping signatures depends mainly on which seems simpler to you. Most tools and class libraries for generating and verifying signatures work equally well with either.