All Products
Search
Document Center

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

Last Updated:Jun 04, 2024

When you use a Key Management Service (KMS) instance of the hardware key management type, you must connect the instance to a hardware security module (HSM) cluster that is provided by Cloud Hardware Security Module. The HSM cluster performs data synchronization and load balancing to ensure high availability. This topic describes how to 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

Region

Region ID

zone

China (Hong Kong)

cn-hongkong

Zone B and Zone C

Singapore

ap-southeast-1

Zone A and Zone B

SAU (Riyadh)

me-central-1

Zone A and Zone B

Malaysia (Kuala Lumpur)

ap-southeast-3

Zone A and Zone B

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.

KMS&加密服务最佳实践架构图

Resource type

Quantity

Description

Example

vSwitch

2

Two vSwitches reside in two zones, and the two zones are the same as the two zones of the HSMs.

  • vSwitch 1 (Zone A)

  • vSwitch 2 (Zone B)

HSM

2 or more. In this example, two HSMs are used.

Two HSMs reside in two zones, and the two zones are the same as the two zones of the vSwitches.

  • HSM 1 (Zone A)

  • HSM 2 (Zone B)

Instance of the hardware key management type

1

The instance resides in the same VPC as your applications.

KMS Instance 1

Elastic Compute Service (ECS) instance

1

The ECS instance runs a CentOS 8 or Alibaba Cloud Linux operating system. The ECS instance and the master HSM are in the same VPC subnet. In this example, HSM 1 is used as the master HSM.

Important

You can install the HSM management tool on an ECS instance or on-premises computer. Then, you can log on to a master HSM by using the HSM management tool to configure the master HSM. In this example, an ECS instance is used. If you use an on-premises computer, you can connect the on-premises computer to the VPC of the master HSM by using a VPN or an Express Connect circuit. For more information, see Connect a client to a VPC or Connect a data center to a VPC by using an Express Connect circuit.

ECS Instance 1

Note

In this example, the names provided are only for reference. In the actual configuration process, refer to the KMS console.

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.

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

      1. Run the loginHSM command to log on to the HSM as a precrypto officer (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 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
      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. 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.

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

      2. 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
      3. 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 update 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.

Note

When you configure a KMS instance of the hardware management type, the following information is involved. Keep the information properly.

  • Name of the HSM cluster

  • Initial password of kmsuser

References

Overview of key management