Configuring the ESA with the Thales Luna HSM

Verifying the Prerequisites

Ensure that the following prerequisites are met:

1. Ensure that the HSM partition is initialized.

2. Ensure that you have downloaded the required libraries, configuration files, and certificates required for connecting to the HSM. The certificates can include the server certificate of the Thales Luna HSM, the client certificate for the ESA appliance, and the CA certificate.
   For more information required about the files required for connecting to the Thales Luna HSM, refer to the Thales Luna documentation.

3. Ensure that the following roles on the Thales Luna HSM are granted read and write permissions:

   • Partition Officer (PO) / Security Officer (SO)
   • Crypto Officer (CO)
   • Crypto User (CU)

   It is recommended to configure the Thales Luna HSM client library to authenticate using the Crypto User (CU). The following setting in the Miscellaneous section of the Chrystoki.conf configuration file configures the role to use for the challenge request status.

   ProtectedAuthenticationPathFlagStatus = 2
   

   Note: The Crypto User (CU) must be initialized on the Thales Luna HSM by using methods, such as, setting a PIN for the Crypto User (CU).
   For more information about initializing the Crypto User (CU), refer to the documentation of the HSM vendor.

Configuring Connection with Thales Luna HSM

To configure a connection with Thales Luna HSM:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. Click New Key Store.

   The Create New Key Store screen appears.

3. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for HSM. For example, type Thales_Luna_HSM. The name that you type will update the Key Store installation path field.
   • Type: Select PKCS #11.

4. In the PKCS#11 details section, enter the following details:

   • User pin: Specify the user pin for the given slot ID of the Thales Luna HSM.
   • Slot: Enter the slot ID for the Thales Luna HSM.

5. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
   The Add Key Store environment variable dialog box appears.

6. Enter the following details, and then click Save:

   • Environment variable name: Specify ChrystokiConfigurationPath as the environment variable name for the Thales Luna HSM.
   • Environment variable value: Specify the value for the environment variable.
     For example, specify /opt/protegrity/keystore/<Keystore_name>, which is the value of the Key Store installation path field, for the Thales Luna HSM.
     If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.

7. In the Key Store files and environment variables > Key Store files section, click Add File.
   The Add Key Store File dialog box appears.

8. Enter the following details.

   File Type	File
   Library	Select the libCryptoki2_64.so HSM library file from your local machine.
   Configuration	Select the Chrystoki.conf HSM configuration file from your local machine.
   Other	Select the Thales Luna HSM client certificate, client key, and server certificate from your local machine.

Note: You can select only one file at a time.

9. Click Add File to add the file to the Key Store files section.

10. Repeat steps 7 to 9 till you have added all the files required to connect to the Key Store.

11. Perform the following steps to edit the configuration file.
    a. Click the Edit icon next to the configuration file.
    The Edit Key Store File screen appears.

    b. Update the path of the required configuration parameters to match the path displayed in the Key Store installation path field.

    c. Click Save.
    The Edit Key Store File screen closes.

12. Click Save.
    The Key Store saved successfully message appears.

13. Click Test to test the Key Store connection.
    The Test Key Store Connection dialog box appears.

14. Click OK to close the Test Key Store Connection dialog box.

15. Click Set As Active to activate the Key Store.
    > Note: If you are using the Thales Luna HSM on an external network, then the policy management services might have a longer start-up time due to network latency.