Developing a secured, non-repudiation IBM Lotus Forms solution with Authenticated Clickwrap signatures

In this article, learn how to use IBM Lotus Forms Authenticated Clickwrap signatures to provide a secured Lotus Forms offering.


Kiat Sing Lai, Advisory IT Specialist, IBM, Software Group

Kiat Sing Lai is an Advisory IT Specialist at the Developer Technical Support Center in Kuala Lumpur, Malaysia. He provides assistance to IBM Business Partners using IBM WebSphere Portal and IBM Lotus Forms through IBM PartnerWorld for Developers.

19 December 2008

Authenticated Clickwrap is one of the signature technologies in Lotus Forms. It uses a shared secret (such as a user ID and password) to verify the identity of the user. Therefore, for organizations that rely on user ID and password, Authenticated Clickwrap provides a simple yet secured signature solution for electronic forms. By using this technology, organizations can reduce the cost of implementing and maintaining the expensive Public Key Infrastructure (PKI).

NOTE: This article is written about Lotus Forms 3.0.1; however, the content applies to Lotus Forms 3.5 as well.


One of the aims of IBM Lotus Forms is to provide a secured, non-repudiation digital form solution through the use of digital signatures. IBM Lotus Forms supports several signature technologies such as Clickwrap, Signature Pad, and PKI/RSA signature. There are two types of Clickwrap signatures: Clickwrap and Authenticated Clickwrap. Both signature technologies are used to sign a form digitally. In general, users have to provide some information during the signing ceremony. After the signing ceremony, users click a button (for example, the Accept button ) to indicate that they accept the form. After the form is signed, no further changes are allowed on the form.

Clickwrap signature typically uses simple questions and answers to establish the identity of the signer. There is no verification of the signer's identity; therefore, it is considered a weak way of identifying a signer. The safeguard questions can be just the name and date of birth (DOB) of the signer, information that other people are likely to know. Insome situations, though, such as those in which identity verification isn’t important or in which other ways to verify the signer’s identity are available, using Clickwrap signature can be sufficient. For example, the form solution might be part of the WebSphere Portal solutions, which require users to log in. In that case, the solution can rely on WebSphere Portal to authenticate the signer.

Authenticated Clickwrap, on the other hand, provides additional features to verify signer identity. During the signing ceremony, the signer must enter a shared secret. This secret is known only to the user and to the system with which the user is interacting. An examples of a shared secret are user ID with password and credit card number with CVV/CVC code, which typically is a three-digit number printed on the credit card that is used for verification purposes. When the form is submitted to the system, matching is done by comparing the secret entered by the user with the secret stored in user registry or database. If the secret is matched, the server can countersign the form using available digital certificates. Therefore, providing a second-layer signature on the form confirm that the signer is valid. Authenticated Clickwrap is implemented with the help of the Lotus Forms API.

Scenario and overview of the solution

Let’s take a look the following scenarios:

Bank of IBM offers credit card services to its customers. One of its offerings is credit card balance transfer. Customers can use the credit card balance transfer form, downloadable from the Bank of IBM Web site, to submit an application for balance transfer (from a credit card issued by other bank) to their Bank of IBM credit card accounts.

To protect the interest of the bank and its customer, the form submitted by the applicant should never be tampered with in any way. The identity of the applicant should be verified to confirm that the signer is a valid Bank of IBM customer by comparing the secret with the one stored in Bank of IBM user database.

In this section, we take a look at the Authenticated Clickwrap signature, and we explore the processes and components that are involved. Note that this is not the only way of implementing an Authenticated Clickwrap signature solution, but it gives you a base from which you can start.

Figure 1 shows an example of an Authenticated Clickwrap solution.

Figure 1. Example of Authenticated Clickwrap Signature implementation
Example of Authenticated Clickwrap Signature implementation

The solution is divided into four major areas, and we discuss each of the processes. To complete the following section, you need a basic knowledge of XML, Lotus Forms, and XFDL. If you want to learn more about these topics, refer to the documentation listed in the Resources section of this article.

  1. Viewer / Webform server. A user fills out the credit card balance transfer form through either Lotus Forms Viewer or Lotus Forms Webform Server. The form contains a Signature button and a Submit button. As their names imply, the Signature button is used to initiate the signing ceremony while the Submit button is used to submit the signed form to the Bank of IBM back-end processing system. When the user clicks the Signature button, the signing ceremony wizard displays, requesting the user to enter the signer and the secret information. In this case, that is the customer user ID and password.

    The signing ceremony wizard has an Accept button; clicking this button indicates that the user has accepted the terms mentioned in the signature ceremony wizard. The process is similar to that of signing a paper-based application form, where the customer writes his or her name and places a signature on the paper to indicate acceptance of the terms and conditions. Two things happen when the user clicks the Accept button.

    • Within the form, a signature item <signature> is created. It consists of options related to the signature, such as signformat, signer, and signoptions.
    • Hash of the form and the user’s secret is created and stored in the signature item mimedata options <mimedata encoding=”base64-gzip”>.

    An example of the signature item is shown in figure 2. This item has a scope identifier (sid)“SIGNATURE_ID. We use this identifier to locate the signature information.

    Figure 2. The signature node
    The signature node
  2. Authentication module. The authentication module is the core of the Authenticated Clickwrap signature solution. This module works with a user database to handle the verification of the signature. In this article, we use a servlet to act as the authentication module. This servlet is deployed on WebSphere Application Server.

    Using the Lotus Forms API, the authentication module retrieves the form and looks for the signature item within the form. If the signature is found, the module checks to make sure the form has not been tampered with or thrown an exception. The server retrieves the signer ID from the signature item and passes it to the user database to retrieve the secret, in our case the user password. Using this password, the authentication module creates a signature hash and compares it to the hash stored in the original signature within the form. The hash matches only if the user provided the same secret; otherwise, an exception is thrown, indicating an invalid signature. The signature hash is generated using the secret word and the user’s ID. Because the secret word is not stored in the form, it avoids being a security issue. The system uses the user’s ID to retrieve the secret word from the user database to validate the signature.

    The largest barrier to using digital signatures is the cost associated with maintaining an extensive PKI system that issues certificates to all users. Authenticated Clickwrap signatures address this by reducing the number of digital certificates you need to one. When the signature is verified, the authentication module retrieves the list of certificates available on the server. The module selects the desired certificate and uses it to notarize the signature, thereby countersigning the signature. If you click the Signature button again, you see the message Signature Is Valid.

    To validate the signature, Lotus Forms provides two methods: validateHMACWithSecret() and validateHMACWithHashedSecret(). You choose the method to use depending on how the password is being stored in the user database: in clear text or in hashed format. For security reasons, storing the secret in clear text is not recommended.

    In this scenario, the password stored in the user database is in hashed format (using the SHA-1 hash algorithm); therefore, you use the validateHMACWithHashedSecret() method.

  3. User database. The user database is the place where the signer ID and the secret are stored. The database can be an LDAP database or any database in your legacy system. You might already have a user database in your environment that can be integrated easily. If you are implementing a user database in an entirely new environment, you need to plan before you decide which user database to use. User information must be secured in such a way that only the administrator and the user have access.

    In addition to that, the secret stored in the database should be hashed to prevent anyone from getting the actual password in clear-text form. Authenticated Clickwrap currently supports SHA-1 and MD5 hash algorithms. We use IBM Tivoli Directory Server as our user database. The directory is configured to use SHA-1 as the password hash algorithm. Instructions on setting this up are provided later in this article.

  4. Storage and further processing. The Authenticated Clickwrap signature typically is part of the total solution. Depending on the requirements, the form that has been signed and notarized can be routed to other systems for further processing. Take the balance transfer scenario as an example, where the form can be rerouted to another module to perform data extraction. The extracted data is then stored in the database to which the balance transfer application processor has access. It is also possible that the form is routed to a workflow system, for example, an approval workflow.

In this article, we store the signed and notarized form in a local file system.

Process walkthrough

You must have the following software installed:

  • Lotus Forms Designer 3.0.1. To create and design forms and the digital signature button.
  • Lotus Forms Viewer 3.0.1. To display and work on the form created in Lotus Forms Designer.
  • Rational Application Developer 7.0. The development tool for the Authentication Module with the WebSphere Application Server V6.0/V6.1 test environment.
  • Tivoli Directory Server 5.2 orlater. The user database to store usernames and passwords.

Form template

Throughout this article, we use a ready-made Credit Card Balance Transfer form as shown in figure 3. The form was created using Lotus Forms Designer 3.0.1 and has an Xform instance to carry the information collected by the form. You can download it from the Download section of this article. Figure 4 shows the Xforms instance used to carry the BalanceTransfer information.

Figure 3. Credit Card Balance Transfer form
Credit Card Balance Transfer form
Figure 4. Xforms instance to carry BalanceTransfer information
Xforms instance to carry BalanceTransfer information

Signature button

User clicks the Signature button to initiate the signature ceremony. Lotus Forms Designer provides a wizard to create the signature button. You set the attributes for the signature button by entering the required information requested in the wizard.

  1. Using Lotus Forms Designer, open the XFDL file you downloaded in the previous step.
  2. Right-click the Signature button and select Signature Wizard.
  3. The Signature button can sign parts of the form. For example, a signed form might need to go through an approval process. In that case, you need to have two signature buttons, one for the applicant and one for the approver. In this case, we sign the entire form. Select The complete form option, and click Next to continue.
  4. Lotus Forms supported signature technologies are presented. Select the Authenticated Clickwrap option, and click Next.
  5. Enter the Authenticated Clickwrap Signature details as shown in table 1. Remember that for each of the Authenticated Clickwrap signatures you have on a form, you need to have at least two safeguard questions. The first question usually asks for the unique ID of the signer, in our case the username. The second question asks for the secret that is known only by the signer, for example, the password.

    Using username and password is more straightforward and reliable in establishing the identity of the user because they are usually provided by your organization LDAP server. You can use other information such as signer and secret, for example, the credit card's number and the CVV/CVC code.

Table 1. Signature details
Field Value
TitleBalance Transfer
PromptPlease enter your Bank of IBM Username and Password
Main TextI authorize Bank of IBM to process this request. I confirm that I have read and agree to the Balance Transfer Terms and Conditions. I agree that I am responsible for the balance outstanding on my Bank of IBM credit card account as a result of this balance transfer.
Question 1Username
Question 2Password
  1. Click Finish.
  2. From the Lotus Designer Properties view, expand General - value - compute. Click the Open compute editor button as shown in figure 5.

    Figure 5. Signature button compute
    Signature button compute
  3. Change the text “Add Signature” to “Click Here To Sign” as shown in figure 6.. This is the string that is displayed on the signature button. Click OK to close the Compute Editor.

    Figure 6. Compute Editor
    Compute Editor
  4. Again, from the Properties view, expand the Signature node. If the Signature node cannot be seen, select the Show Advanced Options option. Change the value for the signature option to SIGNATURE_ID to tell Lotus Forms that the signature button is defined using the unique identifier of sid = “SIGNATURE_ID”. The Authentication Module, which you implement later, uses this identifier to locate the signature node. If you have multiple signatures within a form, make sure to use the appropriate sid. Otherwise, the signature button might sign an incorrect part of the form. See figure 7.

    Figure 7. Specifying the location of the authentication module
    Specifying the location of the authentication module
  5. In the form editor window, click the Submit Form To Server button.
  6. From the Properties view, expand General. Change the values as follows:
    • Change the type option to submit.
    • Change the url option to http://localhost:9080/AuthenticationModule/AuthenticationModule. This url is the URL of the Authentication Module servlet.
  7. Select File - Save.
  8. Preview the form by clicking the Viewer tab in the form editor. You must have Lotus Forms Viewer installed for this to work.
  9. Click the Click Here To Sign button.
  10. The Digital Signature Viewer windowdisplays. Click Sign.
  11. The Click-Wrap Signing Ceremony window displays as shown in figure 8. Note that you entered the title, prompt, and main text when you created the signature button. When you click Accept, the value for username (the signer ID) is appended within the form, and the value for password (the secret) is hashed together with the form. The hash is stored in the form signature item <signature>. At this time, do not enter any information.

    Figure 8. Clickwrap Signing Ceremony wizard
    Clickwrap Signing Ceremony wizard
  12. Close the Click-Wrap Signing Ceremony window.
  13. Close the Digital Signature Viewer window.
  14. Select File - Save As.
  15. Select C:\temp.

User database

You use the user database to store the signer (username) and secret (password). This section highlights some of the important LDAP configuration that you need to do to successfully complete this exercise. For information about installation and configuration of IBM Tivoli Directory Server, refer to documentation listed in the Resources section of this article.

Follow these steps:

  1. Start the IBM Tivoli Directory Server Configuration Tool by selecting Start - IBM Tivoli Directory Server 5.2 - Directory Configuration.
  2. From the task list panel, select the Administrator DN/password task.
  3. Enter the Administrator DN, Administrator password, and Confirm password as shown in table 2 The Administrator DN and password you specify here are used by the Authentication Module to look up the user secret stored in the LDAP configuration. Click OK to continue.
Table 2. Administrator DN and password value for Tivoli Directory Server
Field Value
Administrator DN/passwordcn=root
Administrator passwordpassw0rd
Confirm passwordpassw0rd
  1. Click the Manage suffixes task, add “dc=ibm, dc=com” to suffix DNs and click Add, then click OK to complete the configuration. See figure 9.

    Figure 9. Adding a Suffix DN
    Adding a Suffix DN
  2. Configure SHA-1 password encryption.

    Tivoli Directory Server allows you to prevent unauthorized access to the user password. As such, passwords can be encoded and stored in the directory, which prevents clear passwords from being accessed by anyone. The default encoding format used by Tivoli Directory Server is imask. We change the encoding format to SHA-1, which is supported by Lotus Forms – Authenticated Clickwrap. For detailed information about each of the encoding types, refer to the Tivoli Directory Server documentation.

    1. Using Microsoft WordPad, create a file with the name changeEncryption.txt.
    2. Copy and paste the code shown in listing 1 to the file. This file tells the ldapmodify command to change the ibm-slapdPWEncryption property value to sha (that is, the SHA-1 hash algorithm).

      Listing 1. Specifying sha as password encryption
      dn: cn=configuration
      changetype: modify
      replace: ibm-slapdPWEncryption
      ibm-slapdPWEncryption: sha
    3. Copy changeEncryption.txt to C:\temp.
    4. Open a command prompt and change the directory to the C:\temp folder.
    5. Execute the following command to change the password encryption format. If after you execute the command, the return value is ldap_simple_bind: Can’t contact LDAP server, remember to start the IBM Tivoli Directory Server V5.2 service.

      ldapmodify –D <adminDN> -w <adminPW> -f <filename>

      Figure 10 shows an example of the ldapmodify command.

      Figure 10. Example of ldapmodify command
      Example of ldapmodify command
    6. Using Microsoft Windows Explorer, go to <tds_root>\etc where <tds_root> is the root directory in which Tivoli Directory Server installed.
    7. Open the file ibmslapd.conf with a text editor such as Microsoft WordPad.
    8. Look for the property ibm-slapdPwEncryption. Make sure it is set to sha As shown in figure 11.

      Figure 11. Verify the password encryption algorithm
      Verify the password encryption algorithm

Now that you have changed the user password hash algorithm you can add sample users to the directory using the LDIF import tool available in the Tivoli Directory Configuration Tool. Follow these steps:

  1. Download the sample LDIF file (named setup.ldif) as shown in figure 12, and save it to C:\temp. This LDIF file adds two users to the LDAP. The value for the attribute userpassword is still in clear text. When these users are imported to the LDAP, the password is encoded using the encoding format SHA-1, which you set earlier.

    Figure 12. Sample LDIF
    Sample LDIF
  2. Make sure that Tivoli Directory Server service is stopped. You can check this from the Services panel on Microsoft Windows.
  3. From IBM Tivoli Directory Server Configuration Tool left panel, select the Import LDIF data task.
  4. Enter the Path and LDIF file name as C:\temp\setup.ldif as shown in figure 13. Accept the default settings for other fields.

    Figure 13. Import LDIF file
    Import LDIF file
  5. Click Import.
  6. In the Task messages panel, you get a message saying entries have been added successfully as shown in figure 14.

    Figure 14. Confirmation on LDIF import
    Confirmation on LDIF import
  7. Open a new command prompt.
  8. Execute the following ldapsearch command to validate the user entry.

    ldapsearch -h ldap://localhost -D "cn=root" -w passw0rd -b "dc=ibm,dc=com" "uid=david"

    If after executing the command, the return value is ldap_simple_bind: Can’t contact LDAP server, remember to start the IBM Tivoli Direcotry Server 5.2 service.

  9. You should get all the details about David as shown in figure 15. If this is not the case, verify your LDIF import steps again.

    Figure 15. Returned user details of ldapsearch lookup
    Returned user details of ldapsearch lookup
  10. Close the IBM Tivoli Directory Server Configuration Tool.

Installing the server certificate

The Authentication Module uses the server certificate to notarize the Authenticated Clickwrap signature on a form, or, in other words, to counter sign the form. Using this method, you can reduce the cost of maintaining certificates only one certificate on the server is needed to notarize all the forms instead of having one certificate for each user. The certificate can be obtained from a certificate provider such as VeriSign. If there is no certificate installed on the server where the Authentication Module resides, no notarization can be done, only signature verification.

For the purposes of this article, we have obtained a X.509 certificate issued by VeriSign (myCert.p12).

  1. Double-click the certificate to launch the Certificate Import Wizard, which installs the certificate to the browser. Click Next to continue.
  2. Click Browse to look for the certificate you have. In our case, it is located at C:\temp:

  3. Enter the password for the private key of the certificate. Leave the two checkboxes for the options unchecked.
  4. You are prompted to enter the location where the certificate will be kept. Click the radio button for the Place all certificates in the following store option.
  5. Click Browse.
  6. From the list of certificate stores that displays, select Personal. Click OK.
  7. It is important to install the certificate into the Personal store of the user that the WebSphere Application Server (where the Authentication Module resides) runs as, shown in figure 16. This is typically the system user. Click Next.

    Figure 16. Confirming the certificate store
    Confirming the certificate store
  8. Click Finish.
  9. Make sure that the certificate import successful message displays.

Authentication Module

Finally, we implement the Authentication Module, which is a servlet that we deploy to the WebSphere Application Server. This section explains the steps you can follow to create an Authentication Module servlet. It also explains the Java code in the servlet.

  1. Using Rational Application Developer, create a new Dynamic Web Project by selecting File - New - Project.
  2. Select Dynamic Web Project, and click Next.
  3. Enter information as shown in table 3, and click Finish. See figure 17.

    Figure 17. Project details and target runtime
    Project details and target runtime
Table 3. Specifying the directory administrator DN and password
Project nameAuthenticationModule
Project contentsUse default
Target RuntimeWebSphere Application Server V6.0 stub
EAR Project NameAuthenticationModuleEAR
  1. From the Project Explorer view, right-click AuthenticationModule, then select New - Servlet.
  2. Enter the data as follows (see figure 18):

    • In the Project field, enter AuthenticationModule.
    • In the Folder field, browse to select \AuthenticationModule\src.
    • In the Java package field, browse to select
    • In the Class name field, enter AuthenticationModule.
    • In the Superclass field, browse to select javax.servlet.http.HttpServlet.
  3. Click Finish.

    Figure 18. AuthenticationModule class file destination
    AuthenticationModule class file destination
  4. On the editor, replace the contents of the file with the contents of the AuthenticationModule.txt file. You can obtain this file from the download section. See figure 19.

    NOTE: Do not forget to add the external JAR files (pe_api.jar and uwi_api.jar) needed for the Forms Application (select Project - Properties - Java Build Path - Add External JAR). These JAR files are in the <forms_root>/Server/3.0/API/lib/java directory.

    Figure 19. Contents of file
    Contents of file

Let's walk through the Authentication Module:

  1. The first section of the Authentication Module is the import statements. The following code snippet, shown in listing 2, highlights some of the important classes required for LDAP access as well as the classes required by an application that uses Lotus Forms API.

    Listing 2. The import statements
    // For LDAP Access
    import javax.naming.Context; 
    // PureEdge classes
    import com.PureEdge.DTK; 
    import com.PureEdge.IFSSingleton;
    import com.PureEdge.xfdl.FormNodeP;
    import com.PureEdge.xfdl.XFDL;
    import com.PureEdge.IntHolder;
  2. Next, you initialize the API for the application called AuthenticationModule. This application is currently at version 1.0.0, and the API that the application should use is 7.5.0. See the code in listing 3.

    Listing 3. Lotus Forms API initializations
    public void init(ServletConfig config) throws ServletException 
    	try {
    		DTK.initialize("AuthenticationModule", "1.0.0", "7.5.0");
    	} catch (Exception e) {}
  3. The next section of the module receives the form submitted by the user (that is, when the user clicks the Submit Form To Server button). You first declare the XFDL object and use IFSSingleton.getXFDL to assign the XFDL object to the XFDL. This step allows you to access the root node of the form.

    You then call the readForm to load the forms into memory. You pass the input stream as the first parameter. The flag XFDL.UFL_SERVER_SPEED_FLAGS is used to turn off such features as computes, automatic, formatting. This step results in improved server processing times. See the code in listing 4.

    Listing 4. Accessing root node of the form
    try {
    	theXFDL = IFSSingleton.getXFDL();
    theForm = theXFDL.readForm(request.getInputStream(), XFDL.UFL_SERVER_SPEED_FLAGS);
    } catch (Exception e) {}
  4. Next,locate the signature node using dereferenceEx().you pass the reference type as FormNodeP.UFL_ITEM_REFERENCE to tell the API that you are looking for an item level node with sid SIGNATURE_ID and that this node is under a page with sid PAGE1. Therefore, you give the method your reference string PAGE1.SIGNATURE_ID.

    If the signature is found, use getLiteralByRefEx() to get the value for option signer. See the code in listing 5.

    Listing 5. Signature node lookup and retrieve signer ID
    if((theSignatureNode = theForm.dereferenceEx(null, "PAGE1.SIGNATURE_ID", 0, 
    FormNodeP.UFL_ITEM_REFERENCE, null)) == null)
    	System.out.println("Signature node NOT found!");
    } else {
    theSigner = theSignatureNode.getLiteralByRefEx(null, "signer", 0, null, null);
    	System.out.println("Signature found! Signer is " +theSigner);

    Refer to figure 20 for more details.
    • From the root node of the form, theForm, first look for page PAGE1.
    • Under PAGE1, look for an item with sid SIGNATURE_ID. The <signature> node is now known as theSignatureNode.
    • From theSignatureNode, retrieve the literal of option signer.
    Figure 20. Illustration of node navigation
    Illustration of node navigation
  5. You use the Java Naming Directory Interface (JNDI) API to retrieve the hash of the user password from the IBM Tivoli Directory Server. You first set up the environment to access the directory server and then obtain the directory context using the environment. We provided the URL of the LDAP server as well as the LDAP administration DN and password. See the code in listing 6.

    Listing 6. JNDI environment setup
    Hashtable env = new Hashtable(11);
    env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
    env.put(Context.PROVIDER_URL, "ldap://");
    env.put(Context.SECURITY_AUTHENTICATION, "simple");
    env.put(Context.SECURITY_CREDENTIALS, "passw0rd");
    env.put("java.naming.ldap.attributes.binary", "userpassword");
    DirContext ctx = new InitialDirContext(env);
  6. Next, you pass in the signer (username) you obtained previously to retrieve the value of the userpassword attribute. IBM Tivoli Directory Server returns the digest string of the password, which looks like the following:


    The {SHA} prefix appended to the digest indicates that the hash is in SHA-1 format. Because Lotus Forms expects an actual Base64 decoded digest (excluding the prefix), you remove the {SHA} prefix using the Java substring() method as shown in listing 7.

    Listing 7. Retrieve the value for the attribute userpassword
    Attributes att = ctx.getAttributes("uid="+theSigner+","+dn);
    Attribute passAtt = att.get("userpassword");
    bytePass = (byte[])passAtt.get();			
    stringPass = (new String(bytePass));
    stringPass = stringPass.substring(5);
  7. Next, you perform a Base64 decoding on the remaining value of the string as follows:

    byt = stringPass.getBytes("UTF-8");
    String theHash = (new String(byt));
    hash = (new BASE64Decoder()).decodeBuffer(theHash);
  8. Last, the authentication module needs to search for the available certificate installed on the server and to use this certificate to verify and notarize the signature using the validateHMACWithHashedSecret() method. Earlier in this article, we mentioned storing the secret as clear text. In that case, you can use validateHMACWithSecret() instead.

    After the verification and notarization are done, save the form to a local file system using writeForm(). See listing 8.

    Listing 8. Certificate lookup, signature verification, and notarization
    certStatus = new IntHolder();
    try {
      if ((certList = theXFDL.getEngineCertificateList("Generic RSA", 
      certStatus)) == null)
        System.out.println("Certificate NOT found");
      } else {
        System.out.println("Certificate found! " +certList[0]);
        signStatus = new IntHolder();
        validation = theSignatureNode.validateHMACWithHashedSecret(hash, 
        certList[0], signStatus);
        theForm.writeForm("C:/temp/notarized/BalanceTransferRequest” +theSigner+ 
        ”.xfdl", null, 0);
    } catch (Exception e){};

Signing ceremony

You are now ready to test the Authenticated Clickwrap signature solution that you implemented in the previous section. You can use Lotus Forms Viewer to view the form and sign the form using the Clickwrap signature wizard. We compare the output before and after the server certificate notarization.

  1. In Rational Application Developer, open the Authentication Module project.
  2. In the Project Explorer view, right-click AuthenticationModule and select Run As - Run on Server.
  3. Choose a server on which the Authentication Module will be deployed.
  4. Click Finish to publish the Authentication Module to the server.
  5. Open the BalanceTransfer.xfdl file that you exported in earlier steps using Lotus Forms Viewer.
  6. For your convenience, the form has been populated with the data stored in the Xform instance. Feel free to change the form.
  7. Click the Click Here To Sign button.
  8. In the Digital Signature Viewer, you do not see a signature. Click Sign.
  9. Enter the username david; enter and confirm the password password. (Notice that this is the user that you created using the LDIF Import task earlier). See figure 21.

    Figure 21. Signing ceremony
    Signing ceremony
  10. Click Accept.
  11. The signature information displays in the Digital Signature Viewer. Notice that the signature status is Verified, Not Authenticated as shown in figure 22. This status tells you that the signer has signed the form but the authenticity of the user is not confirmed yet. You need to submit this signed form to the Authentication Module to validate the user’s identity.

    Figure 22. Signature status: Verified, Not Authenticated
    Signature status: Verified, Not Authenticated
  12. Click OK to close the Digital Signature Viewer window.
  13. You can see that the signature button’s name has been changed to the signer ID, which in this case is david. Click Submit Form To Server.
  14. Switch back to the Console view of Rational Application Developer. You should see information about the signer and the hash retrieved from the user database. You also see the message saying that the certificate is found on the server and the validation code is 0. Code 0 confirms that the signature has been verified. See figure 23.

    By passing in the password hash and the certificate to validateHMACWithHashedSecret(), the Lotus Forms API notarizes the signature with the server certificate. The signer is authenticated, and the signature is counter signed.

    Figure 23. Authentication Module console output.
    Authentication Module console output.
  15. The form with the signature notarization should be created in the C:\temp\notarized folder (this location is defined in the Authentication Module).
  16. Double-click the form BalanceTransferRequest_<signer>.xfdl where <signer> is the Signer ID to open it in Lotus Forms Viewer. Click the signature button with the label david.
  17. You should see the signature status changed to Signature Is Valid, which confirms the signer identity.

Congratulations! You have completed the implementation of the Authenticated Clickwrap signature in Lotus Forms 3.0.1.


Lotus Forms 3.0.1 supports Authenticated Clickwrap signature technologies. Organizations that have an existing LDAP and user database infrastructure can benefit from using these technologies to create a secured, non-repudiation digital form solution without implementingthe expensive PKI infrastructure-based digital signature.

This article uses Lotus Forms Viewer to display the form. As an alternative, you can use Lotus Forms – Webform Server, which allows users to complete, sign, and submit forms in a Web browser without the need for Lotus Forms Viewer. Using this approach, you can create a complete zero-footprint forms solution.


Code sampleDownloadFiles.zip10KB



Get products and technologies



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

ArticleTitle=Developing a secured, non-repudiation IBM Lotus Forms solution with Authenticated Clickwrap signatures