January 17, 2021
Hot Topics:

NakovDocumentSigner: A System for Digitally Signing Documents in Web Applications

  • By Svetlin Nakov
  • Send Email »
  • More Articles »

Error Handling

If an error occurs at any of the described steps, the user is shown an appropriate error message. Errors can be produced in lots of situations—when the file to be signed is unable to be read, when the PFX file cannot be read, when the PFX file is invalid, when the private key is missing, when the certificate is missing, when the certificate format is invalid because of an error during the signing itself, because of inability to access the file system or some field of the form, as well as in a number of other unusual situations.

The Certification Chain Starts with the User's Certificate

Some readers can assume that the applet writes only the certification chain in the HTML form, without the certificate itself, but this is not exactly so. By specification, a certification chain always begins with the certificate it belongs to; in particular, it might even consist if it alone. Because of this, the writing of the certification chain in the HTML form means the certificate is also written as a part of the chain.

The PFX File Selection Dialog

The PFX file selection and password dialog allow users to select among PFX and P12 files only. The last-used PFX file is saved with its full path in a configuration file in the user's home directory, so that it can be used in the next showing of the dialog.

The applet's Graphic User Interface (GUI) is based on the AWT and JFC/Swing libraries, distributed along with the JDK 1.4.

About the Cryptographic Algorithms and APIs Used

The implementation of all used cryptographic algorithms is given by the default cryptographic services provider SunJSSE, which is also part of the JDK 1.4.

To sign files, the digital signature algorithm SHA1withRSA is used. This means that for the calculation of the document's hash value, the SHA1 algorithm is used and for encrypting this value and obtaining or the digital signature, the RSA algorithm is used. The SHA1withRSA algorithm is accessible in the Java Cryptography Architecture (JCA) through the java.security.Signature class. The length of the RSA keys depends on the user-selected PFX file and is usually 512 or 1024 bits. Depending on the RSA key, a digital signature with the same length is produced—usually 512 or 1024 bits (64 or 128 bytes, respectively). After encoding with Base64, the signature is written in 88 or 172 text characters, respectively.

The certification chain length depends on the number of certificates that construct it and on the contents of these certificates. Usually, after Base64 encoding, the chain has a length of 200-300 to 8000-10000 text characters.

To perform access to the protected keystore (the user selected PFX file), the java.security.KeyStore class is used. The applet expects the keystore to be in PKCS#12 format and to contain only one alias, in which the user's private key and certificate's certification chain are stored. In particular, the certification chain might consist of one certificate only—the user's certificate. The keystore access password is expected to coincide with the access password for the private key.

Generating a Self-Signed Certificate

For the applet to function properly, it is necessary that it be signed. For the purpose of its signing, a certificate issued by a certification authority (PFX file) can be used, as well as a self-signed certificate. We can use the generate-certificate.bat script to generate a self-signed certificate:


del DigitalSignerApplet.jks
keytool -genkey -alias signFiles -keystore DigitalSignerApplet.jks -keypass !secret -dname "CN=Your Company" -storepass !secretpause

As a result, we obtain a file named DigitalSignerApplet.jks, which is a keystore that contains the generated certificate and the corresponding private key, saved under the name "signFiles" and accessible with the password "!secret". The output file format is not PFX, but JKS (Java Key Store), which is used by default by the keytool utility.

Compiling the DigitalSignerApplet

We could use the build-script.bat script to compile the applet source code, create a JAR archive, and sign it:


del *.class
javac -classpath .;"%JAVA_HOME%\jre\lib\jaws.jar" *.java

del *.jar
jar -cvf DigitalSignerApplet.jar *.class

jarsigner -keystore DigitalSignerApplet.jks -storepass !secret -keypass !secret
DigitalSignerApplet.jar signFiles


This sequence of commands deletes all compiled .class files, compiles all .java files that constitute the applet, packs the resulting .class files in a JAR archive, and signs the archive with the self-signed certificate (located in the keystore DigitalSignerApplet.jks), generated in the previous step. For the source file compilation, JDK 1.4 or later is required. It is expected that the JAVA_HOME environment variable has a value corresponding to the full path to the directory where JDK is installed, and also that in the current path, the bin directory of the JDK installation is present.

Testing the DigitalSignerApplet

Now, we could test the signed applet with a sample HTML document containing an appropriate HTML form and the applet itself. We have created a test form called TestSignApplet.html.

It is important to note that we are not using the obsolete <applet> tag because it has no means of telling the browser that the applet only works with JDK 1.4 or later. If we use the <applet> tag, our applet would execute on any JDK, but would not always function properly.

Running the DigitalSignerApplet

Upon opening the sample HTML document shown above, it is first checked whether there is a Java Plug-In 1.4 or later installed on the machine. If the respective version of Java Plug-In is not found, the user is redirected to the site where it could be downloaded. If the machine has Java Plug-In 1.4 installed and the user's browser is correctly configured to use it for Java applets execution, upon loading the test HTML document, a dialog is shown that asks whether to allow the applet embedded in the loaded HTML page to execute with fill permissions. If the user consents, the applet starts normally.

The purpose of the test HTML page is to demonstrate signing files on the client machine. The example consists of a HTML form containing three fields, the signing applet, and a button that activates the signing procedure that is actually located inside the applet. The three fields are used to select a file to be sent, to write the certification chain, and to write the resulting signature, respectively. When the button is pressed, the user is presented the ability to select a PFX file and password. Afterwards, the applet signs the file with the private key from the selected PFX file. As a result of the signing, the calculated signature and the certification chain are written in the respective fields of the HTML form. Here's how the form and PFX file selection dialog look:

Click here for a larger image.

After a successful signing of the selected file, the HTML form looks like the following:

The certification chain and signature fields are filled in by the applet with values encoded in a text form in Base64 format.

Page 2 of 5

This article was originally published on January 12, 2004

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date