AWS CloudHSM
User Guide

Install and Use the AWS CloudHSM Software Library for Java

Before you can use the AWS CloudHSM software library for Java, you need the AWS CloudHSM client.

The client is a daemon that establishes end-to-end encrypted communication with the HSMs in your cluster. The Java library communicates locally with the client. If you haven't installed and configured the AWS CloudHSM client package, do that now by following the steps at Install the Client (Linux). After you install and configure the client, use the following command to start it.

Note that the AWS CloudHSM software library for Java is supported only on Linux and compatible operating systems.

Amazon LinuxAmazon Linux 2CentOS 6CentOS 7RHEL 6RHEL 7Ubuntu 16.04 LTS
Amazon Linux
$ sudo start cloudhsm-client
Amazon Linux 2
$ sudo service cloudhsm-client start
CentOS 6
$ sudo start cloudhsm-client
CentOS 7
$ sudo service cloudhsm-client start
RHEL 6
$ sudo start cloudhsm-client
RHEL 7
$ sudo service cloudhsm-client start
Ubuntu 16.04 LTS
$ sudo service cloudhsm-client start

Installing the Java Library

Use the following commands to download and install or update the AWS CloudHSM Java library. This library is supported only on Linux and compatible operating systems.

Amazon LinuxAmazon Linux 2CentOS 6CentOS 7RHEL 6RHEL 7Ubuntu 16.04 LTS
Amazon Linux
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-jce-latest.el6.x86_64.rpm
$ sudo yum install -y ./cloudhsm-client-jce-latest.el6.x86_64.rpm
Amazon Linux 2
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
$ sudo yum install -y ./cloudhsm-client-jce-latest.el7.x86_64.rpm
CentOS 6
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-jce-latest.el6.x86_64.rpm
$ sudo yum install -y ./cloudhsm-client-jce-latest.el6.x86_64.rpm
CentOS 7
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
$ sudo yum install -y ./cloudhsm-client-jce-latest.el7.x86_64.rpm
RHEL 6
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-client-jce-latest.el6.x86_64.rpm
$ sudo yum install -y ./cloudhsm-client-jce-latest.el6.x86_64.rpm
RHEL 7
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-client-jce-latest.el7.x86_64.rpm
$ sudo yum install -y ./cloudhsm-client-jce-latest.el7.x86_64.rpm
Ubuntu 16.04 LTS
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-client-jce_latest_amd64.deb
$ sudo dpkg -i cloudhsm-client-jce_latest_amd64.deb

After you run the preceding commands, you can find the following Java library files:

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

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

  • /opt/cloudhsm/java/hamcrest-all-1.3.jar

  • /opt/cloudhsm/java/junit.jar

  • /opt/cloudhsm/java/log4j-api-2.8.jar

  • /opt/cloudhsm/java/log4j-core-2.8.jar

  • /opt/cloudhsm/lib/libcaviumjca.so

Validating the Installation

Perform basic operations on the HSM to validate the installation.

To validate Java library installation

  1. (Optional) If you don't already have Java installed in your environment, use the following command to install it.

    Linux (and compatible libraries)Ubuntu
    Linux (and compatible libraries)
    $ sudo yum install -y java-1.8.0-openjdk
    Ubuntu
    $ sudo apt-get install openjdk-8-jre
  2. Use the following commands to set the necessary environment variables. Replace <HSM user name> and <password> with the credentials of a crypto user (CU).

    $ export LD_LIBRARY_PATH=/opt/cloudhsm/lib
    $ export HSM_PARTITION=PARTITION_1
    $ export HSM_USER=<HSM user name>
    $ export HSM_PASSWORD=<password>
  3. Use the following command to run the basic functionality test. If successful, the command's output should be similar to the one that follows.

    $ java8 -classpath "/opt/cloudhsm/java/*" org.junit.runner.JUnitCore TestBasicFunctionality JUnit version 4.11 .2018-08-20 17:53:48,514 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:33) - Adding provider. 2018-08-20 17:53:48,612 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:42) - Logging in. 2018-08-20 17:53:48,612 INFO [main] cfm2.LoginManager (LoginManager.java:104) - Looking for credentials in HsmCredentials.properties 2018-08-20 17:53:48,612 INFO [main] cfm2.LoginManager (LoginManager.java:122) - Looking for credentials in System.properties 2018-08-20 17:53:48,613 INFO [main] cfm2.LoginManager (LoginManager.java:130) - Looking for credentials in System.env SDK Version: 2.03 2018-08-20 17:53:48,655 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:54) - Generating AES Key with key size 256. 2018-08-20 17:53:48,698 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:63) - Encrypting with AES Key. 2018-08-20 17:53:48,705 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:84) - Deleting AES Key. 2018-08-20 17:53:48,707 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:92) - Logging out. Time: 0.205 OK (1 test)

Providing Credentials to the Java Library

HSMs need to authenticate your Java application before the application can use them. Each application can use one session. HSMs authenticate a session by using either explicit login or implicit login method.

Explicit login – This method lets you provide CloudHSM credentials directly in the application. It uses the LoginManager.login() method, where you pass the CU user name, password, and the HSM partition ID. For more information about using the explicit login method, see the Login to an HSM code example.

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

  • New property file – Create a new file named HsmCredentials.properties and add it to your application's CLASSPATH. The file should contain the following:

    HSM_PARTITION = PARTITION_1 HSM_USER = <HSM user name> HSM_PASSWORD = <password>
  • System properties – Set credentials through system properties when running your application. The following examples show two different ways that you can do this:

    $ java -DHSM_PARTITION=PARTITION_1 -DHSM_USER=<HSM user name> -DHSM_PASSWORD=<password>
    System.setProperty("HSM_PARTITION","PARTITION_1"); System.setProperty("HSM_USER","<HSM user name>"); System.setProperty("HSM_PASSWORD","<password>");
  • Environment variables – Set credentials as environment variables.

    $ export HSM_PARTITION=PARTITION_1 $ export HSM_USER=<HSM user name> $ export 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. HsmCredentials.properties

  2. System properties

  3. Environment variables

Error handling

The error handling is easier with the explicit login than the implicit login method. When you use the LoginManager class, you have more control over how your application deals with failures. The implicit login method makes error handling difficult to understand when the credentials are invalid or the HSMs are having problems in authenticating session.

Key Management Basics in the Java Library

The basics on key management in the Java library 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 Java library code examples at Java Samples.