This document provides instructions for setting up Amazon AWS CloudHSM (CloudHSM) as a HSM provider for PrivX. This integration allows PrivX to store and/or encrypt its cryptographic keys with HSM.

These instructions are only applicable to fresh deployments: existing PrivX deployments cannot be integrated with HSM.

These instructions are to be used together with the PrivX-setup instructions provided in the PrivX Administrator Manual.

Disclaimers

This document includes instructions regarding third-party products by Amazon. These instructions are provided for general guidance only.

Documentation involving third-party products include setting up Linux clients for CloudHSM. The instructions in this manual were verified against the CloudHSM version from May 2019 . These instructions will need to be adapted when using other versions of CloudHSM.

SSH Communications Security Corporation does not make any warranties as to the accuracy, reliability, or usefulness of these instructions, nor guarantee that the content related to third-party products is up to date.

SSH Communications Security Corporation does not provide any warranties regarding third-party products, such as CloudHSM, nor provide any support or other services for third- party products.

For instructions about setting up and operating Amazon products, we always recommend that you consult the official vendor documentation intended for the specific version(s) of Amazon products in your use and/or directly contact Amazon representatives or support.

It is always your responsibility to define the final production setup for the Amazon products that you use.

Prerequisites

Check and ensure the following before performing the procedures in this document:

• You need an activated CloudHSM cluster. Machines where PrivX shall be installed (PrivX machines) must be able to connect to this cluster.

Integration Steps

The high-level workflow for CloudHSM integration involves:

1. Connecting PrivX machines to a CloudHSM cluster.
2. Setting up PrivX-server software on PrivX machines.

These steps are described in more detail in the following sections.

Connecting PrivX Machines to a CloudHSM Cluster

Configure your PrivX machines as clients to your CloudHSM cluster. To do this:

1. On your PrivX machines: Install the AWS CloudHSM Client and Command Line Tools, and Edit the Client Configuration. These procedures are described at:
   https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html
   
   
2. Create a PrivX user in the CloudHSM partition (replace privx_user and example_password with the user name and password respectively):
   # createUser CU privx_user example_password


3. Also install the CloudHSM software library for PKCS #11 on your PrivX machines. This is described at:
   https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html

Setting Up PrivX-Server Software on PrivX Machines

Set up PrivX-server software on a PrivX machine according to the PrivX Administrator Manual, while paying attention to the following points.

You will be prompted for HSM settings during postinstall. Provide them as follows:

Enable pkcs11 keyvault support? [y/N]
To enable, enter y

Select pkcs11 provider [1-3]:
To select Amazon Cloud HSM, enter 2

Enter pkcs11 provider library file path:
Enter /opt/cloudhsm/lib/libcloudhsm_pkcs11.so

Enter pkcs11 slot:
Enter 1

Enter pkcs11 pin: and Enter pkcs11 pin again:
Enter and verify the PrivX user's HSM credentials in username:password format. With the previously-given example, this would be privx_user:example_password

After this, proceed with setup as normal. You should have access to the PrivX GUI after postinstall completes.

If you need to set up additional PrivX servers, duplicate the PrivX-server setup to other PrivX machines as described in the PrivX Administrator Manual.