it.trento.comune.j4sign.examples

Class PKCS11SignApplet

java.lang.Object

java.awt.Component

java.awt.Container

java.awt.Panel

java.applet.Applet

javax.swing.JApplet

it.trento.comune.j4sign.examples.PKCS11SignApplet

All Implemented Interfaces:

java.awt.event.ActionListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, javax.swing.RootPaneContainer

public class PKCS11SignApplet
extends javax.swing.JApplet
implements java.awt.event.ActionListener

This is an implementation of a full-featured signing applet in a web environment.
PKCS11SignApplet sequence of operation follows:

1. Detects insertion of PKCS11 tokens (using pkcs11 api only)
2. Extracts signature certificates from the token, sending it to the server.
3. Receives from the server data to be signed, along with signature time; at the same time, triggers streaming and visualization of the document to be signed via javascript.
4. Asks PIN to the user and starts a signature session on the token
5. Receives raw signature from the token and sends it to the server which creates the CMS envelope.

All the communication between the applet and the server is done using HTTP GET and POST methods.

The applet can also expose some data via javascript to the embedding HTML page.

!!! BE CAREFUL !!!
THE APPLET RELIES HEAVILY ON BINARY DIGEST RECEIVED FROM THE SERVER, AND DOES NOT COMPUTE ITSELF THE DIGEST.
THIS CAN EXPOSE THE CLIENT TO THE RISK OF SIGNING DATA DIFFERENT FROM WHAT HE INTENDED, IF THE SERVER IS COMPROMISED.
HENCE YOU SHOULD USE THE APPLET ONLY IN A VERY WELL CONTROLLED ENVIRONMENT, AND THE SERVER SHOULD BE AUTHENTICATED
IN A STRONG MANNER (USE OF SSL/TLS IS STRONGLY SUGGESTED).
FURTHERMORE, THE PROBLEM OF DISPLAYING THE DOCUMENT TO BE SIGNED (THE "TRUSTED VIEWER" PROBLEM) IS ENTIRELY LEFT
TO THE WEB APPLICATION; WE REMIND THAT A CORRECT PRESENTATION OF THE DOCUMENT IS MANDATORY FOR THE LEGAL VALUE
OF THE SIGNATURE, ACCORDING TO ITALIAN DIGITAL SIGNATURE LAW.

Trying to approach these issues, and for dealing with CMS enveloping, j4sign provides a server side companion for the applet, CMSBuilder.
It is designed for answering to applet requests, an in particular for streaming content to be signed
in a synchronized way with digest generation, checking correctness on the fly.

The native library requirements for dealing with the tokens (the JNI part, such as the excellent pkcs11 wrapper developed by IAIK of Graz University of Technology,
and the pcsc wrapper taken from Open Card Framework project), along with the corresponding native libraries, are encapsulated in a standard Java Extension, named
SmartCardAccess. See it.trento.comune.j4sign.installer and Creating and Using Extensions.
The extension is deployed automatically the first time the applet is loaded.
The ultimate dependency for the applet is the cryptoki library, which has to be provided by the PKCS11 token manufacturer. The PCSCHelper class uses the pcsc wrapper
trying to infer the correct library from the ATR string returned from the token.

Some words about security; all downloaded jars, including the SmartCardAccess extension, has to be signed in order to work; this is needed for many reasons:

• the applet loads native libraries
• the applet deploys a java extension.

This should give also more confidence about signing software integrity.

Note that recent java 7 JVMs have stricter policies about Applets running outside the sandbox,
and many jar manifest attributes are now mandatory.

The applet "may script" and is "scriptable", that is it exposes its public methods to java script on the page it is embedded into, and can call java script functions defined in that page.
Special-named java script functions are indeed used to:

Asking visualization of the document to be signed: viewDocument() Return to the page the data to be signed: setDigest() Return to the page the encryptedDigest: setDigestFirmato() Return to the page the signer certificate extracted from the card: setCertificato() Submitting the page right after signature is completed: eseguiSubmit()
Here is a fragment of a suitable page:

  <head>
   <script language="JavaScript">
        function eseguiSubmit(){
           document.firmaform.submit();
        }
        function setDigest(aString){
           document.firmaform.digestDomandaBASE64.value=aString;
        }
        function setDigestFirmato(aString){
           document.firmaform.digestDomandaFirmatoBASE64.value=aString;
        }
        function setCertificato(aString){
           document.firmaform.certificatoBASE64.value=aString;
        }
        
        //IE insists to cache requests, add viewcount parameter for changing url 
        //at each view request.
        var viewcount=0;
        
        function viewDocument(hash){
                        document.getElementById('doctosign').src="viewdocument?datahash="+hash+"&vc="+viewcount++;
        }
   </script>
   </head>
   <body>
  <div align=center>
  
  <iframe id="doctosign" src="about:blank" width="100%" height="500">
      <p>Your browser does not support iframes</p>  
        </iframe>
  
  <strong>Tutti i dati nei campi della form sono codificati BASE64</strong>
  
  <form action="." name="firmaform" method="POST" >
  <strong>Digest</strong><br>
  <input type="test" name="digestDomandaBASE64" value=""  size="68" /><br>
  <strong>Digest crittato</strong><br>
  <textarea name="digestDomandaFirmatoBASE64"  rows="5" cols="64" ></textarea><br>
  <strong>Certificato</strong><br>
  <textarea name="certificatoBASE64" rows="5" cols="64"  ></textarea><br>
  </form>
  
  <applet height="150" width="600" code="dummy">
    <param name="jnlp_href" value="https://my.web.site//my-application/j4sign-pkcs11-applet.jnlp">
    <param name="singleSignature" value="<%=(session.getAttribute("doclist") == null)%>">
    <param name="digestPath" value="digest">
    <param name="encryptedDigestPath" value="encrypteddigest">
    <param name="datahash" value="${pi.contentHash}">
  </applet>
  </div>
 

Some parameters are to be generated dinamically, in this case (taken form a JSP) via Java and JSTL expressions.
In the above example, the applet is deployed via JNLP, using an xml descriptor (the j4sign-pkcs11-applet.jnlp) that provides all
the standard parameters in the deployment scenario. In particular, you can provide a central location
for the applet, avoiding to embed it in all applications.

Here follows an example:

 <?xml version="1.0" encoding="UTF-8"?>
 <jnlp spec="1.0+" codebase="" href="">
     <information>
         <title>j4sign signature Applet</title>
         <vendor>My firm name</vendor>
     </information>
     <resources>
         <!-- Application Resources -->
         <j2se version="1.7+"/>
         <jar href="https://my.web.site/signature/SignatureApplet-signed.jar" main="true" />
     </resources>
     <applet-desc
          name="Signer"
          main-class="it.trento.comune.j4sign.examples.PKCS11SignApplet"
          width="600"
          height="150">
        <param name="mayscript" value="true" />
        <param name="scriptable" value="true" />
     </applet-desc>
     <security>
        <all-permissions/>
     </security>
 </jnlp>
 

A note about applet parameters:

Inside applet tag

• jnlp_href: URI of the jnlp descriptor.
• singleSignature: boolean, whether this applet is going to sign one document or iterate over many ones.
• digestPath: path for POSTing certificate and receiving data to sign.
• encryptedDigestPath: path for POSTing raw signature.
• datahash: hash of the content to be signed. It is displayed by the applet, and checked server side when applet triggers document streaming.

Inside jnlp descriptor

• mayscript: if true, the applet may call javascript functions on the embedding page.
• scriptable: if true, the applet may have public method called by javascript functions on the embedding page.

Optional parameters:

• submitAfterSigning: if true, automatically submits the form after a successful signature, calling the eseguiSubmit() javascript function.
  Default value: true
• debug adds a scroll panel for viewing debug informations; set applet height to more than 200 to see the content.
  Default value: false
• cryptokilib name of the cryptoki library to load. It has to be inside PATH. This bypasses detection mechanism via ATR.

Author:

Roberto Resoli

See Also:

SimpleSignApplet, Serialized Form