September 19, 2020
Hot Topics:

Java Applet for Signing with a Smart Card

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

How the Applet for Signing with a Smart Card Works

The applet for signing documents with a smart card in the user's Web browser works in the exact same way as the applet you built for signing with PFX files from my previous article, NakovDocumentSigner: A System for Digitally Signing Documents in Web Applications.

First of all, through the class netscape.javascript.JSObject the name of the file is extracted for signing from the HTML form and this file is loaded in the memory. This is possible because the applet is signed and has access to the local file system.

After that, a dialog window pops up and the user is requested to select a PKCS#11 library and provide the PIN code to access the smart card. When the user selects the library with the PKCS#11 implementation and types the PIN code, you extract the certificate from the smart card, together with its certification chain (if it is present) and its private key. Actually, the private key is not physically extracted (because this is not possible by design), but a Java interface to access it is retrieved for later use.

The certification chain is encrypted in ASN.1 DER format and is written in text format (with BASE64 encoding) in the corresponding text field of the HTML form. The class JSObject is used again to access the form in the Web browser.

Later, the file read in the memory is signed with the private key from the smart card and the digital signature received is transformed to text format with BASE64 encoding, and is written in a field of the HTML form.

If an error occurs in one of the described steps, the user is shown the respective error message. An error can occur in many situations—if the signing file cannot be read, if the PKCS#11 library implementation is invalid, if the PIN code is invalid, if there is a missing certificate or private key on the smart card, if the HTML form cannot be accessed, and so on.

The applet's graphic user interface is based on the libraries package found at AWT and JFC/Swing, which come with the standard JDK 5.0.

The dialog window for choosing the PKCS#11 implementation and PIN code gives the option to select only between .dll and .so files (Windows and Linux libraries). The last-used PKCS#11 library, with the full path to it, is saved in the applet's configuration file. This file is located in the user's home directory so that it can be used the next time this dialog window is shown.

To access the smart card, the Sun PKCS#11 Provider is used, which is instanced with Java reflection and is configured dynamically. The sun.security.pkcs11.SunPKCS11 class is instanced with the "reflection" technology, so that it is not linked statically with the applet. If the class is statically linked to the applet and this class is missing (such as in Java Plug-In versions smaller than 5.0), the applet wouldn't load at all. The advantage of instantiating the class with reflection is that the applet will load successfully and will throw an exception if the required class is missing. In this case, the user will receive an appropriate error message.

After the PKCS#11 provider is registered, the access to the smart card keystore is performed through the class found at java.security.KeyStore. The applet is expecting the smart card keystore to contain only one record (alias), in which it holds the user's certificate (possibly together with its certification chain) and its corresponding private key.

The implementation of all used cryptographic algorithms is ensured by the default cryptographic services provider SunJSSE, which is a standard part from JDK 5.0.

To sign files, the digital signature algorithm "SHA1withRSA" is used, which is available in Java through the class found at java.security.Signature, and is supported by most smart cards.

Compiling and Signing the Applet

For the applet to work properly, it must be signed. This is necessary because the applet will need to have access to the file system to read the file for signing. You can use the following script to generate a self-signed certificate that you then can use to sign the applet:


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

As a result of the script execution, you will obtain a keystore file, SmartCardSignerApplet.jks, which contains a generated certificate and its corresponding private key saved under the name "signFiles" and accessible with the password "!secret". The format of the file is JKS (Java Keystore). This file will used by default from keytool, a command-line program for managing keystores in Java 2 SDK, Standard Edition.

To compile the source code of the applet, create the JAR archive and to sign it use the following script:


set JAVA5_HOME=C:Progra~1Javajdk1.5.0_04

del *.class
%JAVA5_HOME%binjavac -classpath .;
   "%JAVA5_HOME%jrelibplugin.jar" *.java

del *.jar
%JAVA5_HOME%binjar -cvf SmartCardSignerApplet.jar *.class
%JAVA5_HOME%binjarsigner -keystore SmartCardSignerApplet.jks
   -storepass !secret
   -keypass !secret
   SmartCardSignerApplet.jar signFiles


The specified sequence of commands deletes all compiled .class files, compiles all .java files, puts the obtained .class files in the archive SmartCardSignerApplet.jar, and signs this very same archive with the generated beforehand, self-signed certificate (located in the SmartCardSignerApplet.jks keystore file). For the compilation, JDK 5.0 or newer is required.

Testing the Applet with a Sample HTML Form

You can test the signed applet test with a sample HTML document that contains an HTML form that will interact with the applet (see Listing 4):

It is important to use the <object> and <embed> tags instead of the old <applet> tag. If you use the old tag, you cannot tell the Web browser that the required Java version is 5.0 or newer.

The sample HTML page contains an HTML form with three fields, an applet for signing, and a button for activation of the signing, which is actually located inside the applet. The three fields in the form are used to select the file to be sent, to save the certification chain used in the signing process, and to sign the received signature.

The Applet for Signing with a Smart Card in Action

When the user opens the sample HTML document, first it checks to see whether the machine has, found at Java Plug-In, 5.0 or newer installed. If the version is older, the user is automatically redirected to the Web site from which the new version can be downloaded and installed.If the machine has installed Java Plug-In 5.0, when the HTML document is loaded a dialog window pops up and requests the user confirmation to execute the applet with full permissions. See Figure 1.

Figure 1: Java Plug-In 5.0 requesting to execute the signed applet with full permissions

If the user trusts the company mentioned, and selects yes, the applet will start as usual. There is also a way to assign permanent trust in the company. In those cases, the Java Plug-In doesn't request any more confirmation to execute it with full rights, but executes it directly in every consequent loading.

When the [Sign] button (which is located inside the applet) is pressed, the user is requested to provide a PKCS#11 library implementation and the PIN code for accessing the smart card. See Figure 2:

Click here for a larger image.

Figure 2: Signing with a smart card in a Web-based environment

If the signing is successful, the calculated signature and the certificate extracted from the smart card, are recorded into the HTML form, as seen in Figure 3:

Figure 3: An HTML form with a signed file in it

The applet for signing with a smart card can be tested online on the NakovDocumentSigner Web site.

Page 3 of 8

This article was originally published on February 24, 2006

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