Use HSMs with hsm_mgmt_tool - Key Management Service - Alibaba Cloud Documentation Center

The hsm_mgmt_tool is a command-line utility for managing HSM instances, users, and keys. Crypto Officer (CO) users use it to manage HSM instances and users. Crypto User (CU) users use it to share keys and manage key attributes.

Important

Before you run hsm_mgmt_tool commands, start hsm_mgmt_tool and log in to an HSM instance with the correct user type. For more information, see Permissions of HSM users.

Install the client

Download the HSM client package.
- CentOS
  - Method 1: Download the HSM client package.
  - Method 2: Run the following command on an ECS instance that has internet access.
```
wget -O hsm-client-v2.03.15.10-1.x86_64.rpm 'https://yundun-hsm4.oss-ap-southeast-1.aliyuncs.com/hsm-client-v2.03.15.10-1.x86_64.rpm'
```
  - Method 3: On the VSMs page, find the HSM instance and click the icon in the Specification column.
  - Method 4: On the Activate Cluster page, click Download HSM Management Tool.
- Debian
  Download hsm-client-2.03.15.10-20240710_1.x86_64.deb.

Install the client to the /opt/hsm directory.

CentOS

sudo yum install -y hsm-client-v2.03.15.10-1.x86_64.rpm

Debian

sudo dpkg -i hsm-client-2.03.15.10-20240710_1.x86_64.deb

Configure the client

Edit the servers section in the /opt/hsm/etc/hsm_mgmt_tool.cfg configuration file.

Set name and hostname to the private IP address of the primary HSM.
Set owner_cert_path to the path of the issuerCA.crt file.

Sample hsm_mgmt_tool.cfg file

{
 "servers": [
 {
 "name" : "172.16.XX.XX",
 "hostname" : "172.16.XX.XX",
 "port" : 2225,
 "certificate": "/opt/hsm/etc/client.crt",
 "pkey": "/opt/hsm/etc/client.key",
 "CAfile": "",
 "CApath": "/opt/hsm/etc/certs",
 "ssl_ciphers": "",
 "server_ssl" : "yes",
 "enable" : "yes",
 "owner_cert_path":"<issuerCA.crt file path>"
 }],
 "scard": {
 "enable": "no",
 "port": 2225,
 "ssl": "no",
 "ssl_ciphers": "",
 "certificate": "cert-sc",
 "pkey": "pkey-sc"
 }
}

Start and quit the tool

Start hsm_mgmt_tool:

/opt/hsm/bin/hsm_mgmt_tool /opt/hsm/etc/hsm_mgmt_tool.cfg

Quit hsm_mgmt_tool:

cloudmgmt> quit

Get help

List all available commands:

cloudmgmt> help

Get the syntax for a specific command:

cloudmgmt> help <command-name>

Command reference

The following table lists all hsm_mgmt_tool commands.

Command	Description	User type
changePswd	Changes a user password on an HSM instance. Any user can change their own password. CO users can change any user's password.	CO user
createUser	Creates a user of any type on an HSM instance.	CO user
deleteUser	Deletes a user of any type from an HSM instance.	CO user
findAllKeys	Lists the keys that a user owns or that are shared with them, along with a hash of the key ownership data for each HSM instance.	CO user, AU user
getAttribute	Gets the value of a key attribute and writes it to a file or to stdout.	CU user
getCert	Retrieves the certificate of an HSM instance and saves it in a specified format.	All users
getCertReq	Retrieves the certificate signing request (CSR) of an HSM instance and saves it in a specified format.	All users
getHSMInfo	Gets hardware information about the device that runs an HSM instance.	All users. No login required.
getKeyInfo	Gets a key's owner, shared users, and quorum authentication status.	CU user
info	Gets HSM instance details: IP address, hostname, port, and the current user.	All users. No login required.
listAttributes	Lists key attributes and their corresponding constant values.	All users. No login required.
listUsers	Lists users on each HSM instance, including their user type, ID, and other attributes.	All users. No login required.
loginHSM and logoutHSM	Logs in to or logs out from an HSM instance.	All users
server	Enters and exits the server mode for an HSM instance.	All users
setAttribute	Changes a key's label and modifies its attributes for encryption, decryption, wrapping, and unwrapping.	CU user
quit	Exits hsm_mgmt_tool.	All users. No login required.
shareKey	Shares a key with other users.	CU user
storeCert	Stores the HSM owner certificate and the owner-signed certificate.	PRECO user or CO user