Hardware security modules (HSM) and etokens are dedicated, hardened, and tamper-resistance computing devices designed to securely manage, process, and store digital keys. These devices are directly attached to a computer or a network server.

Adobe Experience Manager Forms can use credentials stored on an HSM or etoken to eSign or apply server-sided digital signatures to a document. To use an HSM or etoken device with AEM Forms:

Enable the DocAssurance service.

Set up certificates for Reader extension.

Create an alias for the HSM or etoken device in AEM Web Console.

Use the DocAssurance Service APIs to sign or certify the documents with digital keys stored on the device.

Before you configure the HSM or etoken devices with AEM Forms

Install and configure HSM or etoken client software on the same computer as AEM server. The client software is required to communicate with the HSM and etoken devices.

(Microsoft Windows only) Set the JAVA_HOME_32 environment variable to point to the directory where the 32-bit version of Java 8 Development Kit (JDK 8) is installed. The default path of the directory is C:\Program Files(x86)\Java\jdk<version>

(AEM Forms on OSGi only) Install the root certificate in the trust store. It is required to verify the signed PDF

Pastaba:

On Microsoft Windows, only 32-bit LunaSA or EToken clients are supported.

Enable the DocAssurance service

By default, the DocAssurance service is not enabled. Perform the following steps to enable the service:

Stop the Author instance of your AEM Forms environment.

Open the [AEM_root]\crx-quickstart\conf\sling.properties file for editing.

Pastaba:

If you have used the [AEM_root]\crx-quickstart\bin\start.bat file to start the AEM instance, then open the [AEM_root]\crx-quickstart\sling.properties file for editing.

Set up certificates for Reader extensions

Click the name field of the user account. The Edit User Settings page opens.

On the AEM Author instance, certificates reside in a KeyStore. If you have not created a KeyStore earlier, click Create KeyStore and set a new password for the KeyStore. If the server already contains a KeyStore, skip this step.

On the Edit User Settings page, click Manage KeyStore.

On KeyStore Management dialog, expand the Add Private Key from Key Store file option and provide an alias. The alias is used to perform the Reader Extensions operation.

Add the Key Store Password, Private Key Password, and Private Key Alias that is associated with the certificate to the respective fields. Click Submit.

Pastaba:

To determine the Private Key Alias of a certificate, you can use the Java keytool command: keytool -list -v -keystore [keystore-file] -storetype pkcs12

Pastaba:

In the Key Store Password and Private Key Password fields, specify the password provided with the certificate file.

Pastaba:

For AEM Forms on OSGi, to verify the signed PDF, the root certificate installed in the Trust Store.

Pastaba:

On moving to production environment, replace your evaluation credentials with production credentials. Ensure that you delete your old Reader Extensions credentials, before updating an expired or evaluations credential.

Create an alias for the device

The alias contains all the parameters that an HSM or etoken requires. Perform the instructions listed below to create an alias for each HSM or etoken credential that eSign or Digital Signatures uses :

Open AEM console. The default URL of AEM console is http://<host>:<port>/system/console/configMgr

Open the HSM Credentials Configuration Service and specify values for the following fields:

Credential Alias: Specify a string used to identify the alias. This value is used as a property for some Digital Signatures operations, such as the Sign Signature Field operation.

DLL Path: Specify the fully qualified path of your HSM or etoken client library on the server. For example, C:\Program Files\LunaSA\cryptoki.dll. In a clustered environment, this path must be identical for all servers in the cluster.

HSM Pin: Specify the password required to access the device key.

HSM Slot Id: Specify a slot identifier of type integer. The slot ID is set on a client-by-client basis. If you register a second machine to a different partition (for example, HSMPART2 on the same HSM device), then slot 1 is associated with the HSMPART2 partition for the client.
Note:While configuring Etoken, specify a numeric value for the HSM Slot Id field. A numeric value is required to get the Signatures operations working.

Certificate SHA1: Specify SHA1 value (thumbprint) of the public key (.cer) file for the credential you are using. Ensure that there are no spaces used in the SHA1 value. If you are using a physical certificate, then it is not required.

HSM Device Type: Select the manufacturer of the HSM (Luna or other) or eToken device.

Click Save. The hardware security module is configured for AEM Forms. Now, you can use the hardware security module with AEM Forms to sign or certify documents.

Use the DocAssurance Service APIs to sign or certify a document with digital keys stored on the device

The following sample code uses an HSM or etoken to sign or certify a document.