All Products
Search
Document Center

Key Management Service:Use an NIST FIPS-validated GVSM cluster 

Last Updated:May 15, 2025

This topic describes how to use Cloud Hardware Security Module.

Precautions

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.

  • 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.

Step 1: Enable an HSM as the master HSM

An HSM cluster includes one master HSM and multiple non-master HSMs. Before you create an HSM cluster, you must enable an HSM as the master HSM.

  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 the created HSM and click Enable in the Actions column.

  3. In the Configure HSM Instance dialog box, configure parameters and click OK.

    Parameter

    Description

    VPC ID

    The VPC that you want to bind to the HSM.

    VPC Subnet

    The subnet that you want to assign to the HSM in the VPC.

    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.

    Configure HSM Whitelist

    The range of the IP addresses that are allowed to access the HSM. If you do not configure the whitelist, all IP addresses are allowed to access the HSM. If you configure a whitelist, only the IP addresses in the whitelist are allowed to access the HSM.

    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
    • If you create a cluster, add an HSM to the cluster, and configure a whitelist for the cluster, the whitelist of the cluster takes precedence over the whitelist of the HSM. 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.

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

Step 2: Create and activate an HSM cluster

In a cluster, HSMs that reside in the same zone use the same Virtual Private Cloud (VPC) subnet.

  1. On the VSMs page, find 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

    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.

  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 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.

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

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

Step 3: Start the hsm_proxy HSM client

  1. Modify the configuration file of the HSM client.

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

    Note

    issuerCA.crt is the self-signed certificate that is created when you activate the cluster. For more information, see Step 2: Create and activate a cluster.

    {
    
        "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
        }
    }
  2. Start the HSM client (hsm_proxy) and set the log file path.

    In this example, logs are saved in the liquidSecurity.1.WKCrty.log file.

    /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
  3. Check whether the HSM client is connected.

    Use the tail command to obtain the log file of hsm_proxy and check whether hsm_proxy is connected. For example, execute the tail liquidSecurity.1.WKCrty.log command. If e2e_handle_client_request:HSM FIPS STATE 2 appears in the result, 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 4: Create a key

Note

If you are configuring a cryptographic machine cluster for a hardware key management instance of KMS, skip this step. For more information, see Configure a cryptographic machine cluster for a hardware key management instance of KMS.

  1. Start the key_mgmt_tool command line utility.

    /opt/hsm/bin/key_mgmt_tool
  2. Execute the loginHSM command to log on to the HSM as a CU user.

    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
  3. Execute 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
  4. Execute 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
                            
  5. Execute the exit command to exit the key_mgmt_tool command line utility.

    Command:  exit

Step 5: Encrypt and decrypt data by using the HSM cluster

Note

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

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, or PKCS #11 library.

References

For more information about how to add HSMs to or remove HSMs from a cluster, modify the name of a cluster, and modify the access whitelist, see Create and activate a NIST FIPS-validated HSM cluster.