Getting Started with cloudhsm_mgmt_util - AWS CloudHSM
Prepare to run cloudhsm_mgmt_utilBasic Usage of cloudhsm_mgmt_utilUsing cloudhsm_mgmt_util Across Cloned Clusters

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_util tool includes commands to manage keys. To get started with the cloudhsm_mgmt_util command line tool, complete the following tasks.

Prepare to run cloudhsm_mgmt_util

Complete the following tasks 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. The steps 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.

Amazon Linux
$ sudo stop cloudhsm-client
Amazon Linux 2
$ sudo service cloudhsm-client stop
CentOS 7
$ sudo service cloudhsm-client stop
CentOS 8
$ sudo service cloudhsm-client stop
RHEL 7
$ sudo service cloudhsm-client stop
RHEL 8
$ sudo service cloudhsm-client stop
Ubuntu 16.04 LTS
$ sudo service cloudhsm-client stop
Ubuntu 18.04 LTS
$ sudo service cloudhsm-client stop
Windows

  • For Windows client 1.1.2+:

    C:\Program Files\Amazon\CloudHSM>net.exe stop AWSCloudHSMClient

  • For Windows clients 1.1.1 and older:

    Use Ctrl+C in the command window where you started the AWS CloudHSM client.

Step 2: Update the AWS CloudHSM Configuration Files

This step uses the -a parameter of the configure tool to add the elastic network interface (ENI) IP address of one of the HSMs in the cluster to the configuration file.

Amazon Linux
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
Amazon Linux 2
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
CentOS 7
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
CentOS 8
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
RHEL 7
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
RHEL 8
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
Ubuntu 16.04 LTS
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
Ubuntu 18.04 LTS
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
Windows
c:\Program Files\Amazon\CloudHSM>configure.exe -a <HSM ENI IP>

To get the ENI IP address of an HSM in your cluster, navigate to the AWS CloudHSM console, choose clusters, and select the desired cluster. You can also use the DescribeClusters operation, the describe-clusters command, or the Get-HSM2Cluster PowerShell cmdlet. Type only one ENI IP address. It does not matter which ENI IP address you use.

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.

Amazon Linux
$ sudo start cloudhsm-client
Amazon Linux 2
$ sudo service cloudhsm-client start
CentOS 7
$ sudo service cloudhsm-client start
CentOS 8
$ sudo service cloudhsm-client start
RHEL 7
$ sudo service cloudhsm-client start
RHEL 8
$ sudo service cloudhsm-client start
Ubuntu 16.04 LTS
$ sudo service cloudhsm-client start
Ubuntu 18.04 LTS
$ sudo service cloudhsm-client start
Windows

  • For Windows client 1.1.2+:

    C:\Program Files\Amazon\CloudHSM>net.exe start AWSCloudHSMClient

  • For Windows clients 1.1.1 and older:

    C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg

Step 4: Update the cloudhsm_mgmt_util Configuration File

The final step uses the -m parameter of the configure 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.

Amazon Linux
$ sudo /opt/cloudhsm/bin/configure -m
Amazon Linux 2
$ sudo /opt/cloudhsm/bin/configure -m
CentOS 7
$ sudo /opt/cloudhsm/bin/configure -m
CentOS 8
$ sudo /opt/cloudhsm/bin/configure -m
RHEL 7
$ sudo /opt/cloudhsm/bin/configure -m
RHEL 8
$ sudo /opt/cloudhsm/bin/configure -m
Ubuntu 16.04 LTS
$ sudo /opt/cloudhsm/bin/configure -m
Ubuntu 18.04 LTS
$ sudo /opt/cloudhsm/bin/configure -m
Windows
c:\Program Files\Amazon\CloudHSM>configure.exe -m

When this step is complete, 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

The following tasks cover the basic usage of the cloudhsm_mgmt_util tool.

Warning

The cloudhsm_mgmt_util tool doesn't support auto-completion using the Tab key. Using the Tab key with cloudhsm_mgmt_util can make it unresponsive.

Start cloudhsm_mgmt_util

Use the following command to start cloudhsm_mgmt_util.

Amazon Linux
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Amazon Linux 2
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
CentOS 7
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
CentOS 8
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
RHEL 7
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
RHEL 8
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Ubuntu 16.04 LTS
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Ubuntu 18.04 LTS
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Windows
C:\Program Files\Amazon\CloudHSM>cloudhsm_mgmt_util.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_mgmt_util.cfg

Output should be similar to the following depending on how many HSMs you have. 

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

Starting with version 1.1.1 of the client and related software libraries, end-to-end encrypted communication between cloudhsm_mgmt_util and the HSMs in your cluster is enabled by default. If you are using an earlier version, you can use the enable_e2e command to 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 the 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 in the admin user 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...

Using cloudhsm_mgmt_util Across Cloned Clusters

In some cases, you will use cloudhsm_mgmt_util to synchronize changes across cloned clusters. In order to do so, you will need to manually create a new cloudhsm_mgmt_util configuration file that specifies the HSMs you want to sync. For this example, create a copy of your current config file (/opt/cloudhsm/etc/cloudhsm_mgmt_config.cfg) and change the copy's name to syncConfig.cfg.

Edit syncConfig.cfg to include the Elastic Network Interface (ENI) IPs of the HSMs to be synced. We recommend that you specify the source HSM first, followed by the destination HSMs. To find the ENI IP of an HSM, see Update the AWS CloudHSM Configuration Files.

Initialize cloudhsm_mgmt_util with the new config file by issuing the following command: 

aws-cloudhsm> /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/userSync.cfg

Check the status messages returned to ensure that the cloudhsm_mgmt_util is connected to all desired HSMs and determine which of the returned ENI IPs corresponds to each cluster.

When you are done synchronizing HSMs or clusters, initialize cloudhsm_mgmt_util with the original configuration file. 

aws-cloudhsm> /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_config.cfg