How to use an HSM-Key Management Service(KMS)-阿里云帮助中心

Notes

To protect your HSM instance data, do not use test keys in production environments.
If you want to create an HSM cluster for a KMS instance of the hardware key management type, see Configure CloudHSM cluster for KMS hardware instance.

Scope

You have purchased a cryptographic machine. For more information, see Purchase a Cryptographic Machine.
You need an ECS instance that runs CentOS 8 or Alibaba Cloud Linux and is in the same VPC as the HSM instance. For more information, see Linux Instance Quick Start.

Note
You use this ECS instance to install the HSM management tool, not as a business server.

Step 1: Create and activate a cluster

Important

If you configured cluster information when you purchased the GVSM (NIST FIPS) (setting Auto-generate certificate to Yes), the HSM automatically creates a cluster based on the configured cluster information. In this case, skip this step.

Step 1: Enable the master HSM instance

Go to the VSMs page of the CloudHSM console. In the top navigation bar, select the destination region.
On the VSMs page, find the HSM instance that you created. In the Actions column, click Enable.

In the Configure HSM Instance dialog box, configure the HSM instance and click OK. After configuration succeeds, the Status of the HSM instance changes to Enabled.

Parameter	Description
VPC ID	Select the VPC to which the HSM instance is attached. Important This VPC must be the same as the one attached to your ECS instance.
VPC Subnet	Select the subnet CIDR block of the VPC where the HSM instance resides.
Private IP Address	Assign a private IP address to the HSM instance. Important The private IP address must belong to the subnet CIDR block of the VPC. Otherwise, configuration fails. IP addresses ending in 253, 254, or 255 are system reserved IP addresses. Do not use them.
Configure HSM Whitelist	Configure the whitelist for accessing the HSM instance. You can enter one IP address or CIDR block per line. You can enter up to 10 entries. If no whitelist is configured, all IP addresses can access the HSM instance. If a whitelist is configured, only requests from IP addresses in the whitelist are allowed. Requests from other IP addresses are denied. Important If you create an HSM cluster and configure a whitelist for the cluster, the cluster whitelist takes precedence over the whitelists of individual HSM instances in the cluster. For example, if the whitelist of an HSM instance in the cluster is 10.10.10.10 and the cluster whitelist is 172.16.0.1, you can access the HSM instance only from 172.16.0.1. You cannot configure 0.0.0.0/0 (to allow all source IP addresses). For security reasons, we do not recommend allowing all source IP addresses. To allow all source IP addresses for temporary testing, leave the whitelist empty.

Step 2: Create a cluster

On the VSMs page, find the master HSM instance and click Create Cluster in the Actions column.

In the Create and Activate Cluster panel, complete the configurations on the Create cluster tab and click Next.

Parameter	Description
Cluster Name	Enter a custom name for the cluster. The name must be unique and cannot exceed 24 characters.
Configure Whitelist	Specify the IP addresses that can access the cluster. If no whitelist is configured, all IP addresses can access the cluster. If a whitelist is configured, requests from IP addresses outside the whitelist are denied. You can enter one IP address or CIDR block per line. You can enter up to 10 entries. Important The cluster whitelist takes precedence over the whitelists of individual HSM instances in the cluster. For example, if the whitelist of an HSM instance in the cluster is 10.10.10.10 and the cluster whitelist is 172.16.0.1, you can access the HSM instance only from 172.16.0.1. You cannot configure 0.0.0.0/0 (to allow all source IP addresses). For security reasons, we do not recommend allowing all source IP addresses. To allow all source IP addresses for temporary testing, leave the whitelist empty.
Specify vSwitches	Select vSwitches in the required zones based on your business needs. You must configure at least two vSwitches to successfully create and activate an HSM cluster.

Step 3: Import the cluster certificate

In the Upload Cluster Certificate section, click Cluster CSR Certificate to download the CSR certificate file and upload it to the ECS instance. For example, save the file as cluster.csr.
Create a private key and set a password for the private key as prompted. For example, save the private key as issuerCA.key.
```
openssl genrsa -aes256 -out issuerCA.key 2048
```
Create a self-signed certificate. For example, save the certificate as issuerCA.crt.
```
openssl req -new -x509 -days 3652 -key issuerCA.key -out issuerCA.crt
```
Sign the cluster CSR certificate. The issued cluster certificate is stored in the cluster.crt file.
Note
This step uses the cluster.csr, issuerCA.key, and issuerCA.crt files.
```
openssl x509 -req -in cluster.csr -days 3652 -CA issuerCA.crt -CAkey issuerCA.key -set_serial 01 -out cluster.crt
```
Return to the CloudHSM console, import the cluster certificate, and click Submit.
- In the Enter the issuer certificate in the PEM format section, enter the content of the issuerCA.crt file.
- In the Enter the issued cluster certificate in the PEM format section, enter the content of the cluster.crt file.

Step 4: Initialize the master HSM instance

Important

The master HSM instance can be initialized only by using the HSM management tool, and the HSM management tool can be installed only on Linux operating systems.

Download the HSM management tool.
- CentOS
  - Method 1: Go to hsm-client-v2.03.15.10-1.x86_64.rpm to download the HSM management tool.
  - Method 2: Run the following command to download the HSM management tool. This operation requires your ECS server to be connected to the public network.
```
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 target HSM instance and click the icon in the Specifications column.
  - Method 4: On the Activate Cluster page, click Download HSM management tool.
- Debian
  Go to hsm-client-2.03.15.10-20240710_1.x86_64.deb to download the HSM management tool.
Install the HSM management tool: Run the following commands to install the program and configuration files in the /opt/hsm directory.
- CentOS
  Replace hsm-client-v2.xx.x86_64.rpm in the example with the actual name of the tool.
```
sudo yum install -y hsm-client-v2.xx.x86_64.rpm
```
- Debian
  Replace hsm-client-2.xx.x86_64.deb in the example with the actual name of the tool.
```
sudo dpkg -i hsm-client-2.xx.x86_64.deb
```

Modify configuration items: In the installation directory of the HSM management tool, modify the servers configuration item in the /opt/hsm/etc/hsm_mgmt_tool.cfg file. The following sample hsm_mgmt_tool.cfg file is provided for reference:

Change name and hostname to the private IP address of the master HSM. You can query the IP address on the VSMs page.
Change owner_cert_path to the file path of issuerCA.crt.

{
 "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"
 }
}

Log on to the master HSM and view the user list

Run the following command to log on to the master HSM.

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

Run the listUsers command to display the user list.

cloudmgmt>listUsers
Users on server 0(172.16.XX.XX):
Number of users found:2

    User Id            User Type          User Name                     MofnPubKey       LoginFailureCnt            2FA
         1             PRECO          admin                                       NO               0                     NO
         2             AU             app_user                                    NO               0                     NO

Change the PRECO user to a CO user

Run the loginHSM command to log on to the HSM as the PRECO user.
```
server0>loginHSM PRECO admin password
loginHSM success
```

Run the changePswd command to change the password of the PRECO user. After you change the password, the PRECO user becomes a CO user.

cloudmgmt>changePswd PRECO admin <NewPassword>

*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************

Do you want to continue(y/n)?y
Changing password for admin(PRECO) on 1 nodes

Run the listUsers command to view the user list and check whether the PRECO user is changed to a CO user.

cloudmgmt>listUsers
Users on server 0(172.16.XX.XX):
Number of users found:2

    User Id            User Type          User Name                     MofnPubKey       LoginFailureCnt            2FA
         1             CO             admin                                       NO               0                     NO
         2             AU             app_user                                    NO               0                     NO

Create a crypto user (CU)
Warning
Create the CU user before you add non-master HSMs to the cluster. Otherwise, the CU user is not automatically synchronized to the non-master HSMs.
1. Run the loginHSM command to log on to the HSM as the CO user by using the new password that you set in the previous step.
```
server0>loginHSM CO admin password
loginHSM success
```
2. Run the createUser command to create a CU.
  The CU username and password support ASCII characters. The CU username can contain up to 20 characters, and the password must contain 8 to 32 characters.
  In this topic, crypto_user is used as an example CU username. You can specify a username based on your business requirements.
  Important
  If you are configuring an HSM cluster for a KMS instance of the hardware key management type, use kmsuser as the CU username.
```
createUser CU crypto_user <enter password>
```
3. Run the listUsers command to check whether the CU is created.
  Expected output:
```
cloudmgmt>listUsers
Users on server 0(172.16.XX.XX):
Number of users found:3

    User Id         User Type       User Name                  MofnPubKey    LoginFailureCnt         2FA
         1          CO          admin                                    NO               0               NO
         2          AU          app_user                                 NO               0               NO
         3          CU          crypto_user                              NO               0               NO
```

Step 5: Verify and add HSMs

Verify the status of the master HSM: Return to the CloudHSM console. On the Activate Cluster page, click the icon to refresh the HSM status and click Next.
Add HSM: Add non-master HSMs to the cluster as prompted and click Complete.
Note
If you require more HSM instances, you must purchase HSM instances and add them to the cluster.

Step 2: Start HSM client (hsm_proxy)

Modify the HSM client configuration file.

In the HSM management tool installation directory, locate the `/opt/hsm/etc/hsm_proxy.cfg` file. Set `server.hostname` to the IP address of the VPC where the current instance resides, and set `client.e2e_owner_crt_path` to the path of the `issuerCA.crt` file.

Note

The `issuerCA.crt` file is the self-signed certificate you created during cluster activation. For more information, see Use GVSM (NIST FIPS) HSM clusters.

{

    "ssl": {
        "certificate": "/opt/hsm/etc/client.crt",
        "pkey": "/opt/hsm/etc/client.key",
        "CApath": "/opt/hsm/etc/certs",
        "server_ssl": "yes",
        "server_ch_ssl_ciphers": "default"
    },

    "client": {
        "socket_type" : "UNIXSOCKET",
        "tcp_port" : 1111,
        "zoneid" : 0,
        "workers" : 1,
        "daemon_id" : 1,
        "reconnect_attempts": -1,
        "reconnect_interval": 1,
        "log_level": "INFO",
        "sslreneg": 0,
        "CriticalAlertScript": "",
        "e2e_owner_crt_path" : "<issuerCA.crt file path>",
        "create_object_minimum_nodes" : 1,
        "logfiles_location" : ""
    },

    "loadbalance" : {
        "enable" : "yes",
        "prefer_same_zone": "no",
        "success_rate_weight" : 1,
        "relative_idleness_weight" : 1
    },

    "dualfactor": {
        "enable" : "no",
        "port" : 2225,
        "certificate" : "certificate.crt",
        "pkey" : "pkey.pem",
        "dualfactor_ssl": "yes",
        "dualfactor_ch_ssl_ciphers": "default"
    },

    "server": {
        "hostname": "<instance ip>",
        "port": 2224
    }
}

Start the HSM client (hsm_proxy) and specify the log file path.

This example saves logs to `liquidSecurity.1.WKCrty.log`.

/opt/hsm/bin/hsm_proxy /opt/hsm/etc/hsm_proxy.cfg

logfiles_location is not specified, logs will be available in current directory

Logs will be available in liquidSecurity.1.WKCrty.log file

Verify the hsm_proxy connection.

Run the tail command to retrieve the hsm_proxy log file and check whether hsm_proxy is connected. For example, if you run the tail liquidSecurity.1.WKCrty.log command and the output contains `e2e_handle_client_request:HSM FIPS STATE 2`, the connection is successful.

tail liquidSecurity.1.WKCrty.log
2023-10-28T13:33:05Z liquidSecurity INF: check_preferred_srv_status_noclock: New preferred server node id:0
2023-10-28T13:33:05Z liquidSecurity INF: do_e2e_encryption_handshake: Trying to login to server as new server connection is established
2023-10-28T13:33:05Z liquidSecurity INF: e2e_handle_client_request:  Got Authorize session response
2023-10-28T13:33:05Z liquidSecurity INF: get_partition_info: Get pHSM Info using e2e mgmtch
2023-10-28T13:33:05Z liquidSecurity INF: e2e_handle_client_request: Authorize session SUCCESS
2023-10-28T13:33:05Z liquidSecurity INF: e2e_handle_client_request: Got Partition Info
2023-10-28T13:33:05Z liquidSecurity INF: e2e_handle_client_request: GetPartitionInfo success 0 : HSM Return: SUCCESS
2023-10-28T13:33:05Z liquidSecurity INF: e2e_handle_client_request: HSM FIPS STATE 2
2023-10-28T13:33:06Z liquidSecurity INF: libevmulti_init: Initializing events
2023-10-28T13:33:06Z liquidSecurity INF: libevmulti_init: Ready !

Step 3: Create a key

Note

If you configure an HSM cluster for a KMS hardware key management instance, skip this step. For more information, see Configure CloudHSM cluster for KMS hardware instance.

Start the key_mgmt_tool command line utility.
```
/opt/hsm/bin/key_mgmt_tool
```

Run the loginHSM command to log on to the HSM as a CU.

Command:  loginHSM -u CU -s crypto_user -p <enter password>

        Cfm3LoginHSM returned: 0x00 : HSM Return: SUCCESS

        Cluster Status:
        Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Run the genSymKey command to generate a symmetric key.

Command:  genSymKey -l testkey -t 31 -s 32

        Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 6

        Cluster Status:
        Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Run the findKey command to query the key you created.

Command:  findKey

        Total number of keys present: 1

        Number of matching keys from start index 0::0

        Handles of matching keys:
        6

        Cluster Status:
        Node id 0 status: 0x00000000 : HSM Return: SUCCESS

        Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Run the exit command to quit the key_mgmt_tool command line utility.
```
Command:  exit
```

Step 4: Encrypt and decrypt using an HSM cluster

You can use an HSM cluster by calling the interfaces provided by the OpenSSL engine, the Java Cryptography Extension (JCE), or the PKCS #11 library. For more information, see OpenSSL Dynamic Engine, JCE, or PKCS #11 Library.