Key Management Service:Configure an HSM cluster for a KMS instance of the hardware key management type

Background information

You can use a KMS instance of the hardware key management type to encrypt data of client applications or cloud services. This helps prevent files or sensitive data, such as mobile phone numbers, ID numbers, and bank card numbers, from being attacked or leaked during transmission.

If you connect a KMS instance of the hardware key management type to an HSM cluster, you can gain the following benefits:

• Cloud Hardware Security Module provides stable and easy-to-use upper-layer key management capabilities and cryptographic operation capabilities.

• HSM clusters can work together with other Alibaba Cloud services to provide high security and controllability for data encryption of cloud services. For more information, see Alibaba Cloud services that can be integrated with KMS.

Supported regions and zones of HSMs

Scenarios

You created a virtual private cloud (VPC) in the China (Hong Kong) region and built your own applications. You want to encrypt and decrypt sensitive data or files by using an instance of the hardware key management type. In this case, you can build the network architecture and plan resources as described in the following figure.

Limits

• The VPC, vSwitches, HSMs, KMS instance of the hardware key management type, and ECS instance must reside in the same region.

  Important

  Before you purchase HSMs, make sure that HSMs are available in different zones in the required region on the buy page.

• The zones of the two vSwitches must be the same as the zones of the HSMs. For example, if the zones of the two vSwitches are Zone A and Zone B, the zones of the two HSMs must also be Zone A and Zone B.

  Important

  You cannot purchase vSwitches in Zone A in the China (Hangzhou) region. If you purchase an HSM in Zone A, you can purchase a vSwitch in Zone J or Zone G. An HSM in Zone A can be bound to a vSwitch in Zone J or Zone G.

Prerequisites

• A VPC is created. Two vSwitches in different zones are created in the VPC. For more information, see the Step 1: Create a VPC and vSwitches section of the Create a VPC with an IPv4 CIDR block topic.

• An ECS instance that runs a CentOS 8 or Alibaba Cloud Linux operating system is created. The ECS instance and the master HSM are in the same VPC subnet. For more information, see Create an instance on the Custom Launch tab.

Step 1: Purchase HSMs

Purchase HSM 1 in Zone A and HSM 2 in Zone B.

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

2. On the Instances page, click Create HSM.

3. On the Cloud Hardware Security Module buy page, configure the parameters and click Buy Now.

   Parameter	Description	Example
   Region	The region of the HSM. For more information, see What is Cloud Hardware Security Module?. Important You can use an HSM only in a VPC. The HSM, the VPC, and your KMS instance of the hardware key management type must reside in the same region.	China (Hong Kong)
   Deployment Mode	Select Dual-zone. Important The zones of the two HSMs must be the same as the zones of the two vSwitches in the VPC.	Dual-zone
   Quantity	The number of HSMs that you want to purchase. Select 1.	2
   Duration	The subscription duration. We recommend that you select the same subscription duration as your KMS instance of the hardware key management type. Note To prevent the permanent loss of keys, we recommend that you select Auto-renewal. If you do not renew Cloud Hardware Security Module before the subscription duration elapses, your keys may be permanently lost. If you select Auto-renewal, Alibaba Cloud automatically deducts fees from your Alibaba Cloud account that is used to purchase the HSM nine calendar days before Cloud Hardware Security Module expires.	1 Year

4. Read and select Terms of Service and click Pay. Then, click Subscribe to complete the payment.

Step 2: Enable and configure HSMs

Configure HSM 1 and HSM 2 to ensure that your KMS instance of the hardware key management type and your HSM cluster are in the same VPC.

1. On the Instances page, find the HSM that you created and click Enable in the Actions column.

2. In the Configure HSM Instance dialog box, configure parameters and click OK. The following table describes the parameters.

   Parameter	Description	Example
   VPC Subnet	The VPC to which you want to bind the HSM. Select the VPC to which the KMS instance of the hardware key management type belongs.	vpc-wz95******
   VPC ID	The vSwitch in the zone where the HSM resides.	vsw-wz9h****** (vSwitch 1)
   Private IP Address	The private IP address that you want to assign to the HSM. Important The private IP address must belong to the subnet that is assigned to the HSM. Otherwise, the configuration fails. The system reserves IP addresses whose last octet is 253, 254, or 255. Do not use the reserved IP addresses.	192.168.XX.XX
   Configure HSM Whitelist	The range of the IP addresses that are allowed to access the HSM. You do not need to configure the parameter in this step. You need to configure the whitelist of the HSM cluster in the next subsequent operation. The whitelist of a cluster has a higher priority than the whitelist of each HSM in the cluster. For more information about how to configure a cluster whitelist, see Step 3: Create and activate a cluster.	No configuration required

3. Enable the other HSM and repeat Step2.

   For example, set VPC ID to vsw-wz96****** (vSwitch 2) and Private IP Address to 192.169.XX.XX. For other parameters, retain the values in Step2.

   If the configuration is successful, the Status of the HSM changes to Enabled.

Step 3: Create and activate a cluster

You can use an HSM cluster to associate and manage a group of HSMs that reside in different zones of the same region and are used by the same service. An HSM cluster provides high availability, load balancing, and scale-out capabilities for cryptographic operations.

In this example, HSM 1 is used as the master HSM. After you create a cluster, add HSM 2 as a non-master HSM to the cluster.

1. On the Instances page, find the HSM that you want to use as the master HSM and click Create Cluster in the Actions column.

2. In the Create and Activate Cluster panel, complete the Create Cluster step and click Next.

   Parameter	Description	Example
   Cluster Name	The name of the cluster. The name must be unique and cannot exceed 24 characters in length.	custer1
   Configure Whitelist	The range of the IP addresses that are allowed to access the cluster. IP addresses and CIDR blocks are supported. You can specify one IP address or one CIDR block in each row. You can specify up to 10 rows in total. In this example, make sure that the following IP addresses are added to the range: The CIDR block of the vSwitch that is configured for each HSM in the cluster For example, if the CIDR blocks of the vSwitches that are configured for the HSMs in the cluster are 172.16.1.0/24 and 172.16.2.0/24, enter 172.16.1.0/24 and 172.16.2.0/24 in two rows in the field. The private IP address of the ECS instance For example, if the private IP address of the ECS instance is 172.16.3.0, enter 172.16.3.0 in a separate row in the field. The CIDR block of the vSwitch that is associated with the KMS instance. If you have not purchased a KMS instance, you must purchase and enable a KMS instance first. Important The whitelist of a cluster has a higher priority than the whitelist of an HSM in the cluster. For example, if you add 10.10.10.10 to the whitelist of an HSM and add 172.16.0.1 to the whitelist of the cluster that includes the HSM, you can access the HSM only from 172.16.0.1. The whitelist configuration of 0.0.0.0/0 is not supported. If you enter 0.0.0.0/0, requests from all IP addresses are allowed. For security reasons, we recommend that you do not allow requests from all IP addresses. If you need to allow requests from all IP addresses, do not configure the whitelist.	172.16.1.0/24 172.16.2.0/24 172.16.3.0
   Specify a vSwitch for the zone of another purchased HSM	The vSwitch that is bound to HSM 2.	vsw-wz96******

3. In the Create and Activate Cluster panel, complete the Activate Cluster step.

   1. Import a cluster certificate.

      1. In the Upload Cluster Certificate section, click Cluster CSR Certificate to download a certificate signing request (CSR) file. Then, upload the CSR file to the ECS instance. In this example, the CSR file is saved in the cluster.csr file.

      2. Create a private key and configure a password for the private key as prompted. In this example, the private key and password are saved in the issuerCA.key file.

         openssl genrsa -aes256 -out issuerCA.key 2048

      3. Create a self-signed certificate. In this example, the self-signed certificate is saved in the issuerCA.crt file.

         openssl req -new -x509 -days 3652 -key issuerCA.key -out issuerCA.crt

      4. Sign the CSR file and save the issued certificate in the cluster.crt file.

         Note

         In this step, the cluster.csr, issuerCA.key, and issuerCA.crt files are used.

         openssl x509 -req -in cluster.csr -days 3652 -CA issuerCA.crt -CAkey issuerCA.key -set_serial 01 -out cluster.crt

      5. Go to the Activate Cluster step in the Cloud Hardware Security Module console, import the cluster certificate, and then 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.

   2. Initialize the master HSM.

      Step	Description
      Step 1: Download the HSM management tool.	Important You can install the HSM management tool only in Linux operating systems. Download the HSM management tool by using one of the following methods: Click here to download the tool. Run the following command to download the tool. You can use this method only when your ECS instance is connected over the Internet. 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' On the Instances page, find the master HSM, click the information in the Specifications column, and then click Download HSM Management Tool. In the Activate Cluster step in the Create and Activate Cluster panel, click Download HSM Management Tool.
      Step 2: Install the HSM management tool.	Run the following command to install the program and client configuration file in the /opt/hsm directory: sudo yum install -y hsm-client-v2.03.15.10-1.x86_64.rpm
      Step 3: Modify the client configuration file.	Modify the configuration items of servers in the /opt/hsm/etc/hsm_mgmt_tool.cfg file. name and hostname: Change the values to the private IP address of the master HSM. owner_cert_path: Change the value to the path to the issuerCA.crt file. Example of the 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", } }
      Step 4: Log on to the master HSM and query a list of users.	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 users. 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
      Step 5: Change a precrypto officer (PRECO) to a crypto officer (CO).	Run the loginHSM command to log on to the HSM as a precrypto officer (PRECO). server0>loginHSM PRECO admin password loginHSM success Run the changePswd command to change the password of the PRECO. After you change the password, the PRECO is changed to a 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 Run the listUsers command to query users and check whether the PRECO changes to a CO. 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
      Step 6: Create a crypto user (CU).	Warning Before you add non-master HSMs to a cluster, you must create a CU. If you create a CU after you add non-master HSMs to a cluster, the CU information cannot be automatically synchronized to the non-master HSMs. To ensure data security, a KMS instance of the hardware key management type accesses an HSM cluster as a CU named kmsuser. Use the HSM management tool to log on to the master HSM and run the createUser command to create a CU named kmsuser. createUser CU kmsuser <enter password> Important Save the initial password of kmsuser. The password is required when you enable the KMS instance of the hardware key management type. Run the listUsers command to check whether the CU is 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 Run the quit command to exit the management tool. cloudmgmt>quit disconnecting from servers, please wait...
      Step 7: Check the status of the master HSM.	Return to the Cloud Hardware Security Module console. In the Activate Cluster step in the Activate Cluster panel, click the icon to refresh the status of the master HSM, and click Next.

4. In the Add HSM step, add the non-master HSM to the cluster as prompted and click Complete.

   Note

   If the non-master HSM that you want to add to the cluster is in the Initialized state, the non-master HSM cannot be added to the cluster. In this case, submit a ticket to contact technical support.

   After you complete the configuration, you can view the status of the two HSMs in the Cluster column. The status of the two HSMs is Master HSM and Non-Master HSM. The cluster automatically synchronizes the data of the master HSM, such as the information about kmsuser, to the non-master HSM. You need only to check whether the digest information about the two HSMs in the cluster is consistent. If the digest information is inconsistent, manually synchronize the information. If the digest information is still inconsistent, submit a ticket to contact technical support.

What to do next

Go to the KMS console, purchase a KMS instance of the hardware key management type, and complete the relevant configurations. For more information, see Purchase and enable a KMS instance and Getting started with keys.

References

Overview of key management