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.
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.
Tasks
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.
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.
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.
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.
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.
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.
Tasks
Start cloudhsm_mgmt_util
Use the following command to start cloudhsm_mgmt_util.
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_e2eE2E 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.
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>logoutHSMlogoutHSM 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>quitdisconnecting 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
