Appendix A - Migrate from SDK3 to SDK5

For the AWS specific version of the migration process from SDK3 to SDK5, please see the AWS PKCS11 migration documentation here.

Start by stopping EJBCA or SignServer:

systemctl stop wildfly

Remove the old CloudHSM client and PKCS11 library

sudo yum remove cloudhsm-client

Install the new SDK5 CloudHSM PKCS11 Library

Start by downloading the proper client for your Linux distribution and architecture from the following page:

https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html

Install the new client with a yum command and the URL associated with your distribution. For example, on Amazon Linux 2023 with X84_64 architecture use the following command:

sudo yum install https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm

Install the new SDK5 CloudHSM CLI

sudo yum install https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-cli-latest.amzn2023.x86_64.rpm

Determine the IP address of your cluster. You can get one of the CloudHSM IP addresses from the AWS Console or from the AWS CLI if you have it installed. From the AWS CLI on the node, use the following:

aws cloudhsmv2 describe-clusters

Configure the HSM client to know the location of your HSM client certificate. This is typically located at /opt/cloudhsm/etc/customerCA.crt.

sudo /opt/cloudhsm/bin/configure-pkcs11 --hsm-ca-cert /opt/cloudhsm/etc/customerCA.crt -a <HSM_IP_ADDRESS>

If you are using a single HSM in the cluster the HSM client needs to be aware of this. There is a Key Durability Check that needs to be disabled. If you have more than one HSM in the cluster, this can be skipped.

sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check
sudo /opt/cloudhsm/bin/configure-cli --disable-key-availability-check

Start WildFly

systemctl start wildfly

Continue to the next page to Configure the Crypto Token