Using AWS CloudHSM with F5 BIG-IP

Articles F5 Technical Articles
, ,
1

A hardware security module (HSM) is a computing device that processes cryptographic operations and provides secure storage for cryptographic keys. HSM devices are sold by many vendors for installation in customer data centers and are also made available by most public cloud providers. For example, Amazon Web Services (AWS) provides HSM devices under the AWS CloudHSM brand.

BIG-IP can access HSM devices over the network using a Public Key Cryptography Standard (PKCS) #11 Client SDK provided by the HSM vendor.

With the release of TMOS version 17.5.1, BIG-IP now supports the latest AWS CloudHSM hardware security module (HSM) type, hsm2m.medium, and the latest AWS CloudHSM Client SDK, version 5.

Note: By the end of 2025, AWS will remove support for hsm1.medium and Client SDK 3.

Let’s take a look at the steps required to configure BIG-IP to work with AWS CloudHSM using the AWS CloudHSM Client SDK version 5.

 

Software Installation

AWS makes the CloudHSM Client SDK available on its website. It can be downloaded directly to a BIG-IP using the following command in the bash shell:

curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-5.16.1-1.el7.x86_64.rpm

Then install the software like so:

rpm -ivh cloudhsm-pkcs11-5.16.1-1.el7.x86_64.rpm

Note: Unlike Client SDK 3, there is no client daemon that needs to be installed and set to run at boot.

 

Prerequisites

Four items need to be provided by the CloudHSM administrator to configure the BIG-IP instance:

  1. The IP address of one of the HSM devices in the CloudHSM cluster.
  2. The CloudHSM “issuing certificate” created during cluster initialization (normally has the filename customerCA.crt)
  3. The username and password for a Crypto User account the BIG-IP will use to authenticate to the CloudHSM cluster. Don’t forget to put a colon “:” between the username and password in the tmsh command below.
  4. The VPC Security Group created for the CloudHSM cluster. (The name starts with "

cloudhsm-cluster-") The BIG-IP must have this security group in its EC2 config.

 

Software Configuration

On the BIG-IP, copy the CloudHSM issuing certificate to this filename:

/opt/cloudhsm/etc/customerCA.crt

Bootstrap the Client SDK on the BIG-IP using the following bash commands:

/opt/cloudhsm/bin/configure-pkcs11 -a <em><span class="lia-text-color-8"><HSM IP address><br><br></span></em><span class="lia-text-color-8"><span class="lia-text-color-21">tmsh create sys crypto fips external-hsm vendor auto pkcs11-lib-path /opt/cloudhsm/lib/libcloudhsm_pkcs11.so<br><br>tmsh create sys crypto fips nethsm-partition auto password "<em><span class="lia-text-color-8"><</span></em><span class="lia-text-color-8"><em>username><span class="lia-text-color-21">:</span><password></em></span>"<br><br>bigstart start pkcs11d</span></span><em><span class="lia-text-color-8"><br><br></span></em>

 

Test access to the HSM from the BIG-IP

Use this tmsh command to verify access to the CloudHSM cluster:

tmsh run sys crypto nethsm-test<br><br>

Output of a successful test:

<br>[Info]: Begin<br>Testing on the partition with label: auto                            <br>[Info]: Pass<br>[Sanity]: Begin<br>[Sanity]: Pass<br>[RSA2K]: Begin<br>[RSA2K]: Pass<br>[RSA4K]: Begin<br>[RSA4K]: Pass<br>[ECDSA_PRIME256v1_SHA256]: Begin<br>[ECDSA_PRIME256v1_SHA256]: Pass<br>[ECDSA_PRIME256v1_SHA384]: Begin<br>[ECDSA_PRIME256v1_SHA384]: Pass<br>[ECDSA_PRIME256v1_SHA512]: Begin<br>[ECDSA_PRIME256v1_SHA512]: Pass<br>[ECDSA_SECP384R1_SHA256]: Begin<br>[ECDSA_SECP384R1_SHA256]: Pass<br>[ECDSA_SECP384R1_SHA384]: Begin<br>[ECDSA_SECP384R1_SHA384]: Pass<br>[ECDSA_SECP384R1_SHA512]: Begin<br>[ECDSA_SECP384R1_SHA512]: Pass<br>Test Done(F=0)!

 

Logfiles for troubleshooting

Logfiles for the CloudHSM Client SDK can be found in:

/opt/cloudhsm/run

Log messages for PKCS can be found in the LTM log with the following bash command:

grep -i pkcs /var/log/ltm

 

Additional Resources:

1 Like
2

You can migrate from SDK 3 to SDK 5 with an existing HSM1 cluster. The customerCA.crt file should already be on your BIG-IP with SDK 3 and can be reused with SDK 5. Here are the migration steps:

1) Save a copy of the existing customerCA.crt file, get the IP address of the existing CloudHSM cluster, and stop the SDK 3 client daemon.

cp /opt/cloudhsm/etc/customerCA.crt .
grep hostname /opt/cloudhsm/etc/cloudhsm_client.cfg
service cloudhsm-client stop`

2) Determine the names of the SDK 3 RPMs and uninstall (erase) them.

rpm -qa | grep cloudhsm
rpm -ev cloudhsm-client-pkcs11-3.4.4-1.el7.x86_64
rpm -ev cloudhsm-client-3.4.4-1.el7.x86_64

3) Download and install CloudHSM SDK 5.

curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.x86_64.rpm
rpm -ivh cloudhsm-pkcs11-latest.el7.x86_64.rpm

4) Copy customerCA.crt back where it belongs and configure SDK 5 with the IP address of the existing CloudHSM cluster.

cp customerCA.crt /opt/cloudhsm/etc
/opt/cloudhsm/bin/configure-pkcs11 -a <HSM Cluster IP>

3

On the older version of the HSM client which is not required any longer, we could login to the HSM as CO/CU to manage and remove certs, does the new SDK enable F5 interaction for the certs where delete will actually remove them? If not, without a client, how can we clean/validate existing certs on CloudHSM?

4

Yes, there is a CLI for CloudHSM SDK 5 and it does run on BIG-IP. Here’s how you install it:

curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-cli-latest.el7.x86_64.rpm
rpm -ivh cloudhsm-cli-latest.el7.x86_64.rpm
/opt/cloudhsm/bin/configure-cli -a <IP address of HSM>

Docs for the CloudHSM CLI

1 Like
5

There is an issue with the latest release of the CloudHSM client library. Use this one instead:

curl -O https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-5.16.1-1.el7.x86_64.rpm
6

The GUI shows support for ECDSA and a secp384r1 curve. I have confirmed ECDSA and prime256v1 cureve will create a key on HSM, but NOT secp384r1. Any thoughts or insights?