All Products
Search

This Product

    Key Management Service:Create and activate a NIST FIPS-validated HSM cluster

    Document Center

    Key Management Service:Create and activate a NIST FIPS-validated HSM cluster

    Last Updated:Mar 19, 2025

    Cloud Hardware Security Module provides the hardware security module (HSM) cluster feature. You can use the feature to associate and manage HSMs that reside in different zones in the same region and are used by the same service in a centralized manner. The feature provides high availability, load balancing, and scale-out capabilities on cryptographic operations for applications. This topic describes how to use an HSM cluster.

    Note

    If you want to create an HSM cluster for Key Management Service (KMS) instances of the hardware key management type, see this guide.

    Scenarios

    • Applications can access the same key by using whichever HSM within an cluster.

    • Applications operate in the production environment and depend on Cloud Hardware Security Module to deliver continuous services.

    Usage notes

    • An HSM cluster includes one master HSM and multiple non-master HSMs. In a cluster, HSMs that reside in the same zone use the same VPC subnet.

    • HSMs outside the Chinese mainland cannot be manually reset. If you want to reset HSMs outside the Chinese mainland, contact us.

    Prerequisites

    • An HSM is purchased and enabled. For more information, see Purchase and enable an HSM.

      Warning

      • To ensure the data security of HSMs, we recommend that you do not use test keys in production environments.

      • You need to enable the master HSM. You do not need to enable non-master HSMs.

    • An ECS instance that runs a CentOS 8 or an Alibaba Cloud Linux operating system is purchased. The ECS instance and the HSM reside in the same VPC. For more information, see Get started with Linux instances.

      Note

      The ECS instance is used to install the HSM management tool, not to serve as a business server.

    Create and activate the HSM cluster

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

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

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

      Parameter

      Description

      Cluster Name

      The name of the cluster. The name must be unique and cannot exceed 24 characters in length.

      Configure Whitelist

      The range of the IP addresses that are allowed to access the cluster. If you do not configure a whitelist, all IP addresses are allowed to access the cluster. If you configure a whitelist, only the IP addresses in the whitelist 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.

      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.

      Specify vSwitches

      The vSwitches that you need to select based on your business requirements.

      In an HSM cluster, you must configure at least two vSwitches to create and activate the cluster.

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

      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 Elastic Compute Service (ECS) instance. In this example, the CSR file is named cluster.csr.

        2. Create a private key and configure a password for the private key as prompted. In this example, the private key and the 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 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.

        Important

        You can initialize the master HSM only by using the HSM management tool. You can install the HSM management tool only in Linux operating systems.

        Step

        Description

        Step 1: Download the HSM management tool.

        Based on the region where the HSM is located, the tool version is different.

        • Indonesia (Jakarta) region

          • CentOS

            • Method 1: Download the HSM instance management tool (hsm-client-v2.09.07.02-1.202411041707.x86_64.rpm).

            • Method 2: On the Activated Cluster page, click Download HSM Management Tool.

          • Debian: Download the HSM instance management tool (hsm-client-v2.09.07.02-1.202411041707.x86_64.deb).

        • All regions outside Indonesia (Jakarta)

          • CentOS

            • Method 1: Download the HSM management tool (hsm-client-v2.03.15.10-1.x86_64.rpm).

            • Method 2: Run the following command to download the HSM management tool. This operation requires the ECS instance to be connected to 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'

            • Method 3: On the Activate Cluster page, click Download HSM Management Tool.

          • Debian: Download the HSM management tool (hsm-client-2.03.15.10-20240710_1.x86_64.deb).

        Step 2: Install the HSM management tool.

        Run the following command to install the program and client configuration file in the /opt/hsm directory:

        • CentOS

          Replace <TOOL_NAME> in the example with the actual tool name, such as hsm-client-v2.09.07.02-1.202411041707.x86_64.rpm.

          sudo yum install -y <TOOL_NAME>

        • Debian

          Replace <TOOL_NAME> in the example with the actual tool name, such as hsm-client-2.03.15.10-20240710_1.x86_64.deb.

          sudo dpkg -i <TOOL_NAME>

        Step 3: Modify the client configuration file.

        Modify the configuration items in servers in the /opt/hsm/etc/hsm_mgmt_tool.cfg file.

        • Replace name and hostname with the private IP address of the master HSM on the Instances page.

        • Replace owner_cert_path with 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.

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

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

        2. Run the listUsers command to query 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).

        1. Run the loginHSM command to log on to the master HSM as a PRECO. 

          server0>loginHSM PRECO admin password
loginHSM success

        2. Run the changePswd command to change the password of the PRECO. After you change the password, the PRECO changes 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

        3. 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. Otherwise, the CU information cannot be synchronized to the non-master HSMs.

        1. Run the createUser command to create a CU.

          The username and password of a CU can contain ASCII characters. The username can be up to 20 characters in length. The password can be 8 to 32 characters in length.

          In this example, the username is crypto_user. You can specify the username based on your business requirements.

          Important

          If you configure an HSM cluster for an instance of the hardware key management type, you can specify kmsuser as the username. 

          createUser CU crypto_user <enter password>

        2. 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 7: Check the status of the master HSM.

        In the Activate Cluster step, click the update icon to refresh the status of the master HSM. Then, click Next.

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

        You can purchase more HSMs and add them to the cluster based on your business requirements.

    Use the HSM cluster

    To use an HSM cluster, you can use OpenSSL Dynamic Engine, the JCE provider, or the PKCS#11 library. For more information, see OpenSSL Dynamic Engine, JCE provider, or Install the PKCS #11 library.

    Manage an HSM cluster

    Scale out an HSM cluster

    You can add HSMs in different zones to the same cluster and centrally manage the HSMs. This helps ensure that the HSM has high availability. HSMs can be added to a cluster only when the following requirements are met:

    • The HSMs are not initialized.

    • The HSMs are in the Enabled or New state.

    • The HSMs are of the same type as the master HSM of the cluster.

    • No vSwitches are configured for the HSMs, or they use the same vSwitch as the master one.

    Important

    If a whitelist is configured for an HSM, the whitelist of the cluster prevails after the HSM is added to the cluster. The whitelist of the HSM is cleared.

    1. On the VSMs page, find the required master HSM and click Expand Cluster in the Actions column.

    2. Add HSMs to the cluster based on your business requirements.

      • If no HSMs are available, click Purchase an HSM instance in the Add HSM dialog box to purchase some.

        The purchased HSMs are automatically added to the cluster. HSM automatically assigns IP addresses to the HSMs and synchronizes data in the cluster.

      • If HSMs are available: Select the ones you want to add in the Add HSM dialog box, click 添加 icon, and then click OK.

    Modify the cluster name and access whitelist

    1. On the VSMs page, click the instance ID of either the master or non-master HSM.

    2. On the Details tab, you can edit the cluster name and access whitelist.

      Both IP addresses and CIDR blocks are supported. Enter one IP address or CIDR block per row, up to a maximum of 10 rows.

    Remove from the cluster

    To remove HSMs from a cluster, start with the non-master HSMs, followed by the master HSM. When only the master HSM remains, it can be removed directly, which also deletes the cluster.

    1. Disable the HSM before removal from the cluster.

      1. On the VSMs page, locate the desired HSM instance, click the Actions column, and then select Disable.

      2. In the pop-up dialog box, click Disable again.

    2. On the VSMs page, locate the desired HSM instance and click the Actions column. Then, select Remove from Cluster.

    3. In the pop-up dialog box, click Remove from Cluster once more.

    Promote a non-master HSM to the master HSM

    Manually switch a non-master HSM to the master one in the cluster. This operation is only available when the cluster synchronization method is set to manual.

    1. On the VSMs page, locate the desired non-master HSM instance and click the Actions column. Then, click Switch to Master.

    2. In the pop-up dialog box, click Switch.