Skip to content

This page outlines the steps needed to create and initialize a hardware security module (HSM) cluster resource using AWS CloudHSM, in your own AWS account. Once you have created the HSM, see Deploy a vault for instructions on deploying a vault using the HSM for use in Ripple Custody.

Tip

If you have questions about the AWS CloudHSM setup, contact the AWS solution architecture team.

Warning

Please read the AWS page AWS CloudHSM user management best practices. There are a number of important caveats to keep in mind:

  • Neither Ripple nor AWS has access to your HSM user credentials, and they will be unable to assist you if you lose access to them.
  • To avoid being locked out of your cluster, we recommend you have at least two admins with separate passwords in case one admin password is lost. In the event this happens, you can use the other admin to reset the password.
  • We also recommend creating multiple crypto users, each with limited permissions.
  • If you don't back up your HSMs and you don't have replication enabled, and there's an incident causing the permanent loss of keys, neither Ripple nor AWS will be able to assist you.

To create and initialize an HSM using AWS CloudHSM, complete the following steps.

1. Create the HSM

For information on how to create the HSM, see Create an HSM in AWS CloudHSM.

2. Initialize the HSM cluster

Initialize the HSM cluster with private Certificate Authority tools.

For information on how to initialize the cluster, see Initialize the cluster in AWS CloudHSM.

Note

During cluster initialization, you will create a customerCA.crt file. A copy of this file is required for client application setup.

3. Activate the cluster

For information on how to activate the cluster, see Activate the cluster in AWS CloudHSM.

4. (Optional) Configure mutual TLS (mTLS)

This step is optional, but recommended. For more information on how to configure mutual TLS (mTLS), see Set up mutual TLS between client and AWS CloudHSM (recommended).

5. Create a new HSM crypto user

For instructions on how to create an HSM crypto user, with permission to use encrypt-decrypt keys, see Create an HSM crypto user using CloudHSM CLI. For more information about HSM user management, see HSM user management with CloudHSM CLI.

The following is an example for creating a new HSM crypto user using cloudhsm-cli:

USERNAME=awsclientapp
PASSWORD=$(< /dev/urandom | base64 | tr -dc 'A-Za-z0-9!@#$%^&*()_+-=[]{}|;:,.<>?' | head -c 12; echo)
cloudhsm-cli user create --role "crypto-user" \
 --username "$USERNAME" \
 --password "${PASSWORD}"

6. Create a symmetric AES256 key

The following is an example for creating a symmetric AES256 key using cloudhsm-cli:

ID=A2114F9A-FC61-4ED5-AFAB-28E00DD5EA72
cloudhsm-cli key generate-symmetric aes \
 --label KEYLABEL --key-length-bytes 32 \
 --attributes id="0x$(printf "$ID" | sha256sum | cut -f 1 -d ' ')" \
 encrypt=true decrypt=true

7. Create a new VPC with two subnets

To complete this step, reach out to your Ripple liaison. They can propose a reference design to help you complete this step.

The new VPC will be reserved for Ripple Custody applications.

Two subnets must be attached to the VPC:

  • The private subnet must have the required network resources (routing rules, peering, NAT gateway) configured to allow PKCS #11 client application traffic to be routed to the HSM IP address or IP addresses, which are most likely located in a different VPC.
  • A public subnet and internet gateway must be attached to the VPC to route outgoing traffic from Ripple Custody applications (running in EC2 Nitro) to Ripple Custody SaaS.

8. Transfer information to the

Be prepared to transfer the following information to the Ripple Custody, as described in Deploy a vault:

  • VPC and VPC subnet — An existing Virtual Private Cloud (VPC) and subnet where you want to provision your resources. (Alternatively, you have the create a new VPC.)
  • Region — The preferred AWS region where you want to provision resources.
  • AWS CloudHSM cluster — The name of the HSM you created
  • CA Certificate — The client certificate file, customerCA.crt, generated when you created the HSM cluster.
  • PKCS11 authentication — The credentials required to authenticate the PKCS11 client application with AWS CloudHSM:
    • PKCS11 Login username and password HSM crypto user login username and password
  • Hardware AES key prerequisite:
    • AES256 key ID attribute
    • Second AES256 wrapping key

AWS CloudHSM

Deploy a vault