Install the JCE provider for AWS CloudHSM Client SDK 3
Before you can use the JCE provider, 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 JCE provider 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 JCE provider is supported only on Linux and compatible operating systems.
Use the following sections to install, validate, and provide credentials to the provider.
Topics
Step 1: Install the JCE provider
Use the following commands to download and install the JCE provider. This provider is supported only on Linux and compatible operating systems.
Note
For upgrading, see Upgrade Client SDK 3.
After you run the preceding commands, you can find the following JCE provider 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.17.1.jar -
/opt/cloudhsm/java/log4j-core-2.17.1.jar -
/opt/cloudhsm/lib/libcaviumjca.so
Step 2: Validate the installation
Perform basic operations on the HSM to validate the installation.
To validate JCE provider installation
-
(Optional) If you don't already have Java installed in your environment, use the following command to install it.
-
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> -
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 TestBasicFunctionalityJUnit 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)
Step 3: Provide credentials to the JCE provider
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
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.propertiesand add it to your application'sCLASSPATH. 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:
-
HsmCredentials.properties -
System properties
-
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.
