Skip to main content
Welcome to Virtru's support portal. As we work to make this page more accessible to screen readers, please contact us at support@virtru.com for technical support.

Virtru Private Keystore (for Virtru Solutions) Reference - AWS cloudHSM Integration

  • Updated

Overview

The Cloud HSM integration with Virtru Private Keystore (for Virtru Solutions) is designed to give the highest possible protection of encryption keys. This document will cover the steps required to connect a Virtru Private Keystore to the Cloud HSM, and will also detail the steps required to import existing Virtru Private Keystore keys into the HSM.

Jump to:

Important Note

Virtru Private Keystore runs on Linux hosts with Docker and Docker Compose installed, please confirm that your host is compatible with both AWS Cloud HSM and Virtru CKS. At the time of this writing, Cloud HSM does not support Ubuntu 20.04 LTS (per AWS Documentation)

Assumptions

  • HSM cluster has already been stood up

  • HSM has not been initialized

  • CU username is cryptouser

  • Key labels for CKS keys are rsa001

HSM Configuration

Initialize the HSM cluster

  1. Create an HSM in the cluster

Important Note

Ensure the HSM is located in the same Availability Zone as the host running the CKS service

Screen_Shot_2021-01-11_at_11.14.48_AM.png

Wait for HSM to be created

Screen_Shot_2021-01-11_at_11.22.07_AM.png

    1. Download certificate signing request

      1. Click the top button to download the CSR for your cluster

        1. Name: cluster-<cluster-id>_ClusterCsr.csr

      2. Copy downloaded CSR to your CKS Server

    2. Sign the CSR

      1. Signing your HSM CSR - AWS Documentation

        1. Create a private key:

          • openssl genrsa -aes256 -out customerCA.key 2048

            • Include a passphrase

        2. Use the private key to create a self-signed certificate:

          • openssl req -new -x509 -days 3652 -key customerCA.key -out customerCA.crt

            1. Use passphrase above when generating the certificate

        3. Sign the cluster CSR:

          • openssl x509 -req -days 3652 -in cluster-<cluster-id>_ClusterCsr.csr -CA customerCA.crt -CAkey customerCA.key -CAcreateserial -out cluster-<cluster-id>_CustomerHsmCertificate.crt

            • Use passphrase above and clusterID of cluster-<cluster-id>

      2. You should now have cluster-<cluster-id>_CustomerHsmCertificate.crt created:

        Screen_Shot_2021-01-11_at_11.50.19_AM.png

         

    3. Download signed HSM certificate and self-signed cert created on the instance to upload to AWS console:

      1. customerCA.crt

      2. cluster-<cluster-id>_CustomerHsmCertificate.crt

         

    4. Finish initializing the cluster by uploading HSM cert and self-signed cert to HSM cluster

      Screen_Shot_2021-01-11_at_12.01.59_PM.png

      • Initialization now complete

Connect the HSM cluster to EC2 instance

  1. Configure Security Groups - AWS Documentation

    • Then add security group from the HSM cluster to the CKS host:

      Screen_Shot_2021-01-11_at_12.27.51_PM.png

       

Install the AWS cloudHSM client on EC2 instance:

  1. Install and Configure the AWS CloudHSM Client (Linux) - AWS CloudHSM

    • Retrieve IP from HSM cluster in AWS web console

Activate the cluster

  1. Activate HSM Cluster - AWS Documentation

    1. /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg

    2. Enable e2e, log in as PRECO, then change password for CO

      Screen_Shot_2021-01-11_at_2.17.18_PM.pngScreen_Shot_2021-01-11_at_2.18.08_PM.png

       

       

    3. Login as CO and create cryptouser CU

      1. Manage HSM Users - AWS Documentation

      2. loginHSM CO admin <password>

      3. createUser CU cryptouser <password>

        Screen_Shot_2021-01-11_at_4.22.46_PM.png

         

Set up HSM command line tools

  1. There are 2 command line tools:

    1. cloudhsm_mgmt_util (utilized in previous step to create CU user)

      1. CloudHSM Management Utility (CMU) - AWS CloudHSM

      2. Used for managing HSM users

    2. key_mgmt_util

      1. Key Management Utility (KMU) - AWS CloudHSM

      2. Used for managing HSM keys

        1. sudo service cloudhsm-client start

          • Starts the daemon

        2. /opt/cloudhsm/bin/key_mgmt_util

          • Executable - prompt changes to Command when running

Create an RSA key pair on the HSM

If importing existing keys from an existing Virtru Private Keystore or external source, you may skip to Upgrade Procedure From Existing Virtru Private Keystore (Import Keys and Connect Virtru Private Keystore to HSM)

  1. sudo service cloudhsm-client start

  2. /opt/cloudhsm/bin/key_mgmt_util

  3. Command: loginHSM -u CU -s cryptouser -p <password>

  4. Command: genRSAKeyPair -m 2048 -e 65541 -l rsa001

    Screen_Shot_2021-01-11_at_5.21.16_PM.png

Install Virtru Private Keystore

If upgrading an existing Virtru Private Keystore, see steps in next section

  1. Install Virtru Private Keystore

    1. After running the primary setup script to completion, within your cks-setup-scripts directory you will run the setup-cks-hsm-latest.sh script

      1. Before running the HSM integration, SSH into the machine on a second connection.

    2. Enter IP address retrieved when connecting host to HSM (Retrieve IP from HSM cluster in AWS web console)

      1. Before hitting enter, on your second SSH session, copy customerCA.crt into the /hsm-config directory in /var/virtru/cks

      2. The connection to the HSM from the CKS requires the certificate to reside in the /hsm-config directory, which did not exist before selecting the HSM option for your key management

    3. The slot label will be hsm1 when prompted

      Screenshot 2023-10-05 at 1.28.06 PM.png

       

    4. For the key pair label, enter rsa001

    5. Use your created CU user and password for the pin (example: cryptouser:<password>)

    6. Continue with remaining Virtru Private Keystore install setup

 

 

Upgrade Procedure From Existing Virtru Private Keystore (Import Keys and Connect Virtru Private Keystore to HSM)

Run Key Management Utility

  1. sudo service cloudhsm-client start

    1. /opt/cloudhsm/bin/key_mgmt_util

    2. Login as the crypto user

      1. loginHSM -u CU -s cryptouser -p <password>

    3. Find all keys for the current user

      1. findKey

    4. If any keys need to be deleted as they will not be part of this integration, do so with the following command:

      • deleteKey -k <keyHandle>

        Screen_Shot_2021-04-19_at_3.51.13_PM.pngScreen_Shot_2021-04-19_at_3.50.25_PM.png

    5. Check if any keys remain on the HSM

      • findKey

        Screen_Shot_2021-04-19_at_3.52.29_PM.png

Import key pair from file system on existing Virtru Private Keystore

  1. If running the CloudHSM instance of CKS on a separate host, copy over rsa001.pem and rsa001.pub from your CKS host

    1. There are 2 distinct commands here to import the public and then import the private key. We’ll do each step by step according to the linked AWS documentation

    2. Import the public key

      1. Private keys need to be .key, Virtru generated CKS private keys are .pem

        1. mv rsa001.pem rsa001.key

      2. Public keys need to be .pem, Virtru generated CKS public keys are .pub

        1. mv rsa001.pub rsa001.pem

      3. Start key_mgmt_util and log in as cryptouser:

        1. /opt/cloudhsm/bin/key_mgmt_util

        2. loginHSM -u CU -s cryptouser -p cryptouser123

      4. importPubKey -l rsa001 -f rsa001.pem

        1. Public Key Label: prodkey

        2. Public Key Handle: <pubKeyHandle>

        Important Note

        All keys needing to be read by the CKS need to have the same label, you may opt to label keys something more generic

    3. Create wrapping key required for importing private key

      1. genSymKey - AWS CloudHSM

      2. genSymKey -t 31 -s 32 -l aes256

        Screen_Shot_2021-04-20_at_9.54.09_AM.png

        Wrapping Key Handle: <wrappingKeyHandle>

        1. Note this handle, as you will need to import all private keys with this wrapping key as part of the command.

    4. Import the private key

      1. importPrivateKey -f rsa001.key -l rsa001 -w <wrappingKeyHandle>

        Screen_Shot_2021-04-20_at_9.56.03_AM.png

        Private Key Handle: <privKeyHandle>

Verify imported keys are in HSM cluster

  1. findKey

  2. Repeat step 2 and 3 for any additional key pairs. As noted in step 2, ALL imported keys must have the same label to be read by the CKS, as opposed to importing key pairs as rsa001, rsa002, etc.

Backup and Upgrade Virtru Private Keystore

  1. Follow the procedure to back up and upgrade your Virtru Private Keystore: Virtru Private Keystore Upgrade

  • After running the primary setup script to completion, within your cks-setup-scripts directory you will run the setup-cks-hsm-latest.sh script

        1. Before running the HSM integration, SSH into the machine on a second connection.

      2. Enter IP address retrieved when connecting host to HSM (Retrieve IP from HSM cluster in AWS web console)

        1. Before hitting enter, on your second SSH session, copy customerCA.crt into the /hsm-config directory in /var/virtru/cks

        2. The connection to the HSM from the CKS requires the certificate to reside in the /hsm-config directory, which did not exist before selecting the HSM option for your key management

      3. The slot label will be hsm1 when prompted

        Screenshot 2023-10-05 at 1.28.06 PM.png

         

      4. For the key pair label, enter rsa001

      5. Use your created CU user and password for the pin (example: cryptouser:<password>)

      6. Continue with remaining Virtru Private Keystore install setup

Related articles