Key Management Service:Configure an HSM cluster for a KMS hardware instance

Step 1: Purchase an HSM cluster

An HSM cluster groups HSM instances across different zones in the same region and provides high availability, load balancing, and horizontal scaling for cryptographic operations.

1. Log on to the Cloud Hardware Security Module console. In the top navigation bar, select a region.

2. On the VSMs tab, click Create HSM.

3. On the CloudHSM purchase page, configure the parameters in the following table, click Buy Now, and complete the payment.

   Parameter	Description
   Region	Select a region for the HSM instance. Important The HSM instance, your VPC, and your KMS hardware key management instance must be in the same region.
   Crypto service type	Select General-purpose Server HSM GVSM.
   Deployment mode	Select Dual-zone Deployment.
   Cluster name	Enter a name of 1 to 24 characters. The name must start with a letter, a digit, or a Chinese character, and can contain digits, underscores (_), and hyphens (-).
   VPC	Select the VPC to which the HSM belongs.
   Whitelist	Select Yes. HSM adds the VPC network segment to the cluster whitelist so that all IP addresses in the VPC can access the HSM cluster.
   vSwitch	Select two to four vSwitches in different zones.
   generate_cert	Select Yes. HSM automatically generates the certificate for encrypted communication and completes the certificate configuration. KMS retrieves the certificate and completes client configuration automatically — you do not need to manage this process. The certificate is valid for 10 years and is automatically rotated before expiry. Important Do not register a UKEY administrator for the HSM. If you register a UKEY administrator, automatic certificate rotation will fail.
   Data backup and restore	Enable this feature to back up and restore HSM instance data. Each backup stores data from one HSM. If an HSM is released, its backup images are retained for 90 days before being automatically deleted. Cross-region image replication is also available for disaster recovery. For more information, see Data backup and recovery.
   Image quota	The maximum number of backup images. Each image stores one HSM backup. When the quota is reached, the oldest image is overwritten automatically.
   Quantity	The default value is 2. Keep this value.
   Subscription period	Select a subscription duration. To prevent permanent key loss caused by service expiry, select Auto-renewal. When auto-renewal is enabled, Alibaba Cloud charges your payment account 9 calendar days before the service expires. Make sure your payment account has a sufficient balance.

4. Read the Terms of Service, click Buy Now, and then click Subscribe to complete the purchase.

After the purchase, the HSM instance appears on the VSMs page. The cluster is created in approximately 5 minutes.

Step 2: Synchronize cluster data

Check the synchronization mode of the cluster to determine whether manual synchronization is needed.

Automatic synchronization cluster

Data is synchronized across all HSMs in the cluster automatically. No action is needed.

Manual synchronization cluster

After you create and activate the cluster for the first time, manually synchronize data from the master HSM to the subordinate HSMs. When you scale out the cluster later, data is synchronized automatically to newly added HSM instances.

1. In the Actions column, click Synchronize Cluster. The cluster status changes to Synchronizing during the process.

   

2. After synchronization completes, check that the HSM digests are identical. View the digests on the HSM product page. If the digests for both HSMs match, the cluster is configured correctly. If they differ, repeat the synchronization. If the digests still differ after retrying, contact us.

   

Step 1: Purchase two HSM instances

1. Log on to the Cloud Hardware Security Module console. In the top navigation bar, select a region.

2. On the VSMs tab, click Create HSM.

3. On the CloudHSM purchase page, configure the parameters in the following table and click Buy Now.

   Parameter	Description
   Region	Select a region for the HSM instance. Important The HSM instance, your VPC, and your KMS hardware key management instance must be in the same region.
   Crypto service type	Select GVSM.
   Deployment mode	Select Dual-zone deployment. The specific zones are assigned by HSM.
   Data backup and restore	Each backup stores data from one HSM. After enabling this feature, select the number of images. For more information, see Data backup and recovery.
   Quantity	The default value is 2. Keep this value.
   Subscription period	Select the same subscription duration as your KMS hardware key management instance. Note Select Auto-renewal to prevent permanent key loss if the service expires without renewal. When auto-renewal is enabled, Alibaba Cloud deducts fees from your payment account nine calendar days before the service expires.

4. Read the Terms of Service, click Buy Now, and then click Pay to complete the purchase.

Step 2: Enable the HSM instance

Enable only the master HSM. The subordinate HSM does not need to be enabled separately.

1. Go to the VSMs page of the Cloud Hardware Security Module console. In the top navigation bar, select a region.

2. Enable the master HSM. In the HSM Instance Configuration dialog box, configure the parameters in the following table and click OK. The Status of the HSM instance changes to Enabled.

   Parameter	Description
   VPC ID	Select the VPC to which you want to attach the HSM instance. The VPC must match the VPC of the KMS hardware key management instance.
   VPC subnet	Select the VPC subnet (vSwitch) to which the HSM instance belongs.
   Private IP address	Assign a private IP address within the CIDR block of the selected VPC subnet. Important Do not use IP addresses ending in 253, 254, or 255 — these are reserved by the system.
   Configure HSM whitelist	Leave this blank. The cluster whitelist takes precedence over individual HSM whitelists, so you will configure the whitelist when creating the cluster.

Step 3: Create and activate a cluster

An HSM cluster groups HSM instances across different zones in the same region and provides high availability, load balancing, and horizontal scaling for cryptographic operations.

Use the master HSM to create the cluster, then add the subordinate HSM.

1. Go to the VSMs page of the Cloud Hardware Security Module console. In the top navigation bar, select a region.

2. Locate the master HSM instance and click Create Cluster in the Actions column.

3. In the Create and Activate Cluster panel, complete ①Create Cluster and click Next.

   Configuration item	Description
   Cluster name	Enter a unique name of up to 24 characters.
   Configure whitelist	Enter the IP addresses and CIDR blocks allowed to access the cluster. Use one entry per line, up to 10 entries. Include the following: the CIDR blocks of the vSwitches where HSM instances are located (for example, 172.16.1.0/24 and 172.16.2.0/24), the private IP address of the ECS instance, and the CIDR block of the vSwitch to which the KMS instance is attached. Important The cluster whitelist overrides individual HSM whitelists. Do not enter 0.0.0.0/0 — if you need to allow all IP addresses, leave the whitelist blank instead.
   Specify vSwitches	Select the vSwitch to which the subordinate HSM instance is attached.

4. In the Create and Activate Cluster panel, complete ②Activate Cluster. a. Import a cluster certificate Download command (step 1):

   1. In the Upload Cluster Certificate section, click Cluster CSR Certificate to download the certificate signing request (CSR) file. Upload it to the ECS instance and save it as cluster.csr.

   2. Generate a private key with a passphrase: ``bash openssl genrsa -aes256 -out issuerCA.key 2048 ``

   3. Create a self-signed certificate: ``bash openssl req -new -x509 -days 3652 -key issuerCA.key -out issuerCA.crt ``

   4. Sign the cluster CSR using cluster.csr, issuerCA.key, and issuerCA.crt. The signed cluster certificate is saved as cluster.crt: ``bash openssl x509 -req -in cluster.csr -days 3652 -CA issuerCA.crt -CAkey issuerCA.key -set_serial 01 -out cluster.crt ``

   5. Return to the CloudHSM console, import the certificate, and click Submit:

      • In Enter the issuer certificate in the PEM format, paste the content of issuerCA.crt.

      • In Enter the issued cluster certificate in the PEM format, paste the content of cluster.crt.

   b. Initialize the master HSM instance

   Step	Description
   1. Download the HSM management tool	Important The HSM management tool runs on Linux only. Download it using one of the following methods: directly from this link, by running the command below on an ECS instance with internet access, by clicking the instance specification on the VSMs page and then clicking , or by clicking Download HSM Management Tool on the Activate Cluster page.
   2. Install the HSM management tool	Run the following command to install the tool to /opt/hsm:
   3. Modify the client configuration file	In /opt/hsm/etc/hsm_mgmt_tool.cfg, set name and hostname to the private IP address of the master HSM, and set owner_cert_path to the path of issuerCA.crt.
   4. Log on to the master HSM and view the user list	Run the tool and list users to confirm the initial state.
   5. Change the PRECO user to a CO user	Log on as the Pre-Crypto Officer (PRECO) user and change the password. Changing the password converts the PRECO user to a Crypto Officer (CO) user.
   6. Create a Crypto User (CU)	Warning Create the Crypto User (CU) before adding the subordinate HSM. Otherwise, the CU is not synchronized to the subordinate HSM automatically. For security purposes, the KMS hardware key management instance accesses the HSM cluster as a CU user named kmsuser. Remember the initial password; you will need it when enabling the KMS hardware key management instance.
   7. Verify the master HSM status	Return to the CloudHSM console. On the Activate Cluster page, click the refresh icon to update the HSM status, then click Next.

   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'

   Install command (step 2):

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

   Configuration file example (step 3):

   {
   	"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 and list users (step 4):

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

   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

   Convert PRECO to CO (step 5): Log on as the PRECO user:

   server0>loginHSM PRECO admin password
   loginHSM success

   Change the password to convert PRECO to CO:

   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

   Verify the conversion:

   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 kmsuser (step 6):

   createUser CU kmsuser <enter password>

   Verify that the CU user was created:

   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          kmsuser                                  NO               0               NO

   Exit the management tool:

   cloudmgmt>quit
   disconnecting from servers, please wait...

5. On the ③Add HSM page, add the subordinate HSM to the cluster as prompted and click Complete. After adding the subordinate HSM, the cluster automatically synchronizes master key data — including kmsuser — to the subordinate HSM. Check that the digest information for both HSMs in the cluster is identical. If the digests differ, contact us.

   If the HSM instance has a status of Initialized, it cannot be added to the cluster. In this case, contact us.