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

Prerequisites

Before you begin, make sure you have:

• A purchased and enabled HSM. See Purchase and enable an HSM.

• An ECS instance running CentOS 8 or Alibaba Cloud Linux, in the same Virtual Private Cloud (VPC) as the HSM. The ECS instance is used to install the HSM management tool — not as a business server. See Get started with Linux instances.

Step 1: Enable an HSM as the master HSM

An HSM cluster consists of one master HSM and multiple non-master HSMs. Before creating a cluster, designate one HSM as the master.

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

3. In the Configure HSM instance dialog box, set the following parameters and click OK. When the configuration succeeds, the HSM Status changes to Enabled.

   Parameter	Description
   VPC ID	The VPC to bind to the HSM.
   VPC subnet	The subnet to assign to the HSM in the VPC.
   Private IP address	The private IP address to assign to the HSM. Must belong to the assigned subnet. The system reserves IP addresses whose last octet is 253, 254, or 255 — do not use these.
   Configure HSM whitelist	The IP addresses or CIDR blocks allowed to access the HSM. Supports up to 10 entries (one per row). If left blank, all IP addresses can access the HSM. If a cluster whitelist is configured, it takes precedence over the HSM whitelist. The 0.0.0.0/0 entry is not supported — to allow all IP addresses, leave the whitelist blank.

Step 2: Create and activate an HSM cluster

This step establishes your ownership and control over the cluster through a certificate-based trust chain. The process involves:

• Creating the cluster and specifying network configuration

• Generating a self-signed certificate authority (CA) and using it to sign the cluster's certificate signing request (CSR)

• Initializing the master HSM with the HSM management tool

HSMs in the same zone use the same VPC subnet.

{
 "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 3: Start the hsm_proxy HSM client

hsm_proxy is the HSM client that runs on your ECS instance and routes cryptographic requests to the HSM cluster.

1. Edit /opt/hsm/etc/hsm_proxy.cfg: Example configuration:

   • Set server.hostname to the IP address of the VPC to which the current instance belongs.

   • Set client.e2e_owner_crt_path to the full path of issuerCA.crt (the self-signed CA certificate you created in Step 2).

   {
   
       "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 hsm_proxy:

   /opt/hsm/bin/hsm_proxy /opt/hsm/etc/hsm_proxy.cfg

   The output shows the log file path:

   logfiles_location is not specified, logs will be available in current directory
   
   Logs will be available in liquidSecurity.1.WKCrty.log file

3. Verify the connection by checking the log file:

   tail liquidSecurity.1.WKCrty.log

   A successful connection includes the following line:

   2023-10-28T13:33:05Z liquidSecurity INF: e2e_handle_client_request: HSM FIPS STATE 2

   The full expected output looks like:

   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

Skip this step if you are configuring the cluster for a KMS hardware key management instance. See Configure an HSM cluster for a hardware key management instance of KMS.

1. Start key_mgmt_tool:

   /opt/hsm/bin/key_mgmt_tool

2. Log on as the crypto user (CU):

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

   Note the key handle (6 in this example) — use it to reference the key in subsequent operations.

4. Confirm the key exists with findKey:

   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. Exit key_mgmt_tool:

   Command:  exit

Step 5: Encrypt and decrypt data

Skip this step if you are configuring the cluster for a KMS hardware key management instance. See Configure an HSM cluster for a hardware key management instance of KMS.

To use the HSM cluster for cryptographic operations, choose one of the following interfaces:

• OpenSSL Dynamic Engine

• JCE (Java Cryptography Extension) provider

• PKCS#11 library

What's next

To manage your cluster — add or remove HSMs, rename the cluster, or update the access whitelist — see Create and activate a NIST FIPS-validated HSM cluster.