Skip to content

This page describes how to deploy a vault in Ripple Custody to connect to a hardware security module (HSM) in AWS CloudHSM. Before following these instructions, you need to have created and initialized your HSM in AWS CloudHSM, as described in Initialize an AWS CloudHSM.

Once you have initialized the HSM, complete the following steps to use the to deploy a vault that uses the HSM.

  1. Install the .
  2. Deploy the vault.
  3. Connect the vault.

The following sections describe these steps in detail.

Prerequisites

Before starting, make sure you have the following information:

  • User-supplied information — Be prepared to supply the following to the :

    • Vault name — A name you choose to reflect the intended purpose of the vault.
    • Vault ID — A user-defined unique identifier (UUID). Note: This ID cannot be modified once the vault is created.
    • IAM Profile — The Identity and Access Management (IAM) role that will be attached to the EC2 instances. This is a drop-down menu in the .

  • From Ripple — Your Ripple liaison will provide this information:

    • Open telemetry (OTEL) information, as follows:
      • OTEL Collector Address — URL of your OTEL collector where telemetry data will be sent for processing and analysis
      • OTEL Username and Password — Basic authentication credentials
    • Docker registry information:
      • Docker Server DNS Name
      • Docker Username and Password

  • From your AWS CloudHSM cluster — see Initialize an AWS CloudHSM:

    • 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

1. Install the

Before you can deploy the vault, you need to install the , which you can do using a Cloud Formation (CF) template available through your Ripple liaison.

To provision the resources (AWS App Runner, predefined IAM Instance-role, and AWS Cognito user pool):

  1. Provide the following:

    1. The custom DNS domain name where the AWS App Runner application will be exposed.
    2. The tenant name as a string.
      Ripple provides you with the tenant name.
    3. The AWS region where the resources will be provisioned.

  2. Submit the form to install the .
    Once the installation is complete, you can authenticate and then access the at the custom DNS name you provided. To add users to the AWS Cognito user pool for access to the , see Signing up and confirming user accounts.

2. Deploy the vault

From the you just opened, you (or any assigned user) can now deploy the vault:

  1. Enter your username and password.

    Custody onboarding

    This screen shows the with the Getting started widget from where you can start to deploy the vault.

  2. On the Getting started widget, select Start and complete all sections to deploy a vault:

    • Create a new vault
    • Configure networking
    • Configure the key management system (KMS)
    • Configure telemetry (optional)
    • Connect a Docker container registry
    • Installation
    Note:

    The provides step-by-step instructions to guide you through the onboarding experience.

    Custody onboarding summary This screen shows the with the summary of the settings you selected for deploying the vault. Review the summary before you select Submit.

  3. Once you submit for installation, it takes from three to five minutes to create the resources on AWS Cloud. When the process is complete, the displays the ID and Public key that you will need to enter in Ripple Custody.

    Copy ID and public key This screen shows the with the ID and the Public key that you must copy and then paste into your Ripple Custody instance to connect the vault.

  4. Save a copy of the ID and Public Key values, as you will need to enter them in your instance.

3. Connect the vault

After the installation is complete, you must connect your vault to your Ripple Custody instance.

  1. In the , make sure you have saved a copy of the ID and Public Key values, and select Open Ripple Custody instance.

  2. Log in to your Ripple Custody instance.

  3. Select Administration > Vaults > Create a vault.

  4. In the Vault name field, enter a unique name for the vault.

  5. Copy the ID value you copied from , and paste it into the ID field in your Ripple Custody instance.

  6. Copy the Public Key value you copied from , and paste it into the Vault public key field in your Ripple Custody instance.

  7. Select Submit for approval and follow the process for submitting and approving the intent to create the new vault.

  8. The vault is connected when it appears in the Administration > Vaults window, and its Activation status has changed from Pending to Completed. Custody vaults.

Initialize an AWS CloudHSM

BlockSafe HSM integration guide