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 JAR file from Artifactory.

Steps

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.
Click Next.
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.
Click Next.
Upload the customerHSMCertificate as the cluster certificate, and the customerCA certificate 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:

wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-latest.el7.x86_64.rpm

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 ec2-user@ec2-3-249-200-193.eu-west-1.compute.amazonaws.com:~

Move the certificate to the correct directory on the EC2 host:

ssh -i "nickd-keypair-4.pem" ec2-user@ec2-3-249-200-193.eu-west-1.compute.amazonaws.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:

wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm

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:

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

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-hsm directory and build the sample-hsm code:
```
./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 hsmtest:

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 .

Create a utilities subdirectory in hsmtest:

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 .

Create a drivers subdirectory in hsmtest:

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/

Create a .tar file containing the hsmtest directory:

tar cvfz hsmtest.tar.gz hsmtest/
ls -ltr hsmtest.tar.gz

Deploy the compressed .tar file 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>:~

Unzip the .tar file 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 partition field 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.