Digi-Seal™ Server Manual

Using Digital Signatures to Sign Online Forms & Files

For signing on line, or browser based, transactions Digi-Seal™ Server is the perfect solution. The thin client applet is automatically downloaded to the browser and is a 'one time only' action that occurs seamlessly without any prior knowledge or action on the part of the end user. Once the Digi-Seal™ applet is activated, the user can sign forms and file uploads using their personal digital signature [1].

There are two options with Digi-Seal™:

[2]

See the online demo [3]

If the user is submitting a file or form and wants to digitally sign it, they select the "Digitally Sign File" button. Again, the Digi-Seal™ applet will automatically select the correct certificate for the specific user and digitally sign the file before submitting it.

Digi-Seal™ provides javascript(s) that your web site designers will place on each form so that the functions will work correctly. Whenever any of the buttons on the forms are selected, the Digi-Seal™ applet will automatically select the correct certificate for the specific user and digitally sign the file before submitting the form.

How it Works

How the Digi-Seal™ Applet Works

[4] The framework is intended to implement the following scenario:

User accesses a Web application

User completes the Web form (which could contain files for uploading)

User clicks a “Sign” button and request signing of the Web form (all its text fields and files for upload or either of the above). Here the signing applet is invoked

The applet creates a XML document containing all the Web form data: all form fields and their corresponding values and all electronic files selected for uploading and their binary contents (encoded as Base64 strings). The signature of the Web form is computed by digitally signing this XML document.

Then a dialog is shown, prompting the user to selects a PKCS#12 file which contains a private key and corresponding public key certificate

The applet uses the user's private key and public key certificate to generate a signature of the completed Web form and stores the result in a PKCS#7 SignedData object. The result PKCS#7 object contains:

The applet encodes the calculated PKCS#7 object using the Base64 algorithm and stores the result string in one of the Web form fields

The form (along with all files for uploading and the calculated signature) is submitted to the Web server

A server side application processes the form by verifying the signature and optionally storing the form data and its corresponding signature in a SQL database

System Details

About the Applet

[4] The Web Forms Signer Applet is a Java based client side component running inside a Web browser which digitally signs Web forms and Electronic Files with a private key and public key certificate stored in a PKCS#12 compliant keystore file.

The applet digitally signs (at the client side in a Web browser) the fields of given Web form (including any files for uploading as part of the form) and produce a single digital signature as a result

The computed form digital signature is a PKCS#7 SignedData object encoded as Base64 string that is inserted into one of the Web form custom fields and posted to the Web server along with the entire form. The name of the custom field storing the computed PKCS#7 SignedData object should be configurable as an applet external parameter

For the purpose of digital signing the Web form, the applet uses the private keys and public key certificates from a PKCS#12 compliant file

The applet supports signing of 3 types of Web forms:

Web forms with one or more data fields: text fields, drop downs, radio buttons, check boxes, text areas, etc.

Web forms with one or more electronic files for uploading

Web forms with mixed content (data fields and electronic files)

During the signing process the file(s) contents should be signed (not their file path and file name). The file format is ignored and all files are considered as binary data

The only supported form character encoding is UTF-8

Requirements

What is needed to use with Digi-Seal™

[4] The Web Forms Signer Applet generally requires a standard Web browser that supports Java applets but has some specific requirements described below.

Requirements for Running the Applet

Supported Web Browsers

The applet supports the following platforms and Web browsers:

Known Incompatibilities

Using Digi-Seal™

Using the Digi-Seal™ Applet

[4] This section describes how to use the applet (Screenshots are on Mozilla Firefox 3).

You must access a Web application form (see online demo [5])

If a pop-up warning security dialog appears you must to choose “Run” to give permission to the applet (this can be avoided by purchasing a Digi-Code™ [6] software signing certificate and signing the applet)

You have to complete the Web form (which could contain files for uploading)

If form contains files to upload you must click “Browse” button and navigate to file. If there is terms and conditions check the checkbox

Click a “Sign” button. Here the signing applet is invoked

Will pop-up dialog window, where you must select certificate keystore file by browsing to him. Then enter the password for your private key and click “Sign” button.

The applet uses the user's private key and public key certificate to generate a signature of the completed Web form and stores the result in a PKCS#7 SignedData object. The result PKCS#7 object contains:

The applet encodes the calculated PKCS#7 object using the Base64 algorithm and stores the result string in one of the Web form fields

When click “Submit” button the form (along with all files for uploading and the calculated signature) is submitted to the Web server

A server side application processes the form by verifying the signature and optionally storing the form data and its corresponding signature in a SQL database

The Keystore

The Certificate Keystore Choosing Dialog

[4] When you click on the “Sign” button, a pop-up dialog window with two fields appears.

In first field you must navigate to certificate keystore file using “Browse” button.

Then in second field you must enter your certificate keystore password and click “Sign”.

If there are no problems the signature will be printed in field of the forms in string format. In other cases, an error message will be displayed.

Common Issues

Common Issues with Digi-Seal™

Applet is not loaded
[4] If applet is not loaded you must check does your browser have installed Java Plug-In JDK 5.0 or later. Or in browser security settings you must give permissions to this applet. If have no this plug-in in your browser download and install it. Or edit security settings of your browser to allow execution of applet.

Can Not Execute Signed Applet

If can not execute applet probably you are click “Cancel” on Warning – Security dialog and don’t want to run this application. Or your browser security settings don’t allow Signed Applet to be executed.

To solve this problem you must restart your browser or edit security settings of your browser to allow execution of applet.

Invalid Keystore or Password is specified

When can not read certificate message is shown, the file that you are selected as certificate keystore is not in PKCS#12 format (.P12 or .PFX) or is corrupted or the password is invalid.
Then check is selected file the corrected certificate keystore or is his certificate valid or you are entering not valid password for this certificate.

Applet Causes JavaScript Error

If applet causes java script error probably the form is incorrect and must send message to website support team to solve this problem.

Applet Causes the Web Browser to Crash

If applet causes the web browser to crash then you must preinstall the browser or the java plug-in.

Applet Causes the Web Browser to Crash

If applet runs too slowly you probably try to upload large file. Or performance of your PC is not too high.

Developers Guide

Information for Developers using Digi-Seal™

[4] As described, the Web Forms Signer Applet is a Java based client side component running inside a Web browser which digitally signs Web forms and Electronic Files with a private key and public key certificate stored in a PKCS#12 compliant keystore file.

With the standard resources of HTML and JavaScript we cannot sign client files in Web browser. This is a problem of web technology that has no standardised solution that can be supported by all web browsers. JavaScript does not support functionality for working with digital signatures and certificates and can not access either the user certificates installed on a web browser, nor external storage for keys and certificates.

There are some solutions:

One possible solution to sign documents in the user's machine is any user to install the specialized software. This could work well but there are some problems:

There is also a problem with the maintenance of keystores for different types of certificates - PFX files, smart cards, etc. In different operating systems access to such repositories it differently. Any change in the software will cause all users to download and install the correct version. If consumers are many, this may prove a serious problem.

The software for signature must have separate versions for different operating systems, which the consumer could use. This is not always an easy task, especially if it is to support a large number of different platforms

There is also a problem with the support of storage for different types of certificates - PFX files, smart cards, etc. In different operating systems access to such repositories is differently

The integration of software with such a web interface system is not an easy task, especially if it is to maintain various web browsers. If external software for signing the documents is not well integrated with the Web system its use would be inconvenient for the user

The computed form digital signature is a PKCS#7 SignedData object encoded as Base64 string that is inserted into one of the Web form custom fields and posted to the Web server along with the entire form. The name of the custom field storing the computed PKCS#7 SignedData object should be configurable as an applet external parameter

For the purpose of digital signing the Web form, the applet uses the private keys and public key certificates from a PKCS#12 compliant file

The applet supports signing of 3 types of Web forms:

Web forms with one or more data fields: text fields, drop downs, radio buttons, check boxes, text areas, etc.

Web forms with one or more electronic files for uploading

Web forms with mixed content (data fields and electronic files)

Use of ActiveX controls in Internet Explorer. ActiveX controls are Windows components, COM-based technology, which implement some functionality, have their own graphical user interface and may be build in to web pages and then run inside pages [MSDN ActiveX].

With them it is not a problem to access the certificates repository of Windows and Internet Explorer (so called Windows Certificate Store) for instance using the standard Windows library CryptoAPI or with the CAPICOM component.
ActiveX controls can decide a technical problem, but they are not platform independent – support only for Windows platform.

In the Windows environment, if you use Microsoft Internet Explorer, can be installed ActiveX control CAPICOM. It represents COM cover of Microsoft CryptoAPI and is object model and provides access for cryptography functionality of Windows.
Once installed, CAPICOM it can be used in VBScript to sign the text data such as web forms but there are some problems.

The most serious of them is that the technology works only with Windows-based Web browser Microsoft Internet Explorer. Under other operating systems and Web browsers CAPICOM is not available. An additional requirement is the need to install a single CAPICOM ActiveX control on the client machine, which may create difficulties.
Another problem is that in order to sign a file, it must be read and VBScript does not allow access to the file system

Use of method crypto.signText() in Netscape and Mozilla.

In the new versions of Web browsers Mozilla and Netscape have incorporated functions to sign the text. They support JavaScript function crypto.signText(text, certificateSelectionMode) which signed a digital string. Advantage of this technology is that does not require installing any additional software.

The main problem of this technology is that works only with web browser Mozilla and Netscape (under all platforms, which are available - Linux, Windows, Solaris, etc.). But not supported by Internet Explorer.

The other problem is that in order to sign the file, it must be read and this can not happen with JavaScript. For that reason these technologies may be signed only web forms or parts of them, but not files.

Java applet

Java applets are extensions of standard Web technologies and have the advantage that can work in all popular web browsers and all operating systems.

Java applets are the only technology that can decide on platform-independent way the problem with digital signing of documents in a user‘s web browser.

To read more and for a comprehensive understanding of the Digi-Seal™ application, how to use and configure it, download the Digi-Seal™ Manual [4]

Installation Guide

3 Simple Steps

Converting your online forms to forms that will have legal value is simple with Digi-Seal™. There are three simple steps to getting Digi-Seal&trade active on your electronic forms (and you can probably implement these in a few hours):

The simplicity of the implementation means that you can have digital signature capability on your forms in a matter of hours. You don't need to send data outside your network and you continue to retain total control of your forms and business processes.

Order Digi-Seal™ >> [7]

Read each step in more detail below

Step 1 - Ordering the Digi-Seal™ Applet

Number of Users

Digi-Seal™ enables users to sign any online form, or file upload. In order to use the Digi-Seal™, the user must first have their own digital signature certificate [Digi-ID™ [1]].

The simplest way to get each user their digital signature is to use the Total Trust Management™ [8] service. Or you can use the Digi-CA™ [9] system and issue the certificate yourself.

Either way, when placing your order [7], you should decide on the approximate number of people you want to use your online forms.

Step 2 of 3 >> [10]

Step 2 - Edit/Create Forms

Modify/Create your Web Forms

To run the Web Forms Signer Applet you need the following files:

Embedding the Applet in a HTML Page

For the applet to work with the most popular browsers (IE, Mozilla, etc), your web developer should follow these guidelines:

Using a combination of <object> and <embed> tags. You should note the following:

Internet Explorer

Recognizes the <object> tag

Ignores the contents of the <comment> tag

Mozilla browsers

Ignore an <object> tag with the classid attribute

Interpret the contents of the <comment> tag

Add the <applet> tag

The sample HTML pages [11] shows how to embed the applet in a HTML form using the tag <applet> in the first example, and a combination of <object> and <embed> tags in the second example.

You can also 'view source' on the Digi-Seal™ online demo [3]

Step 3 of 3 >> [12]

Step 3 - Install the Digi-Seal™ Applet

Upload the Applet

Simply place the WebFormSignerApplet.jar in the same direcotry as the forms and you're done.

Order Digi-Seal™ >> [7]

Digi-Seal™ Sample HTML Code

Sample HTML code using <applet> tag

An example of a HTML page (Web form) referencing the Web Form Signing Applet is given below. In this example the applet is embedded into the Web form with the <applet> tag.
<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Personal Data Form</title>
</head>

<strong>Personal Data Form</strong>

First name: <input name="textBoxFirstName" type="text" />

Last name: <input name="textBoxLastName" type="text" />

Gender:
<select name="dropDownListGender">
<option value="Male">Male</option>
<option value="Female">Female</option>
</select>

Marital status:
<input type="radio" name="radioMaritalStatus" value="Single" />Single<br />
<input type="radio" name="radioMaritalStatus" value="Married" />Married<br />
<input type="radio" name="radioMaritalStatus" value=" Divorced" />Divorced<br />

Comments:
<textarea name="textAreaComments" rows="2" cols="20"></textarea>

Upload CV (file upload):
<input type="file" name="fileUploadCV" />

<input type="checkbox" name="checkBoxTermsAgree" />
<label for="checkBoxTermsAgree">I agree to the terms and conditions</label>

<applet
code="com.digisign.applet.WebFormSignerApplet"
archive="WebFormSignerApplet.jar"
width="150"
height="30"
mayscript="true"
signButtonCaption="Sign form"
inputForm="formPersonalData"
ignoredFields="xml"
textBoxFormFieldsXML="xml"
outputForm="formSignature"
textBoxPkcs7Signature="textBoxPkcs7Signature"
maxFileSize="1"
debugMode="false">WebFormSignerApplet
</applet>

XML for signing (built from the form fields):
<textarea name="xml" style="height: 130px; width: 390px;"
readonly="true" wrap="off"></textarea>
</form>

<br/>

<strong>Signature Form</strong>

PKCS#7 Signed Data (the result of signing):
<textarea name="textBoxPkcs7Signature" style="height: 130px; width: 390px;"
readonly="true" wrap="off"></textarea>

</form>

</body>
</html>

Sample HTML code using <applet> tag

An example of a HTML page (Web form) referencing the Web Form Signing Applet is given below. In this example a combination of <object> and <embed> tags is used.

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Personal Data Form</title>
</head>

First name: <input name="textBoxFirstName" type="text" />

Last name: <input name="textBoxLastName" type="text" />

Gender:
<select name="dropDownListGender">
<option value="Male">Male</option>
<option value="Female">Female</option>
</select>

Comments:
<textarea name="textAreaComments" rows="2" cols="20"></textarea>

Upload CV (file upload):
<input type="file" name="fileUploadCV" />

<input type="checkbox" name="checkBoxTermsAgree" />
<label for="checkBoxTermsAgree">I agree to the terms and conditions</label>

XML for signing (built from the form fields):
<textarea name="xml" style="height: 130px; width: 390px;"
readonly="true" wrap="off"></textarea>

</form>

<br/>

<strong>Signature Form</strong>

PKCS#7 Signed Data (the result of signing):
<textarea name="textBoxPkcs7Signature" style="height: 130px; width: 390px;"
readonly="true" wrap="off"></textarea>

</body>
</html>

Note:- Some web browsers will allow the applet to run JavaScript and to access the HTML document, but only if this is explicitly set by the parameters or attributes of the tag by which it is embedded in the web page. Such parameters are “mayscript” and “scriptable”, and they must have value “true”.