Menu
AWS CloudHSM
User Guide

Getting Started with cloudhsm_mgmt_util

AWS CloudHSM includes two command line tools with the AWS CloudHSM client software. The cloudhsm_mgmt_util tool includes commands to manage HSM users. The key_mgmt_utiltool includes commands to manage keys. To get started with the cloudhsm_mgmt_util command line tool, see the following topics.

Prepare to run cloudhsm_mgmt_util

Complete the following steps before you use cloudhsm_mgmt_util. You need to do these steps the first time you use cloudhsm_mgmt_util and after you add or remove HSMs in your cluster.

In these steps, you will update the HSM list in the configuration files that the AWS CloudHSM client and command line tools use. Keeping these files updated helps AWS CloudHSM to synchronize data and maintain consistency across all HSMs in the cluster.

Step 1: Stop the AWS CloudHSM Client

Before you update the configuration files that the AWS CloudHSM and command line tools use, stop the AWS CloudHSM client. If the client is already stopped, running the stop command has no harmful effect.

$ sudo stop cloudhsm-client

Step 2: Update the AWS CloudHSM Configuration Files

This step uses the -a parameter of the Configure tool which adds the elastic network interface (ENI) IP address of one of the HSMs in the cluster to the configuration files that the AWS CloudHSM client and command line tools use.

$ sudo /opt/cloudhsm/bin/configure -a <ENI IP>

To get the ENI IP address of an HSM in your cluster, you can use the DescribeClusters operation, the describe-clusters command, or the Get-HSM2Cluster PowerShell cmdlet. Enter only one ENI IP address, no matter how many HSMs you have in your cluster. It does not matter which HSM ENI IP address you select.

Step 3: Start the AWS CloudHSM Client

Next, start or restart the AWS CloudHSM client. When the AWS CloudHSM client starts, it uses the ENI IP address in its configuration file to query the cluster. Then, it adds the ENI IP addresses of all HSMs in the cluster to the cluster information file.

$ sudo start cloudhsm-client

Step 4: Update the cloudhsm_mgmt_util Configuration File

The final step uses the -m parameter of the Configuration tool to copy the updated ENI IP addresses from the cluster information file to the configuration file that cloudhsm_mgmt_util uses. If you skip this step, you might run into synchronization problems, such as inconsistent user data in your cluster's HSMs.

$ sudo /opt/cloudhsm/bin/configure -m

When this step completes, you are ready to start cloudhsm_mgmt_util. If you add or delete HSMs at any time, be sure to repeat this procedure before using cloudhsm_mgmt_util.

Basic Usage of cloudhsm_mgmt_util

See the following topics for the basic usage of the cloudhsm_mgmt_util tool.

Note

The cloudhsm_mgmt_util tool doesn't support auto-completing commands with the Tab key. Don't use the Tab key with cloudhsm_mgmt_util, because that can make the tool unresponsive.

Start cloudhsm_mgmt_util

Use the following command to start cloudhsm_mgmt_util.

$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg Connecting to the server(s), it may take time depending on the server(s) load, please wait... Connecting to server '10.0.2.9': hostname '10.0.2.9', port 2225... Connected to server '10.0.2.9': hostname '10.0.2.9', port 2225. Connecting to server '10.0.3.11': hostname '10.0.3.11', port 2225... Connected to server '10.0.3.11': hostname '10.0.3.11', port 2225. Connecting to server '10.0.1.12': hostname '10.0.1.12', port 2225... Connected to server '10.0.1.12': hostname '10.0.1.12', port 2225.

The prompt changes to aws-cloudhsm> when cloudhsm_mgmt_util is running.

Enable End-to-End Encryption

Use the enable_e2e command to establish end-to-end encrypted communication between cloudhsm_mgmt_util and the HSMs in your cluster. You should enable end-to-end encryption each time you start cloudhsm_mgmt_util.

aws-cloudhsm>enable_e2e E2E enabled on server 0(10.0.2.9) E2E enabled on server 1(10.0.3.11) E2E enabled on server 2(10.0.1.12)

Log in to the HSMs

Use the loginHSM command to log in to the HSMs. Any user of any type can use this command to log in to the HSMs.

The command in following example logs in admin, which is the default crypto officer (CO). You set this user's password when you activated the cluster. The output shows that the command logged the admin user in to all of the HSMs in the cluster.

Warning

When you log in to cloudhsm_mgmt_util, verify that the ENI IP addresses in the success messages exactly match the ENI IP addresses of all HSMs in the cluster. If they do not, stop and run all steps in the Prepare to run cloudhsm_mgmt_util procedure.

To get the ENI IP addresses of the HSMs in your cluster, the DescribeClusters operation, the describe-clusters command, or the Get-HSM2Cluster PowerShell cmdlet.

aws-cloudhsm>loginHSM CO admin <password> loginHSM success on server 0(10.0.2.9) loginHSM success on server 1(10.0.3.11) loginHSM success on server 2(10.0.1.12)

The following shows the syntax for the loginHSM command.

aws-cloudhsm>loginHSM <user type> <user name> <password>

Log Out from the HSMs

Use the logoutHSM command to log out of the HSMs.

aws-cloudhsm>logoutHSM logoutHSM success on server 0(10.0.2.9) logoutHSM success on server 1(10.0.3.11) logoutHSM success on server 2(10.0.1.12)

Stop cloudhsm_mgmt_util

Use the quit command to stop cloudhsm_mgmt_util.

aws-cloudhsm>quit disconnecting from servers, please wait...