AWS CloudHSM

This document provides instructions for setting up Amazon AWS CloudHSM as the 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 at Setting up PrivX components.

Disclaimers

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

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 a CloudHSM cluster with at least one HSM. Machines where PrivX shall be installed (PrivX machines) must be able to connect to this cluster. The cluster may be in FIPS or in non-FIPS mode.

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.

Installing CloudHSM SDK

Configure your PrivX machines as clients to your CloudHSM cluster. The following steps need to be performed on all PrivX machines.

1. Download and install the latest CloudHSM CLI and CloudHSM PKCS#11 SDK from the latest releases. The minimum supported version is 5.17.0.
2. Copy the HSM cluster issuer CA under /opt/cloudhsm/etc/
3. Bootstrap the CLI tool and SDK with the following commands:

   sudo /opt/cloudhsm/bin/configure-cli -a <The ENI IPv4 / IPv6 addresses of the HSMs>
   sudo /opt/cloudhsm/bin/configure-cli --hsm-ca-cert <Path to issuer CA>
   sudo /opt/cloudhsm/bin/configure-pkcs11 -a <The ENI IPv4 / IPv6 addresses of the HSMs>
   sudo /opt/cloudhsm/bin/configure-pkcs11 --hsm-ca-cert <Path to issuer CA>

Cluster Activation and Creating a Privx Crypto User

CloudHSM operations need to be performed through a crypto user. A crypto user functions as a service account for PrivX.

info

This operation only needs to be done once per cluster.

1. Launch cloudhsm-cli in interactive mode:

   sudo /opt/cloudhsm/bin/cloudhsm-cli interactive

2. Activate the cluster:

   aws-cloudhsm > cluster activate

   Enter a cluster-admin password.
3. Log in as the cluster admin:

   aws-cloudhsm > login --username admin --role admin

4. Create the PrivX crypto user:

   aws-cloudhsm > user create --username privx --role crypto-user

Setting Up PrivX-Server Software on PrivX Machines

Set up PrivX-server software on a PrivX machine according to the Deployment instructions, 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:
Select the option for Amazon CloudHSM.
Enter pkcs11 provider library file path:
Enter /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
Enter pkcs11 slot (as decimal or hex with 0x prefix):
Enter 0x2000000000000001
Enter pkcs11 pin: and Enter pkcs11 pin again:
Enter and verify the PrivX crypto user's credentials in username:password format.

info

To automate postinstall, provide the HSM settings (and other settings) in /opt/privx/scripts/postinstall_env, and source the file before running postinstall.

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 High-Availability Deployment.

info

The provided backup.sh and restore.sh utilities only duplicate the PrivX-server setup. You must separately duplicate the CloudHSM-client setups.

CloudHSM Limitations

The CloudHSM SDK does not support symmetric encryption of plaintexts that exceed 16kB (https://docs.aws.amazon.com/cloudhsm/latest/userguide/ki-pkcs11-sdk.html#ki-pkcs11-8). This may cause PrivX to fail to perform operations in rare circumstances. This can be mitigated by enabling ciphertext splitting in PrivX Keyvault.

In order to enable this feature, perform the following on each PrivX node:

1. Open /opt/privx/etc/keyvault-config.toml and find the setting ciphertext_block_size. Set its value to the previously-recommended value.
2. Restart PrivX Keyvault:

   sudo systemctl restart keyvault

This feature can be disabled at any time by setting the value back to 0 and restarting the Keyvault.