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.
Topics
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.
Topics
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.cfgConnecting 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_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 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>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...
