Java Tips - Using the Java XML Digital Signature API

XML digital signatures have been on programmers' wish lists for some time. The good news is that JSR 105 now defines a standard Java technology API for providing XML digital signatures. This API is now part of the Java Web Services Development Pack (Java WSDP) 1.5. The Java WSDP 1.5 includes an implementation of the JSR 105 Proposed Final Draft. (Note that this is only the "proposed" final draft. The libraries might change before the final release.) The stated purpose of the Java XML Digital Signature API is to provide a vendor-neutral implementation of the W3C Recommendations for XML-Signature Syntax and Processing.

What is a digital signature? Much like its pen and paper counterpart, a digital signature assures to anyone reading data that the author is indeed who he or she claims to be. A digital signature provides what cryptographers call "authentication." It also ensures that the content of the data is exactly the same as what the author signed (that is, nothing has been added or removed). In the world of cryptography, this is known as "integrity."

Performing a digital signature involves two steps. In the first step, the data is run through a hashing algorithm. A typical hashing algorithm scans through the data and generates a number of some size -- this is typically called a "digest." If the same data is run through the hashing algorithm again, the same digest should be generated. Good hashing algorithms vary the digest unpredictably if the slightest change is made in the data. This makes it impossible to reverse engineer the original data, given the digest.

The second step in producing a digital signature is to encrypt the digest using the private key of the author. If you're not familiar with the terms public key or private key, then you've probably never heard of public key cryptography. The basic concepts of public key cryptography are simple: anything that is encrypted using an individual's private key, can only be decrypted using the same individual's public key. The reverse is also true: anything encrypted using an individual's public key, can only be decrypted using the same individual's private key. The two keys are mathematically linked. After encrypting the digest with the user's private key, the resulting scrambled data is then appended to the original document data.

Because public keys can be shared with anyone, and private keys should be known only to the signing author, verifying a digital signature is simple. The steps are:

If the two digests are not equal, then either the document has been altered, or the author of the document is not the same as the individual that signed it. However this information does not indicate which of those two faults (or both) have occurred.

There are two parts of the JSR 105 API. The first part allows Java developers to create XML digital signatures for their data. The second part allows third-party developers to create provider implementations of the XML Digital Signature API and register them. This tip covers the first part only. It presents a simple example of how to sign an XML document and then verify that signature. Note that the XML signatures generated by JSR 105 can be applied to both XML and binary data. The resulting signature is created in XML.

An XML Signature takes one of three forms. Assuming that the XML signature is contained in a <Signature> element, the only difference between the three forms is where the <Signature> element is located with respect to the document data. The three forms are:

Let's assume that the data to be signed is contained in an <Envelope> element. Here is what the XML document looks like before applying a signature:

Here's what the XML document looks like after the data is signed with an enveloped signature (note that these examples have been re-formatted and indented for easier reading):

A number of elements are added inside of the <Signature> element by the XML digital signature process. These elements are <SignedInfo>, <SignatureValue> element, and <KeyInfo>.

The <SignedInfo> element contains signature information, as well as references to the data that is to be signed. In actuality, <SignedInfo> is the element that the signature is calculated over. Here is how this happens:

The second element, <SignatureValue>, is relatively simple. It contains an arbitrarily-large text-encoded number which is the scrambled signature for the document in question. For example:

Anyone who receives the XML document must be able to validate this signature. So the original document author (the signer) must append his or her public key to the document. (In reality, the public key should be authenticated with a certificate authority, but that's beyond the scope of this tip.) The public key is stored in the third element, <KeyInfo>. Here is an example of a raw DSA key. The value is in the <KeyValue> element (a subelement of <KeyInfo>):

Here is an example that can be used to generate an XML digital signature (the example is adapted from the examples provided for the API with Java WSDP 1.5):

   String providerName = System.getProperty("jsr105Provider",

             "org.jcp.xml.dsig.internal.dom.XMLDSigRI");

      

         XMLSignatureFactory fac =

             XMLSignatureFactory.getInstance("DOM",

             (Provider) Class.forName(providerName).newInstance());

      

         Reference ref =

             fac.newReference("",

                 fac.newDigestMethod(DigestMethod.SHA1, null),

                     Collections.singletonList(

                         fac.newTransform(Transform.ENVELOPED, null)), 

                 null, null);

      

             SignedInfo si = fac.newSignedInfo

                 (fac.newCanonicalizationMethod

                   (CanonicalizationMethod.INCLUSIVE_WITH_COMMENTS, 

                       null), 

                  fac.newSignatureMethod(SignatureMethod.DSA_SHA1, 

                      null),

                  Collections.singletonList(ref));

                  

             KeyPairGenerator kpg = 

                 KeyPairGenerator.getInstance("DSA");

             kpg.initialize(512);

             KeyPair kp = kpg.generateKeyPair();

      

             KeyInfoFactory kif = fac.getKeyInfoFactory();

             KeyValue kv = kif.newKeyValue(kp.getPublic());

      

             KeyInfo ki = 

                 kif.newKeyInfo(Collections.singletonList(kv));

      

             DocumentBuilderFactory dbf =

                 DocumentBuilderFactory.newInstance();

             dbf.setNamespaceAware(true);

             Document doc = 

                 dbf.newDocumentBuilder().

                 parse(new FileInputStream("myfile"));

      

             DOMSignContext dsc = new DOMSignContext

              (kp.getPrivate(), doc.getDocumentElement());

      

             XMLSignature signature = fac.newXMLSignature(si, ki);

                signature.sign(dsc);

      

             TransformerFactory tf = TransformerFactory.newInstance();

             Transformer trans = tf.newTransformer();

             trans.transform(

                 new DOMSource(doc),

                 new StreamResult(

                     new FileOutputStream("mySignedFile"));

The following lines of code create the XML signature factory, which is used to sign the document:

 String providerName = System.getProperty("jsr105Provider",

       "org.jcp.xml.dsig.internal.dom.XMLDSigRI");

      

       XMLSignatureFactory fac =

       XMLSignatureFactory.getInstance("DOM",

       (Provider) Class.forName(providerName).newInstance());

The code then creates Reference and SignedInfo objects. These map directly to their respective elements in the XML signature.

   Reference ref =

             fac.newReference("",

                 fac.newDigestMethod(DigestMethod.SHA1, null),

                     Collections.singletonList(

                         fac.newTransform(Transform.ENVELOPED, null)), 

                 null, null);

      

             SignedInfo si = fac.newSignedInfo

                 (fac.newCanonicalizationMethod

                   (CanonicalizationMethod.INCLUSIVE_WITH_COMMENTS, 

                       null), 

                  fac.newSignatureMethod(SignatureMethod.DSA_SHA1, 

                      null),

                  Collections.singletonList(ref));

Next, the JCA classes are used to generate a 512-bit DSA key, and create a KeyInfo object that includes the public key. The KeyInfo object also maps to the <KeyInfo> element in the signature.

       KeyPairGenerator kpg = 

                 KeyPairGenerator.getInstance("DSA");

             kpg.initialize(512);

             KeyPair kp = kpg.generateKeyPair();

      

             KeyInfoFactory kif = fac.getKeyInfoFactory();

             KeyValue kv = kif.newKeyValue(kp.getPublic());

      

             KeyInfo ki = 

                 kif.newKeyInfo(Collections.singletonList(kv));

Finally, the code uses the JAXP DocumentBuilderFactory to create a document from the filename given, create an XML signature object, and use the TransformerFactory to write the signature to an OutputStream. The result is sent to the file mySignedFile.

       DocumentBuilderFactory dbf =

                 DocumentBuilderFactory.newInstance();

             dbf.setNamespaceAware(true);

             Document doc = 

                 dbf.newDocumentBuilder().

                 parse(new FileInputStream("myfile"));

      

             DOMSignContext dsc = new DOMSignContext

              (kp.getPrivate(), doc.getDocumentElement());

      

             XMLSignature signature = fac.newXMLSignature(si, ki);

                signature.sign(dsc);

      

             TransformerFactory tf = TransformerFactory.newInstance();

             Transformer trans = tf.newTransformer();

             trans.transform(

                 new DOMSource(doc),

                     new StreamResult(

                     new FileOutputStream("mySignedFile"));

        DocumentBuilderFactory dbf = 

                  DocumentBuilderFactory.newInstance();

              dbf.setNamespaceAware(true);

              Document doc =

                  dbf.newDocumentBuilder().parse(new

                  FileInputStream("mySignedFile"));

      

              NodeList nl = 

                  doc.getElementsByTagNameNS(XMLSignature.XMLNS, 

                    "Signature");

              if (nl.getLength() == 0) {

                  throw new Exception("Cannot find Signature element");

              }

      

              String providerName = System.getProperty(

                  "jsr105Provider",

                  "org.jcp.xml.dsig.internal.dom.XMLDSigRI");

              XMLSignatureFactory fac = 

                   XMLSignatureFactory.getInstance("DOM",

                  (Provider) Class.forName(providerName).newInstance());

              DOMValidateContext valContext = new DOMValidateContext

                  (new KeyValueKeySelector(), nl.item(0));

      

              XMLSignature signature = 

                  fac.unmarshalXMLSignature(valContext);

              boolean coreValidity = signature.validate(valContext); 

      

              if (coreValidity == false) {

                  System.err.println("Signature failed"); 

              } else {

                  System.out.println("Signature passed");

              }

          }

The first section of code uses the JAXP DocumentBuilderFactory to create a namespace-aware Document object from the file mySignedFile:

        DocumentBuilderFactory dbf = 

                  DocumentBuilderFactory.newInstance();

              dbf.setNamespaceAware(true);

              Document doc =

                  dbf.newDocumentBuilder().parse(new

                  FileInputStream("mySignedFile"));

Next, it programmatically extracts the <Signature> element (and all its children) from the XML:

        NodeList nl = 

                  doc.getElementsByTagNameNS(XMLSignature.XMLNS, 

                    "Signature");

              if (nl.getLength() == 0) {

                  throw new Exception("Cannot find Signature element");

              }

Then it creates an XMLSignatureFactory and DOMValidateContext object for use in unmarshalling the XML signature:

        String providerName = System.getProperty(

                  "jsr105Provider",

                  "org.jcp.xml.dsig.internal.dom.XMLDSigRI");

              XMLSignatureFactory fac = 

                   XMLSignatureFactory.getInstance("DOM",

                  (Provider) Class.forName(providerName).newInstance());

              DOMValidateContext valContext = new DOMValidateContext

                  (new KeyValueKeySelector(), nl.item(0));

After an appropriate XMLSignature object is obtained, the program calls the validate() method using the appropriate context to determine whether the signature is valid:


              XMLSignature signature = 

                  fac.unmarshalXMLSignature(valContext);

              boolean coreValidity = signature.validate(valContext); 

      

              if (coreValidity == false) {

                  System.err.println("Signature failed"); 

              } else {

                  System.out.println("Signature passed");

              }

          }

Related Tips