Testing an HSM integration
To test an HSM implementation both Corda Enterprise and the HSM must be deployed. This guide will run through testing an example HSM using the Technical Compatibility Kit (TCK) when deployed virtually to AWS.
This is an example configuration to demonstrate running the TCK and showing the results.
Before you begin
For this process you must have completed the following tasks:
- Install Git Bash and OpenSSL.
- Create a signing key and certificate using OpenSSL.
- Have access to an AWS instance.
- Download Corda Enterprise utilities
.jarfile from Artifactory.
- Create a virtual private cloud (VPC).
- Create the HSM cluster.
- Create signed certificates.
- Initialise the cluster using the signed certificates.
- Create the EC2 instance.
- Log in to the EC2 host and set up the security group.
- Install and configure the local client.
- Authenticate the HSM client.
- Install the JCE provider.
- Activate the HSM cluster and set user passwords.
- Set up Corda Enterprise and the TCK.
- Run the TCK tests.
Step One: Create the virtual private cloud
Sign in to AWS.
Open the management console and ensure you are in the correct region.
Search for VPC and click Launch VPC Wizard. The VPC should be created with the following configuration:
- VPC with Public and Private Subnets.
- No IPv6 CIDR Block.
- Name the VPC and subnets.
- Enable DNS hostnames.
Click Create VPC then click OK.
Step Two: Create the HSM cluster in the subnet
Navigate to the CloudHSM page: https://console.aws.amazon.com/cloudhsm.
Ensure that your region is correctly set.
Click Create cluster.
Configure the cluster with the following information:
- Select the VPC created earlier.
- Select the availability zone created earlier.
Add a tag that you can search for later, and click Review.
Click Create cluster. This may take several minutes.
After the cluster has been created, select it in the cluster list and click Initialize.
Select the correct private subnet in the list, and click Create. This may take several minutes.
Click Cluster CSR. This will download the certificate signing request associated with the HSM to a local directory.
Next, the CSR must be used to create certificates locally.
Step Three: Create signed certificates
Move the downloaded CSR to the same directory as your private key.
Create the signed certificates using the following command, replacing
<ClusterID>with the cluster identifier:
openssl x509 -req -days 3652 -in <clusterID>_ClusterCsr.csr \ -CA customerCA.crt \ -CAkey customerCA.key \ -CAcreateserial \ -out <clusterID>_CustomerHsmCertificate.crt
Step Four: Initialise the cluster with the signed certificate
Navigate to the CloudHSM page: https://console.aws.amazon.com/cloudhsm/.
Click the Actions drop-down list, and select Initialize.
customerHSMCertificateas the cluster certificate, and the
customerCAcertificate as the issuing certificate.
Click Upload and initialize.
Step Five: Create the EC2 instance
At this point there is one HSM user, defined as a Precrypto Officer (PRECO). You must update the password for this user, which will change the user type to Crypto Officer (CO).
Open the AWS command-line console here: https://console.aws.amazon.com/ec2.
Click Launch Instance and select Amazon Linux 2.
Select the large instance type, and click Configure Instance Details.
Select the VPC and public subnet created earlier, and enable Auto-assign Public IP.
Click Review and Launch, then click Launch.
Select Create Keypair, enter a name for the keypair, and click Download Keypair.
After downloading the keypair, click Launch instances.
Step Six: Log in to the EC2 host and set up the security group
Select the new instance. Select Actions then click Connect.
Copy the example command and run it to connect to the EC2 host.
In the same menu select Actions then Networking then Change Security Groups.
Select the HSM security group and click Assign Security Groups.
Step Seven: Install and configure the local client
Connect to the EC2 instance.
Download the cloud HSM package using the following command:
Install the cloud HSM package using the following command:
sudo yum install -y ./cloudhsm-client-latest.el7.x86_64.rpm
Navigate to the clusters tab.
Select the HSM cluster created earlier.
Copy the ENI IP address, and run the following command to set the configuration for the local client:
sudo /opt/cloudhsm/bin/configure -a <IP Address>
Step Eight: Authenticate the HSM client
Using a Git Bash shell on the local host, copy the signed certificate created earlier to the EC2 host:
cd sign scp -i "sign/nickd-keypair-4.pem" customerCA.crt firstname.lastname@example.org:~
Move the certificate to the correct directory on the EC2 host:
ssh -i "nickd-keypair-4.pem" email@example.com ls -ltr pwd sudo -i ls -ltr /opt/cloudhsm/etc whoami cp /home/ec2-user/customerCA.crt /opt/cloudhsm/etc exit ls -ltr /opt/cloudhsm/etc
Step Nine: Install the JCE provider
Connect to the EC2 instance.
Download the cloud JCE package using the following command:
Install the cloud JCE using the following command:
sudo yum install -y ./cloudhsm-client-jce-latest.el7.x86_64.rpm
Step Ten: Activate the HSM cluster and set user passwords
Connect to the EC2 instance.
Start the local client using the following command:
sudo service cloudhsm-client start
Activate the cluster using the following command:
Change the password for the Precrypto Officer user, and create a new Crypto Officer user:
enable_e2e listUsers loginHSM PRECO admin password changePswd PRECO admin corda createUser CO user password quit
Step Eleven: Setting up Corda Enterprise and TCK
Navigate to the HSM directory.
Navigate to the
samples-hsmdirectory and build the
./gradlew clean build -x test
Create a new local directory to contain the files to be hosted on AWS, in this example the directory is called
cd hsmtest cp <PATH_TO_TCK_JAR> . cp /hsm/samples-hsm/build/libs/hsm-root-1.0-SNAPSHOT.jar . cp /hsm/samples-hsm/hsm-aws-java/cloud-test/runHSMTests.sh . cp /hsm/samples-hsm/hsm-aws-java/cloud-test/runHSMTimeoutTests.sh . cp /hsm/samples-hsm/hsm-aws-java/src/test/resources/*.conf .
mkdir utils cd utils cp /hsm/samples-hsm/hsm-aws-java/cloud-test/runHSMCommand.sh . cp /hsm/samples-hsm/hsm-aws-java/cloud-test/deleteAllKeys.sh .
mkdir drivers mv hsm-root-1.0-SNAPSHOT.jar drivers/ cp /n/hsm/samples-hsm/hsm-aws-java/lib/cloudhsm-3.2.1.jar drivers/
.tarfile containing the
tar cvfz hsmtest.tar.gz hsmtest/ ls -ltr hsmtest.tar.gz
Deploy the compressed
.tarfile to the AWS EC2 host:
cd sign ssh -i <keypair-certificate> <AWS-ec2-address> hostname scp -i "<keypair-certificate>" hsmtest.tar.gz <AWS-ec2-address>:~
.tarfile on the EC2 host:
tar xvf hsmtest.tar.gz
Step Twelve: Running the TCK tests
To run the tests you must configure the credentials of the HSM. These credentials should match the username and password of the Crypto Officer earlier. Additionally, you must specify the
partitionfield of the HSM. The three files that must have credentials updated are:
service.tls.conf service.legal.conf service.confidential.conf
Before you run the TCK tests, you must clear any extraneous keys from the HSM using the following command:
cd /home/ec2-user/hsmtest/utils/ ./deleteAllKeys.sh
Run the standard TCK tests by running the following command:
cd /home/ec2-user/hsmtest/ ./runHSMTests.sh | tee out
The tests will take approximately 10 minutes to run. If any tests fail, the logs will be saved in a date- and time-stamped subdirectory.
If the standard tests pass, delete the keys as described in Step Two, and run the timeout tests by running the following command:
cd /home/ec2-user/hsmtest/utils/ ./deleteAllKeys.sh cd /home/ec2-user/hsmtest/ ./runHSMTimeoutTests.sh | tee out
The timeout tests may take over an hour to complete. The tests are designed to hang for up to 20 minutes in order to ensure that connections can be successfully re-established.