Install and use the AWS CloudHSM JCE provider for Client SDK 5 - AWS CloudHSM
Install the JCE providerProvide credentials to the JCE providerKey management basics in the JCE provider

Install and use the AWS CloudHSM JCE provider for Client SDK 5

The JCE provider is compatible with OpenJDK 8, OpenJDK 11, OpenJDK 17, and OpenJDK 21. You can download both from the OpenJDK website.

Note

To run a single HSM cluster with Client SDK 5, you must first manage client key durability settings by setting disable_key_availability_check to True. For more information, see Key Synchronization and Client SDK 5 Configure Tool.

Install the JCE provider

  1. Use the following commands to download and install the JCE provider.

    Amazon Linux 2

    Install the JCE provider for Amazon Linux 2 on x86_64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm

    Install the JCE provider for Amazon Linux 2 on ARM64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.aarch64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.el7.aarch64.rpm
    Amazon Linux 2023

    Install the JCE provider for Amazon Linux 2023 on x86_64 architecture:

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

    Install the JCE provider for Amazon Linux 2023 on ARM64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.aarch64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.amzn2023.aarch64.rpm
    CentOS 7 (7.8+)

    Install the JCE provider for CentOS 7 on x86_64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm
    RHEL 7 (7.8+)

    Install the JCE provider for RHEL 7 on x86_64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm
    RHEL 8 (8.3+)

    Install the JCE provider for RHEL 8 on x86_64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.x86_64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.el8.x86_64.rpm
    RHEL 9 (9.2+)

    Install the JCE provider for RHEL 9 (9.2+) on x86_64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.x86_64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.el9.x86_64.rpm

    Install the JCE provider for RHEL 9 (9.2+) on ARM64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.aarch64.rpm
    $ sudo yum install ./cloudhsm-jce-latest.el9.aarch64.rpm
    Ubuntu 20.04 LTS

    Install the JCE provider for Ubuntu 20.04 LTS on x86_64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Focal/cloudhsm-jce_latest_u20.04_amd64.deb
    $ sudo apt install ./cloudhsm-jce_latest_u20.04_amd64.deb
    Ubuntu 22.04 LTS

    Install the JCE provider for Ubuntu 22.04 LTS on x86_64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_amd64.deb
    $ sudo apt install ./cloudhsm-jce_latest_u22.04_amd64.deb

    Install the JCE provider for Ubuntu 22.04 LTS on ARM64 architecture:

    $ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_arm64.deb
    $ sudo apt install ./cloudhsm-jce_latest_u22.04_arm64.deb
    Windows Server 2016

    Install the JCE provider for Windows Server 2016 on x86_64 architecture, open PowerShell as an administrator and run the following command:

    PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMJCE-latest.msi -Outfile C:\AWSCloudHSMJCE-latest.msi
    PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMJCE-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
    Windows Server 2019

    Install the JCE provider for Windows Server 2019 on x86_64 architecture, open PowerShell as an administrator and run the following command:

    PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMJCE-latest.msi -Outfile C:\AWSCloudHSMJCE-latest.msi
    PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMJCE-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait

  2. Bootstrap Client SDK 5. For more information about bootstrapping, see Bootstrap the Client SDK.

  3. Locate the following JCE provider files:

    Linux

    • /opt/cloudhsm/java/cloudhsm-version.jar

    • /opt/cloudhsm/bin/configure-jce

    • /opt/cloudhsm/bin/jce-info

    Windows

    • C:\Program Files\Amazon\CloudHSM\java\cloudhsm-version.jar>

    • C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe

    • C:\Program Files\Amazon\CloudHSM\bin\jce_info.exe

Provide credentials to the JCE provider

Before your Java application can use an HSM, the HSM needs to first authenticate the application. HSMs authenticate using either an explicit login or implicit login method.

Explicit login – This method lets you provide AWS CloudHSM credentials directly in the application. It uses the method from the AuthProvider, where you pass a CU username and password in the pin pattern. For more information, see Login to an HSM code example.

Implicit login – This method lets you set AWS CloudHSM credentials either in a new property file, system properties, or as environment variables.

  • System properties – Set credentials through system properties when running your application. The following examples show two different ways that you can do this:

    Linux
    $ java -DHSM_USER=<HSM user name> -DHSM_PASSWORD=<password>
    System.setProperty("HSM_USER","<HSM user name>");
System.setProperty("HSM_PASSWORD","<password>");
    Windows
    PS C:\> java -DHSM_USER=<HSM user name> -DHSM_PASSWORD=<password>
    System.setProperty("HSM_USER","<HSM user name>");
System.setProperty("HSM_PASSWORD","<password>");

  • Environment variables – Set credentials as environment variables.

    Linux
    $ export HSM_USER=<HSM user name>
$ export HSM_PASSWORD=<password>
    Windows
    PS C:\> $Env:HSM_USER="<HSM user name>"
PS C:\> $Env:HSM_PASSWORD="<password>"

Credentials might not be available if the application does not provide them or if you attempt an operation before the HSM authenticates session. In those cases, the CloudHSM software library for Java searches for the credentials in the following order:

  1. System properties

  2. Environment variables

Key management basics in the JCE provider

The basics on key management in the JCE provider involve importing keys, exporting keys, loading keys by handle, or deleting keys. For more information on managing keys, see the Manage keys code example.

You can also find more JCE provider code examples at Code samples.