Secure your IBM Lotus Forms-based application with digital signatures

In this article, learn how to use digital signature technology to prevent tampering during transmission. Follow the example provided in this article to design the form, sign the form, and verify the signature.

Share:

Xiao Jun Zhang (xjzhang@cn.ibm.com), Staff Software Engineer, IBM

Xiao Jun Zhang is a Staff Software Engineer, leading the IBM Lotus Forms test team in the IBM China Software Development Laboratory in Beijing. You can reach him at xjzhang@cn.ibm.com.



Kai Feng Zhang (zhangkf@cn.ibm.com), Software Engineer, IBM

Kai Feng Zhang is a Software Engineer in the IBM China Software Development Laboratory in Beijing. He focuses on IBM Lotus Forms Web form server testing. You can reach him at zhangkf@cn.ibm.com.



Jie Yang (yangjcdl@cn.ibm.com), Software Engineere, IBM

Jie Yang is a Software Engineer in the IBM China Software Development Laboratory in Beijing. She focuses on IBM Lotus Forms Designer testing. You can reach her at yangjcdl@cn.ibm.com.



04 November 2008

Security is always a key concern for an application, especially for those that use forms to capture data for making decisions. IBM® Lotus® Forms supports industry-standard digital signature technology that makes it possible to keep the data contained in a form and the form itself secure from tampering during transmission. This solution illustrates an end-to-end approach including designing the form, signing the form, and verifying the signature.

Figure 1. Solution diagram
Solution diagram

Let's look at figure 1 in more detail.

  • Designer. Install Lotus Forms Designer here; you can create the form here. For more information about Lotus Forms Designer installation, refer to the Lotus Forms Information Center.
  • Viewer signer. Install Lotus Forms Viewer here; you can sign the form here. The user's digital certificate needs to be installed on this system, and the instructions for doing so are described later in this article. For more information about Lotus Forms Viewer installation, refer to the Lotus Forms Information Center.
  • Web form signer. Install Microsoft® Internet Explorer here; you can also sign the form here. The user's digital certificate must be installed on this system, and the instructions for doing so are described later. The Web form signer can share the same physical system with Viewer Signer.
  • Viewer signature verifier. Install Lotus Forms Viewer here; you can verify the signed form here. The root certificate must be installed on this system, and the instructions for doing so are described later. For more information about Lotus Forms Viewer installation, refer to the Lotus Forms Information Center.
  • Web form signature verifier. Install Internet Explorer here; you can verify the signed form here also. No certificate needs to be installed on this system because the signature verification is done on the server side.
  • Web form server. Install Lotus Forms Web form server; you can store and process all forms here. The root certificate needs to be installed on this system, and instructions for doing so are described later. For Lotus Forms Web form server installation, refer to the Lotus Forms Information Center.

Preparation

Lotus Forms supports a number of different signatures. In this solution, we use the PKI-based digital signature because it is reliable and widely used. To sign a form, you need a digital certificate. Generally, the certificate is issued by a certificate authority (CA). Certificate authorities do occasionally offer short-term certificates for testing purposes. Contact the certificate authority of your choice to ascertain whether it offers short-term certificates. In this article's example, we applied a testing certificate from Thawte. You can also apply for your IBM certificate.


Installing the user certificate on the viewer signer

Before you can sign a form, the user digital certificate must be installed on the system. You can install the certificate on two certificate stores: Internet Explorer certificate store and Mozilla Firefox certificate store. You can choose either of these two approaches.

To install the user digital certificate into the Internet Explorer certificate store, follow these steps:

  1. Double-click the certificate file (usually it is a file with the extension .p12).
  2. The Certificate Import Wizard window displays as shown in figure 2.

    Figure 2. The Certificate Import Wizard
    The Certificate Import Wizard
  3. Click Next.
  4. Enter the file name and its location in the File name field. You can browse to select the file name. Click Next.
  5. In the Password field, enter the password that protects the private key. Usually the password is set when you apply the certificate. Click Next.
  6. If it is not already selected, select the default setting, Automatically select the certificate store based on the type of certificate. Click Next.

    Figure 3. Completing the Certificate Import Wizard
    Completing the Certificate Import Wizard
  7. Confirm the certificate settings that display in the window shown in figure 3. Click Finish to import the certificate.
  8. A Security Warning displays. Click Yes.
  9. A window displays that states "The import was successful." Click OK.

You can view the certificate that you imported. Launch Internet Explorer, and then select Tools - Internet Options. Select the Content tab, and then click the Certificates button, as shown in figure 4. A window displays that lists your certificates.

Figure 4. The Content tab
The Content tab

Installing the user digital certificate in the Firefox certificate store

To install the user digital certificate in the Firefox certificate store, follow these steps:

  1. Launch Firefox, and then select Tools - Options.
  2. Click Advanced, and then select the Encryption tab as shown in figure 5.

    Figure 5. Encryption tab
    Encryption tab
  3. Click the View Certificates button. The Certificate Manager window shown in figure 6 displays.

    Figure 6. Certificate Manager
    Certificate Manager
  4. Click Import, and select the certificate file.
  5. Enter the password that protects the private key. Click OK.
  6. A window displays that shows this message: "Successfully restored your security certificate(s) and private key(s)." Click OK.

Your certificate is listed as shown in figure 7.

Figure 7. List of certificates in Certificate Manager window
List of certificates in Certificate Manager window

Installing the user certificate on the Web form signer

You also need to install the user digital certificate before you can sign a form using the Web form server. The steps are the same as described in the "Installing the user certificate on viewer signer" section, but you need to import the user certificate into the Internet Explorer certificate store. If you use the same system and the user certificate is already in the Internet Explorer certificate store, skip the steps to install the user digital certificate.

NOTE: Firefox is not supported to sign a form in the Web form server, so do not install the user certificate on Firefox.


Installing the root certificate on the viewer signature verifier

To verify the signed form, install the root certificate of the certificate authority that issued the user certificate used to sign the form on the system on which the viewer is running. You can also install the root certificate in the Internet Explorer certificate store or the Firefox certificate store. You can choose either of these two approaches.

To install the root certificate in the Internet Explorer certificate store, follow these steps:

  1. Launch Internet Explorer, and then select Tools - Internet Options.
  2. Select the Content tab and click Certificates.
  3. In the Certificates window that displays, click Import. The Certificate Import Wizard opens. Browse to the root certificate file, which is usually a file with the extension .crt. Click Next.
  4. Click Browse to see a list of your certificate stores as shown in figure 8. Select the Show physical stores option.

    Figure 8. Select Certificate Store window
    Select Certificate Store window
    Figure 9. Selecting the certificate store
    Selecting the certificate store
  5. Select Trusted Root Certificate Authorities - Registry as shown in figure 9. Click OK.
  6. The Certificate Import Wizard shown in figure 10 displays. Make sure that the location selected for the certificate shown in this window matches the location that you selected in the previous step. See figure 10. Click Next.

    Figure 10. Certificate location
    Certificate location
    Figure 11. Confirming the certificate settings
    Confirming the certificate settings
  7. Confirm the certificate information that displays in the Certificate Import Wizard window as shown in figure 11, and then click Finish.
  8. A window displays that states "The import was successful." Click OK.

To install the root certificate into the Firefox certificate store, follow these steps:

  1. Launch Firefox, and then select Tools - Options.
  2. Click Advanced, and then select the Encryption tab.

    Figure 12. The Encryption tab
    The Encryption tab
  3. Click the View Certificates button as shown in figure 12.
  4. In the Certificate Manager window that displays, click the Authorities tab.
  5. Select the root certificate file and click Import.

    Figure 13. Downloading Certificate window
    Downloading Certificate window
  6. In the Downloading Certificate window that displays, select the following options as shown in figure 13:
    • Trust this CA to identify web sites.
    • Trust this CA to identify email users.
    • Trust this CA to identify software developers.
  7. Click OK.

The certificate is imported successfully.


Installing the root certificate on the Web form server

To verify the signed form in the Web form server, iinstall the root certificate of the CA that issued the user certificate used to sign the form on the system on which the Web form server is running. The steps are the same as described in the "Installing the root certificate onthe viewer signature verifier" section, but you have to import the root certificate into the Internet Explorer certificate store.

NOTE: Firefox is not supported to verify a signed form in the Web form server, so do not install the root certificate on Firefox.


Designing a form with digital signature capability

With Lotus Forms Designer, you can easily create a form with digital signature capability. You can design each signature to sign a certain portion of the form by setting a series of signature filters. The signature filters specify which parts of the form a particular signature signs using either keep or omit filters.

Follow these steps to create a digital signature with Lotus Forms Designer:

  1. Launch Lotus Forms Designer (if it is not already running), and open the SampleForm.xfdl form in the attachment. The form contains a Sign Here button as shown in figure 14.

    Figure 14. The Personal Information window
    The Personal Information window
  2. Click Sign Here, select the Properties View, and set the button’s type to signature.
  3. Right-click the button and select Signature Wizard from the context menu.

    The Signature Wizard launches. In the first step, you are asked whether the signature signs the complete form or parts of the form. See figure 15.

    Figure 15. Step 1 of the Signature Wizard
    Step 1 of the Signature Wizard
  4. If you choose to sign the complete form, you are asked to select a type of signature in step 2. Select one option from this list:

    • Generic RSA
    • Crypto API
    • Clickwrap
    • Authenticated Clickwrap
  5. Click Finish to create a signature button.

If you chose to sign parts of the form on the first step, you are asked to define whether the signature filters keep or omit items. The keep filter lets you specify the items that you want to sign; the omit filter lets you specify those items that you do not want to sign. The omit filter is used as a better practice because it provides greater security. The omit filter can prevent you from accidentally excluding items that should be signed and from adding items after it is signed.

To create a digital signature with Lotus Forms Designer using the omit filter, follow these steps:

  1. Select the Items not to sign option in step 1 of the Signature Wizard. Click Next.
  2. Select the pages not to be signed by the signature. See figure 16. In this example, we do not want to omit the entire page, so click Next. See figure 16.

    Figure 16. Using the omit filter
    Using the omit filter
  3. Then you can specify the items not to sign using the controls. For example, to move all items from Signed to Not Signed, click the >>> button; to move individual items from Signed to Not Signed, select the items from the list and click >. You can also use the hand pointer button shown in figure 17 to select items from the canvas. Click Next when you finish this step.

    Figure 17. Using the hand pointer button
    Using the hand pointer button
  4. As you did previously, select a type of signature. In this solution, we are working with a PKI-based digital signature, so select Generic RSA and click Finish.

You have successfully created the form with a digital signature capability. Next ,we test signing the form in the Lotus Forms viewer and the Web form server.


Deploy the designed form to the Web form server

After the Web form server is installed on your system, it can provide a sample Web form Web application automatically. The default access URL is: http://yourservername:8085/Samples/FormListServlet.

You want to deploy the designed form above to the sample application, so that you can see it from the client browser and open it with the viewer or the Web form server.

You can put the form into the following destination directory on the Web form server:

WebSphereProfileFolder\installedApps\ProfileName\WebformSampleApp.ear\Samples.war\SampleForms

An example for this location can be:

E:\IBM\WebSphere\profiles\wp_profile\installedApps\lwpcn\WebformSampleApp.ear\Samples.war\SampleForms

Return to the client, and open either Internet Explorer or Firefox with the provided access URL for the sample. The default page should be look like the one shown in figure 18.

Figure 18. Default page
Default page

Clicking the icon on the left arrow icon opens the form with the viewer.

Clicking the icon on the right circle icon opens the form with the Web form server.


Signing the form

Make sure that the user certificate is imported successfully before you perform the steps that follow.

Signing a form in the forms viewer

To sign a form in the forms viewer, follow these steps:

  1. Launch Internet Explorer or Firefox, and enter the URL of the list form servlet on the Web form server.
  2. Navigate to the form that you want to sign.
  3. Click the button showing the arrow to open the form with the viewer.
  4. Enter the data, then click the Add Signature button to sign the form.
  5. In the Digital Signature Viewer window shown in figure 19, click Sign.

    Figure 19. Digital Signature Viewer window
    Digital Signature Viewer window
  6. Click Sign to sign the form with your imported user certificate.
  7. Click OK to lock all fields. You cannot change any of the fields now.
  8. Click Submit to submit the signed form to the server.

You open the signed form and verify the signature on other systems with both the viewer and the Web form server later.

Signing a form in the Webform Server

Make sure that the user certificate is imported into the Internet Explorer certificate store successfully before you perform the steps that follow. Firefox is not supported to sign a form in Webform Server.

To sign a form in the Webform Server, follow these steps:

  1. Launch Internet Explorer.
  2. Navigate to the form that you want to sign.
  3. Click the button showing a circle to open the form with the Web form server. You are prompted to install the ActiveX control of the WebformSignatures plug-in application. Select trust and install.
  4. Enter the data, and then click Add Signature to sign the form.
  5. Click Sign. The form is signed with your user certificate imported as shown in figure 20.

    Figure 20. Signing the form
    Signing the form
  6. Click OK to lock all fields.
  7. Click Submit to submit the signed form to the server.

We open the signed form and verify the signature on other systems with both the viewer and the Web form server later.


Validating the signed form

The signed form can be verified in both the viewer and the Web form server no matter where it is signed. This feature is important because it gives users the flexibility to choose the product that they use to sign and verify forms. Users do not have to worry about cross-verification issues; they can sign once, verify everywhere.

Validating the signed form in the forms viewer

Make sure that the root certificate is imported successfully before you perform the steps that follow.

To validate the signed form in the Forms Viewer, follow these steps:

  1. Launch Internet Explorer or Firefox, and enter the URL of the list form servlet on the Web form server.
  2. Navigate to the form that you signed with the viewer.
  3. Click the button with the arrow to open the form with the viewer.
  4. Click the Signature button to validate the signature. Figure 21 shows the window that displays.

    Figure 21. Valid signature information
    Valid signature information
  5. Navigate to the form that you signed with the Web form server.
  6. Click button with the arrow to open the form with the viewer.
  7. Click the signature button. You can see that the signature is still valid. Click OK.

Validating the signed form in the Web form server

Make sure that the root certificate is successfully imported into the Internet Explorer certificate store on the system where the Web form server is running before you perform the steps that follow. Firefox is not supported to verify a signed form in Webform Server.

To validate the signed form in the Webform Server, follow these steps:

  1. Launch Internet Explorer. Enter the URL of the list form servlet on the Web form server.
  2. Navigate to the form that you signed with the Web form server.
  3. Click the button showing a circle to open the form with the Web form server.
  4. Click the Signature button. You can see that the signature is valid.
  5. Navigate to the form that you signed with the viewer.
  6. Click the button showing the circle to open the form with the Web form derver.
  7. Click the Signature button. You can see that the signature is still valid.

Validating a signed form that has been tampered with

Let's see what happens if the form is tampered. Open the signed form in a text editor and make a modification, then save your updated version.

Validating a signed form that is tampered with in the viewer

Follow these steps:

  1. Launch Internet Explorer or Firefox, and enter the URL of the list form servlet on the Web form server.
  2. Navigate to the tampered form.
  3. Click the button showing an arrow to open the form with the viewer.
  4. A window opens showing the message "An error has occurred" to let you know that the digital signature is not valid. Click Close.
  5. Click the Signature button. You can see that the signature is invalid.

Validating a signed form that has been tampered with in the Web form server

Follow these steps:

  1. Launch Internet Explorer , and enter the URL of the list form servlet on the Web form server.
  2. Navigate to the form that has been tampered with.
  3. Click the button showing a circle to open the form with the Web form server.
  4. A window opens that shows the message "One or more digital signatures are invalid." Click OK.
  5. Click the Signature button. You can see that the signature is invalid.

Conclusion

In this article, you learned how to ensure that your forms are secure using Lotus Forms products and digital signatures. This article describes a business scenario that involves applying the security mechanism within Lotus Forms; it also showed you how to install certificates into the viewer and the Web form server signer on different platforms, and the root certificate on the viewer and Web form server verifier. This article also demonstrated how to design a simple form that contains  signature capability in Lotus Forms Designer. Finally, it showed you how to sign forms and verify them (including tampered forms) with the viewer and the Web form server.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, Security
ArticleID=349587
ArticleTitle=Secure your IBM Lotus Forms-based application with digital signatures
publish-date=11042008