AWS CloudHSM
User Guide

Getting Started with key_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 key_mgmt_util command line tool, see the following topics.

If you encounter an error message or unexpected outcome for a command, see the Troubleshooting AWS CloudHSM topics for help. For details about the key_mgmt_util commands, see key_mgmt_util Command Reference.

Set Up key_mgmt_util

Complete the following setup before you use key_mgmt_util.

Start the AWS CloudHSM Client

Before you use key_mgmt_util, you must start the AWS CloudHSM client. The client is a daemon that establishes end-to-end encrypted communication with the HSMs in your cluster. The key_mgmt_util tool uses the client connection to communicate with the HSMs in your cluster. Without it, key_mgmt_util doesn't work.

To start the AWS CloudHSM client

Use the following command to start the AWS CloudHSM client.

Amazon LinuxAmazon Linux 2CentOS 6CentOS 7RHEL 6RHEL 7Ubuntu 16.04 LTSWindows
Amazon Linux
$ sudo start cloudhsm-client
Amazon Linux 2
$ sudo service cloudhsm-client start
CentOS 6
$ sudo start cloudhsm-client
CentOS 7
$ sudo service cloudhsm-client start
RHEL 6
$ sudo start cloudhsm-client
RHEL 7
$ sudo service cloudhsm-client start
Ubuntu 16.04 LTS
$ sudo service cloudhsm-client start
Windows
C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg

Start key_mgmt_util

After you start the AWS CloudHSM client, use the following command to start key_mgmt_util.

Amazon LinuxAmazon Linux 2RHEL 6RHEL 7CentOS 6CentOS 7Ubuntu 16.04 LTSWindows
Amazon Linux
$ /opt/cloudhsm/bin/key_mgmt_util
Amazon Linux 2
$ /opt/cloudhsm/bin/key_mgmt_util
RHEL 6
$ /opt/cloudhsm/bin/key_mgmt_util
RHEL 7
$ /opt/cloudhsm/bin/key_mgmt_util
CentOS 6
$ /opt/cloudhsm/bin/key_mgmt_util
CentOS 7
$ /opt/cloudhsm/bin/key_mgmt_util
Ubuntu 16.04 LTS
$ /opt/cloudhsm/bin/key_mgmt_util
Windows
c:\Program Files\Amazon\CloudHSM>key_mgmt_util.exe

The prompt changes to Command: when key_mgmt_util is running.

If the command fails, such as returning a Daemon socket connection error message, try updating your configuration file.

Basic Usage of key_mgmt_util

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

Log In to the HSMs

Use the loginHSM command to log in to the HSMs. The following command logs in as a crypto user (CU) named example_user. The output indicates a successful login for all three HSMs in the cluster.

Command: loginHSM -u CU -s example_user -p <password> Cfm3LoginHSM returned: 0x00 : HSM Return: SUCCESS Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

The following shows the syntax for the loginHSM command.

Command: loginHSM -u <user type> -s <username> -p <password>

Log Out from the HSMs

Use the logoutHSM command to log out from the HSMs.

Command: logoutHSM Cfm3LogoutHSM returned: 0x00 : HSM Return: SUCCESS Cluster Error Status Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

Stop key_mgmt_util

Use the exit command to stop key_mgmt_util.

Command: exit