This topic describes how to quickly get started with Cloud Hardware Security Module.
If you want to create a hardware security module (HSM) cluster for Key Management Service (KMS) instances of the hardware key management type, see Configure an HSM cluster for a KMS instance of the hardware key management type.
Prerequisites
A virtual private cloud (VPC) is created. vSwitches are created in the VPC. For more information, see Create a VPC with an IPv4 CIDR block.
An Elastic Compute Service (ECS) instance that runs a CentOS 8 or an Alibaba Cloud Linux operating system is created. The ECS instance must reside in the same virtual private cloud (VPC) subnet as the master HSM to create. For more information, see Create an instance by using the wizard.
Step 1: Create an HSM
Log on to the Cloud Hardware Security Module console. In the top navigation bar, select the required region.
On the Instances page, click Create HSM.
On the Cloud Hardware Security Module buy page, configure the parameters and click Buy Now to complete the payment. The following table describes the parameters.
Parameter
Description
Region
The region of the HSM. For more information, see What is Cloud Hardware Security Module?.
You can use an HSM only in a VPC. Make sure that the HSM resides in the same region as your VPC and ECS instance.
Zone
The zone of the HSM. To ensure service continuity in case of a data center incident in a zone, we recommend that you deploy HSMs in different zones.
NoteYou can establish network connections across zones only if the zones belong to the same region.
Your HSMs and ECS instance can reside in different zones.
Quantity
The number of HSMs that you want to purchase. To ensure high availability of Cloud Hardware Security Module, we recommend that you purchase at least two HSMs.
Duration
The subscription duration of Cloud Hardware Security Module.
We recommend that you select Auto-renewal to prevent permanent loss of keys that can occur if you do not renew Cloud Hardware Security Module before the subscription duration elapses. If you select Auto-renewal, Alibaba Cloud automatically deducts fees from the Alibaba Cloud account that is used to purchase HSMs nine calendar days before Cloud Hardware Security Module expires. Make sure that your account balance is sufficient.
After you create an HSM, you can view the HSM on the Instances page. The value of Status for the HSM is New.
Step 2: Enable the HSM
On the Instances page, find the HSM that you created and click Enable in the Actions column.
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.
ImportantThe 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.
ImportantIf 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.
If the configuration is successful, the value of Status for the HSM changes to Enabled.
Step 3: Create and activate an HSM cluster
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.
On the Instances page, find an HSM that you want to use as the master HSM and click Create Cluster in the Actions column.
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 whitelist 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.
ImportantThe 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.
Specify a vSwitch for the zone of another purchased HSM
The vSwitch for the zone of another purchased HSM. You can select the vSwitch based on your business requirements.
You must configure two vSwitches for a cluster to create and activate the cluster.
In the Create and Activate Cluster panel, complete the Activate Cluster step.
Import a cluster certificate.
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.
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
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
Sign the CSR and save the issued certificate in the cluster.crt file.
NoteIn 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
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.
Initialize the master HSM.
Step
Description
Step 1: Download the HSM management tool.
ImportantYou can install the HSM management tool only in Linux operating systems.
Download the HSM management tool by using one of the following methods:
Run the following command to download the HSM management tool. You can use this method only if your ECS instance is 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'
On the Instances page, find the master HSM, click the information about the master HSM in the Specifications column, and then click Download HSM Management Tool.
In the Activate Cluster step of 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: Replace the values with the private IP address of the master HSM.
owner_cert_path: Replace the value with the path to the issuerCA.crt file.
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 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).
Run the
loginHSM
command to log on to the master HSM as a PRECO.cloudmgmt>loginHSM PRECO admin password loginHSM success
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
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).
WarningBefore 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.
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. If you configure an HSM cluster for an instance of the hardware key management type, you can specifykmsuser
as the username.createUser CU crypto_user <enter password>
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.
Return to the Cloud Hardware Security Module console. In the Activate Cluster step of the Activate Cluster panel, click the icon to refresh the status of the master HSM. Then, click Next.
In the Add HSM step, add non-master HSMs 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 4: Start the hsm_proxy HSM client
Modify the configuration file of the HSM client.
In the installation directory of the HSM management tool, find the /opt/hsm/etc/hsm_proxy.cfg file, change server.hostname to the IP address of the VPC to which the current HSM belongs, and change client.e2e_owner_crt_path to the path of the issuerCA.crt file.
NoteissuerCA.crt is the self-signed certificate that is created when you activate the cluster. For more information, see Step 3: Create and activate an HSM 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 } }
Start the HSM client and specify a 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
Check whether the HSM client is connected.
Run the
tail
command to obtain the log file of the HSM client and check whether the HSM client is connected. For example, run thetail liquidSecurity.1.WKCrty.log
command. If e2e_handle_client_request:HSM FIPS STATE 2 is returned in the response, 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 5: (Optional) Create a key
If you configure an HSM cluster for a KMS instance of the hardware key management type, skip this step.
Start the key_mgmt_tool command line tool.
/opt/hsm/bin/key_mgmt_tool
Run the
loginHSM
command to log on to the master HSM as a 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
Run 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
Run the
findKey
command to query the created key.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
Run the
exit
command to exit the key_mgmt_tool command line tool.Command: exit
Step 6: (Optional) Encrypt and decrypt data by using 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.