Digital Signature Syntax





Digital Signature Syntax

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.

  1. An enveloping signature contains the data it signs.

  2. An enveloped signature is contained inside the document it signs.

  3. 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 Figure.

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. Figure demonstrates, using the order document from Figure. 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.

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. Figure shows a version of Figure that contains an enveloped signature.

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. Figure is a detached signature for the order document shown in Figure.

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.


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows