Adobe ExperienceManager FormsnShield® HSM Integration Guide

Version: 1.1

Date: Monday, August 23, 2021

Copyright © 2021 nCipher Security Limited. All rights reserved.

Copyright in this document is the property of nCipher Security Limited. It is not to be

reproduced modified, adapted, published, translated in any material form (including

storage in any medium by electronic means whether or not transiently or incidentally) in

whole or in part nor disclosed to any third party without the prior written permission of

nCipher Security Limited neither shall it be used otherwise than for the purpose for

which it is supplied.

Words and logos marked with ® or ™ are trademarks of nCipher Security Limited or its

affiliates in the EU and other countries.

Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in

the United States and/or other countries.

Information in this document is subject to change without notice.

nCipher Security Limited makes no warranty of any kind with regard to this information,

including, but not limited to, the implied warranties of merchantability and fitness for a

particular purpose. nCipher Security Limited shall not be liable for errors contained

herein or for incidental or consequential damages concerned with the furnishing,

performance or use of this material.

Where translations have been made in this document English is the canonical language.

nCipher Security Limited

Registered Office: One Station Square

Cambridge, UK CB1 2GA

Registered in England No. 11673268

nCipher is an Entrust company.

Entrust, Datacard, and the Hexagon Logo are trademarks, registered trademarks, and/or

service marks of Entrust Corporation in the U.S. and/or other countries. All other brand

or product names are the property of their respective owners. Because we are

continuously improving our products and services, Entrust Corporation reserves the right

to change specifications without prior notice. Entrust is an equal opportunity employer.

Adobe Experience Manager Forms nShield® HSM Integration Guide 2 of 10

Contents1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

1.1. nShield configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

1.2. Software configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

1.3. Supported nShield HSM functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5

2. Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6

2.1. Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6

2.2. Configure Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6

2.3. Generate a Signed Certificate on the HSM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8

2.4. Configure the HSM credential alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9

Contact Us. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

Adobe Experience Manager Forms nShield® HSM Integration Guide 3 of 10

1. IntroductionAdobe Experience Manager Forms is an end-to-end digital document solution that

makes it possible to create responsive forms that customers can complete and securely

e-sign. Digital signatures in AEM Forms can use credentials stored in an Entrust nShield

HSM to apply server-side digital signatures.

1.1. nShield configurations

We have successfully tested the integration of an nShield HSM with Adobe Experience

Manager Forms in the following configurations:

nShield HSM nShield Image nShield Firmware nShield SecurityWorld Software

Connect XC

Connect +

12.60.10 12.50.11

12.50.8

12.60.11

1.2. Software configurations

We have successfully tested the integration of an nShield HSM with Adobe Experience

Manager Forms using the AEM Forms on JEE deployment using the following versions:

Base OS Java AEM Forms JBoss MSSQL Server

Windows Server

2016

JDK 1.8.0_291 6.5.0 Red Hat JBoss

EAP 7.1.4.GA

2019

1.3. Supported nShield HSM functionality

Feature Support

Module-only key Yes

OCS cards Yes

Softcards Yes

nSaaS Yes

FIPS 140-2 level 3 Yes

Adobe Experience Manager Forms nShield® HSM Integration Guide 4 of 10

1.4. Requirements

Before starting the integration process, familiarize yourself with the Adobe

Documentation and Software Requirements along with nShield Documentation. The

following include links to documentation for Adobe Experience Manager Forms used in

this integration:

• https://experienceleague.adobe.com/docs/experience-manager-65/forms/install-

aem-forms/jee-installation/aem-forms-jee-supported-platforms.html?lang=en

• https://helpx.adobe.com/content/dam/help/en/experience-manager/6-5/forms/

pdf/install-single-server-jboss.pdf

• https://helpx.adobe.com/content/dam/help/en/experience-manager/6-5/forms/

pdf/prepare-install-single-server.pdf

• https://experienceleague.adobe.com/docs/experience-manager-65/forms/

administrator-help/manage-certificates-credentials/hsm-credentials.html?lang=en#

Adobe Experience Manager Forms nShield® HSM Integration Guide 5 of 10

2. Procedures

2.1. Prerequisites

Before you can use Adobe Experience Manager Forms with the nShield HSM, complete

the following steps:

1. Install the Java Development Kit.

2. Set up the HSM client software on the machine where Adobe Experience Manager

Forms will be installed. See the Installation Guide for your HSM.

3. Configure the HSM(s) to have the IP address of your host machine as a client.

4. Load an existing Security World or create a new one on the HSM.

5. Create or edit the cknfastrc file in nfast directory, and add one of the following two

config settings:

Module protection:

CKNFAST_FAKE_ACCELERATOR_LOGIN=1

OCS or Softcard protection:

CKNFAST_LOADSHARING=1CKNFAST_NO_ACCELERATOR_SLOTS=1

Optional lines to enable debug:

CKNFAST_DEBUG=5CKNFAST_DEBUGFILE=C:\pkcs11.log

6. Install Adobe Experience Manager Forms.

For instructions, see the Adobe Documentation.

This integration followed the Adobe documentation and set up AEM forms on a JEE

deployment.

For more information on configuring and managing nShield HSMs, Security Worlds, and

Remote File Systems, see the User Guide for your HSM(s).

2.2. Configure Java

You have to configure Java for the nShield HSM before you can use the HSM with Adobe

Experience Manager Forms Credentials.

Adobe Experience Manager Forms nShield® HSM Integration Guide 6 of 10

1. Add lines to C:\ProgramData\nCipher\Key Management Data\config\config about

privileged and non-privileged ports:

[server_startup]...priv_port=9001nonpriv_port=9000

2. Set the path variables.

Open a command prompt as Administrator and run:

% setx JAVA_HOME "C:\Program Files\Java\jdk1.8.0_291"% setx PATH "%PATH%;%JAVA_HOME%\bin";

3. Copy the nCipherKM.jar file to the extensions folder of your local Java Virtual Machine

installation from the following directory:

%NFAST_HOME%\java\classes

4. Paste the file in the following directory:

%JAVA_HOME%\jre\lib\ext

5. Download the JCE Unlimited Strength Jurisdiction Policy Files from your Java VM

vendor’s Web site. The downloaded Java 8 file used in this interop was jce_policy-8.

6. Extract and copy the extracted files local_policy.jar and US_export_policy.jar into

the security directory:

%JAVA_HOME%\jre\lib\security

7. Edit %JAVA_HOME%\jre\lib\security.

8. Add security.provider.1=com.ncipher.provider.km.nCipherKM to the top of the list of

providers and shift the rest of the numbers down to keep them in ascending order.

9. Open a command prompt as Administrator and run:

% java com.ncipher.provider.InstallationTest

10. The output of the above command should show a list of providers and nShield JCE

services.

Also check for the following phrases within the output:

Adobe Experience Manager Forms nShield® HSM Integration Guide 7 of 10

Unlimited strength jurisdiction files are installed.The nCipher provider is correctly installed.

2.3. Generate a Signed Certificate on the HSM

An nShield HSM will be used to generate a Certificate Signing Request to then be signed

and imported. This certificate will be later used by AEM Forms Credentials.

If you are using FIPS 140-2 level 3, PKCS #11 requires HSM OCS cards for FIPS

authentication when you are importing the signed certificate. When you are running the

ckcerttool command at a later step, you will have to insert the OCS card(s).

1. The following command can be used to generate an ocs or Softcard for the HSM:

% createocs -m1 -Q 1/1 -N <cardset_name>% ppmk --new <cardset_name>

2. Open command prompt as administrator and run

Module protection:

% generatekey pkcs11 protect=module certreq=yes type=rsa size=2048 pubexp=65537 plainname=<key_name> nvram=no

OCS protection:

% generatekey pkcs11 cardset=<cardset_name> protect=token certreq=yes type=rsa size=2048 pubexp=65537plainname=<key_name> nvram=no

Softcard protection:

% generatekey pkcs11 softcard=<cardset_name> protect=softcard certreq=yes type=rsa size=2048 pubexp=65537plainname=<key_name> nvram=no

3. Take note of the path to the key and the CSR.

4. Take the CSR file to a Certificate Authority and have it signed.

5. Take the generated signed certificate file and place it in the same directory where

the CSR file was originally generated.

6. Open command prompt as administrator and run one of the following to import the

signed certificate:

Module protection:

% ckcerttool -c <cardset name> -f <signed_cert_filename> -k <identof the key, the part after pkcs11_> -L<label_for_the_key>

Adobe Experience Manager Forms nShield® HSM Integration Guide 8 of 10

OCS and Softcard protection:

% ckcerttool -n -f <signed_cert_filename> -k <identof the key, the part after pkcs11_> -L <label_for_the_key>

OCS protection example:

% ckcerttool -c aemocs -f aemcertocs.cer -k ucdf5b8ad614c4790788582016043d54d23282013b-fcc2027b509bf11dfff2d5e91c83229eb389b2c1 -L AEMocsprivateKey

2.4. Configure the HSM credential alias

If you completed the previous steps while the Application Server was running, you might

need to restart the Application Server before you configure the HSM credential alias

because AEM Forms might not recognize the HSM certificate yet.

1. Open the administrative console of AEM Forms in a web browser at

http://localhost:8080/adminui.

2. Select Settings.

3. Select Trust Store Management.

4. Select HSM Credentials.

5. Enter a Profile Name for the HSM.

6. Enter the path of the pkcs11 library:

C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll

7. Select Test HSM Connectivity.

A success message HSM is available should be displayed.

8. For the Token Name, Select accelerator for module protection or the cardsetname

for ocs/softcard protection.

9. The corresponding Slot ID and Slot List Index values should automatically be

selected.

10. For the Token Pin, enter the administrator card passphrase if you are using module

protection. If you are using OCS cards or Softcard protection, enter their passphrase.

11. Select Next.

12. Select the HSM’s Credentials.

13. Select Save.

14. Test this credential by selecting the check box next to it and selecting Check Status.

A green check mark should appear.

Adobe Experience Manager Forms nShield® HSM Integration Guide 9 of 10

Contact Us

Web site https://www.entrust.com

Support https://nshieldsupport.entrust.com

Email Support nShield.support@entrust.com

Online documentation: Available from the Support site listed

above.

You can also contact our Support teams by telephone, using the following numbers:

Europe, Middle East, and Africa

United Kingdom: +44 1223 622444

One Station Square

Cambridge, UK CB1 2GA

Americas

Toll Free: +1 833 425 1990

Fort Lauderdale: +1 954 953 5229

Sawgrass Commerce Center – A

Suite 130

13800 NW 14 Street

Sunrise, FL 33323 USA

Asia Pacific

Australia: +61 8 9126 9070

World Trade Centre Northbank Wharf

Siddeley St

Melbourne VIC 3005 Australia

Japan: +81 50 3196 4994

Hong Kong: +852 3008 3188

31/F, Hysan Place,

500 Hennessy Road,

Causeway Bay

Adobe Experience Manager Forms nShield® HSM Integration Guide 10 of 10

ABOUT ENTRUST CORPORATION

Entrust keeps the world moving safely by enabling trustedidentities, payments, and data protection. Today more than ever,people demand seamless, secure experiences, whether they’recrossing borders, making a purchase, accessing e-governmentservices, or logging into corporate networks. Entrust offers anunmatched breadth of digital security and credential issuancesolutions at the very heart of all these interactions.Withmorethan 2,500 colleagues, a network of global partners, andcustomers in over 150 countries, it’s no wonder the world’s mostentrusted organizations trust us.

To get help withEntrust nShield HSMs

nShield.support@entrust.com

nshieldsupport.entrust.com