AWS CloudHSM

User Guide

AWS Documentation » AWS CloudHSM » User Guide » Using the AWS CloudHSM Software Libraries » AWS CloudHSM Software Library for Java » Install and Use the AWS CloudHSM Software Library for Java

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.

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.

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

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.

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:

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.

On this page:

• Installing the Java Library
• Validating the Installation
• Providing Credentials to the Java Library
• Key Management Basics in the Java Library