DC add-on: Embed Java applet to web page

Discuss this help topic in SecureBlackbox Forum

The Java applet can be used to sign data remotely. Java applets are supported in different browsers and now, they are the most universal solution for browser based security related tasks. If Java applets are disabled in the browser, it is possible to launch the applet via Java Web Start as a standalone application (see Run Java applet when Java is disabled in browser topic for details).

With the Java applet, the user is able to use Windows system certificate storage, cryptographic tokens and smart cards (if they provide PKCS#11 drivers), as well as X.509 certificates stored in Java Key Storages (JKS) and PKCS#12 (PFX , P12) files to sign data, provided from the server, and return the signature back to the server.

There are 2 possible ways to use the Java applet in the browser:

Embed the applet into a web page. This way is supported in Internet Explorer and Firefox browsers but not supported in Chrome;
Use JNLP file to run the applet as a standalone application which uses resources from the server. This way is supported in all browsers including Chrome.

The applet can be compiled with JDK 5 and later. Please note that if there is only JRE 5 available on the client computer, the applet will not use Windows system certificate storage, which is supported since JRE 6 only.

Embedding the applet

The applet can be embedded into a HTML page using the following code:

<applet archive="com.secureblackbox.dc.jar, com.secureblackbox.dc.applet.jar"
        code="com.secureblackbox.dc.applet.ElDCServerApplet"
        width=500 height=240>
    <param name="Data" value="base64-encoded xml request" />
    <param name="DataURL" value="absolute or relative url" />
    <param name="GoURL" value="absolute or relative url" />
    <param name="SessionID" value="unique text" />
    <param name="AllowWindowsStorage" value="false|true|no|yes" />
    <param name="AllowFileStorage" value="false|true|no|yes" />
    <param name="AllowTokenStorage" value="false|true|no|yes" />
    <param name="Color" value="color value in form #RRGGBB" />
    <param name="Token" value="token name" />
</applet>

Mandatory parameters

Data- this parameter contains a signature request. This request is produced by TElDCAsyncState or TElDCAsyncStateCollection classes (as an XML document) and must be Base64-encoded before embedding into the web page. There are two parameters available to return signed data back to the server:

The DataURL parameter specifies the URL where the signed data to be posted to.
The GoURL parameter specifies the URL where the browser has to be navigated to after the data is posted.

If no DataURL parameter is provided, the signed data is returned using the query part of the URL from the GoURL parameter (see below).

Additionally one of the below parameters must be included:

DataURL - this parameter provides an absolute or a relative URL to be used to post the signed data back to the server. The signed data is posted back to the server using TElHTTPSClient component, so no cookies or other things from the browser will be available in that HTTP request. The only way to identify the original session or document on the server is to use the SessionID parameter. The value of this parameter (if it is provided in the web page source) is included without any change to the query part of the URL. If there are other parameters available in the DataURL value, they are not affected in any way and the SessionID parameter will be added to the end of the existing query part. The Content-Type field of the POST request is set to application/xml.
```
POST /<path from DataURL>?sessionid=unique-text HTTP/1.1
Host: <host name from DataURL>
Content-Type: application/xml
...
```
The Java applet expects status code 200 to be returned from the server. All other status codes are reported to the user as an error.
GoURL - this parameter provides an absolute or a relative URL to be used to navigate the browser to after the data is signed. If no DataURL parameter is included in the web page, the signed data is returned as a query parameter named data. In this case, the signed data is Base64-encoded.
The value of the SessionID parameter is used in the same way, as described for the DataURL parameter. If there are other parameters available in the DataURL value, they are not affected in any way, and the sessionid parameter will be added to the end of the existing query part.

Optional parameters

SessionID - this parameter should contain a text string which helps to determine the signing session or the pre-signed document on the server where the control returns the signed data back to the server. The value of this parameter is not changed and just added to the query part of the URL(s) provided by the DataURL and GoURL parameters.
AllowFileStorage - the parameter specifies if the user is allowed to use certificates loaded from files. Possible values are true or yes to allow the user to load certificates from files, and false or no to disable this. If the parameter is not specified, the user is allowed to use certificates from files.
AllowWindowsStorage - the parameter specifies if the user is allowed to use certificates from the Windows system certificate storage. Possible values are true or yes to allow the user to use certificates from the Windows certificate storage, and false or no to disable this. If the parameter is not specified, the user is allowed to use certificate from the Windows certificate storage.
If the applet is running on Windows platform and there is at least one certificate with private key exists in the Windows Certificate Storage, the option will be enabled. On all other platforms or if there is no certificate with private key in the storage the option will be disabled.
AllowTokenStorage - the parameter specifies if the user is allowed to use keys from security tokens and smart cards. Possible values are true or yes to allow the user to use keys from security tokens and smart card, and false or no to disable this. If the parameter is not specified, the user is allowed to use security tokens and smart cards.
Color - the parameter specifies the background color of the applet in HTML style: #RRGGBB. If the parameter is not specified the applet will be of WHITE color.

How To articles about Distributed Cryptography add-on.

Discuss this help topic in SecureBlackbox Forum