DocsICP FilingConsole
Documentation
Home Page Key Management Service Cloud Hardware Security Module (HSM) Use Cases Secure SSL offloading based on CloudHSM Configure SSL offload with an EVSM

Configuring SSL offload for EVSM

Updated at:
Copy as MD
Product
My Favorites

This topic describes how to use an EVSM to perform SSL offload for applications on a Linux system.

Step 1: Before you begin

  1. Prepare the following software resources.

    Type

    Description

    How to obtain

    HSM instance management tool

    Used to configure your virtual HSM instance.

    1. Log on to the CloudHSM console, go to the virtual HSM instance page, find your instance, and click the download icon next to its specification, such as Financial Data HSM, to download the cryptography service package.

    2. The HSM instance management tool and user manual are in the \Alibaba Cloud Cryptography Service - EVSM Software Package XXXX\Management Tool and User Manual directory of the software package.

    TASSL engine

    A TASSL engine package that enables calls to the EVSM. It supports both Chinese cryptographic algorithms and international algorithms.

    Contact Alibaba Cloud technical support.

    Nginx proxy

    An Nginx service package compatible with the TASSL engine.

    Contact Alibaba Cloud technical support.

  2. Deploy the following cloud resources.

    Resource name

    Specification

    Description

    ECS1

    64-bit Windows 10 system

    Used for managing and configuring the EVSM. This ECS instance must be in the same VPC as the virtual HSM instance. For information about how to purchase an instance, see Create an instance by using the wizard.

    The management port that ECS1 uses to access the EVSM must be 8013.

    ECS2

    64-bit Linux system

    Used for deploying your application, TASSL, and Nginx. This ECS instance must be in the same VPC as the virtual HSM instance.

    Note

    • ECS2 must use service port 8018 to access the EVSM.

    • You must configure the SSL port service on ECS2.

    EVSM

    Financial Data HSM (EVSM)

    Performs cryptographic operations for SSL offloading.

Step 2: Configure the management tool

Important

The HSM client management tool runs only on Windows.

  1. Log on to the ECS1 instance. For more information, see Overview of connection methods for ECS instances.

  2. Install the HSM instance management tool on ECS1. Then, use a local terminal to remotely log on to the ECS instance and use the tool.

    Note

    Alternatively, you can install the HSM instance management tool on your local machine and then connect your local machine to the virtual HSM instance's VPC by using a VPN or Express Connect.

  3. Use the HSM instance management tool to initialize the virtual HSM instance. For more information, see the "Initial Initialization" chapter in the user manual included in the software package.

    If you have already initialized the virtual HSM instance, skip this step.

Step 3: Deploy TASSL

  1. Log on to the ECS2 instance. For more information, see Overview of connection methods for ECS instances.

  2. Upload the TASSL engine package nginx_tassl_tasshsmXX.XX.XX to ECS2 and extract it to a directory, such as /home/tass.

    Note

    This package usually includes an Nginx service package. Extract it to the /home/tass directory as well.

    If you do not extract the package to the /home/tass directory, you must configure two environment variables to specify the paths to the engine library and its configuration file. For example:

    export OPENSSL_ENGINES=/home/other/tassl/lib/engines-1.1/
export TASSL_ENGINE_CFG=/home/other/tassl/cfg/tasshsm_engine.ini

  3. Configure the TASSL engine to connect to your EVSM.

    In the /home/tass/tassl/cfg/tasshsm_engine.ini file, set HSM_IP to your EVSM's IP address and HSM_PORT to its service port.

    # The IP address of the EVSM.
HSM_IP      = 172.XX.XX.183 
# Must be 8018.
HSM_PORT    = 8018

    You can find the IP address of the EVSM in the IP Address column of the console. Log on to the Cryptographic Service console and obtain the IP address of the EVSM from the IP Address column on the virtual HSM instance list page.

Step 4: Request and issue SSL certificates

You can generate a certificate signing request (CSR), also known as a P10 file, for servers that use RSA, SM2, or ECC algorithms, which you then use to issue the certificates.

RSA certificate request and issuance

  1. Generate a certificate signing request (CSR).

    1. Log on to the HSM instance management tool.

      The default port is 8013. No changes are required.

    2. Generate a new key.

      1. Click the Key Management tab, and then click Asymmetric Key Management.

      2. In the Asymmetric Key Management dialog box, click Generate New Key.

      3. In the Generate Asymmetric Key dialog box, set Algorithm Identifier to RSA, Key Modulus Length to 2048, and Exponent to 65537. Enter a custom Key Index, and then click Generate.

      4. The EVSM generates a new asymmetric key and displays the public key in plaintext and the private key in ciphertext.

    3. Generate the CSR.

      • Method 1: Use the HSM instance management tool

        1. In the Asymmetric Key Management dialog box, click Generate RSA Request.

        2. In the Generate RSA dialog box, enter a valid Subject, select whether to Use Internal Index, enter the Key Index, and then click OK.

        3. Copy the P10 request and save it as a CSR file, for example, S_RSA_HSM.csr.

      • Method 2: Use the TASSL script

        Go to the /home/tass/tassl/cert/rsa directory on ECS2 and generate the CSR file S_RSA_HSM.csr.

        [tass@localhost rsa]#./gen_rsa_csr_with_hsm -r S_RSA_HSM.csr
Please enter DN: /C=CN/ST=BJ/L=HaiDian/O=Beijing JNTA Technology LTD./OU=BSRC of TASS/CN=rsa_commoname/
Please enter key modulus length [1024 - 2048]:2048
Select digest algorithm: 1)SHA1
	        2)SHA224
		3)SHA256
		4)SHA384
		5)SHA512
Enter: 3
Enter the index for the private key stored in the HSM: 15

  2. Issue the certificate.

    Important

    For testing purposes, we recommend using a self-signed certificate. For production environments, we recommend using a certificate issued by a certificate authority (CA) or through Alibaba Cloud Certificate Management Service.

    This topic uses a self-signed certificate as an example. For information about how to issue a certificate by using Certificate Management Service, see Submit a certificate application.

    1. Go to the /home/tass/tassl/cert/rsa directory on ECS2.

    2. Issue S_RSA_HSM.crt.

      ./sign_cert.sh S_RSA_HSM.csr S_RSA_HSM.crt

SM2 certificate request and issuance

  1. Generate the CSR files.

    1. Log on to the HSM instance management tool.

      The default port is 8013. No changes are required.

    2. Generate a signing key and an encryption key.

      1. Click the Key Management tab, and then click Asymmetric Key Management.

      2. In the Asymmetric Key Management dialog box, click Generate New Key.

      3. In the Generate Asymmetric Key dialog box, set Algorithm Identifier to SM2, enter a Key Index, and then click Generate.

        In this example, the key index for the signing key is 15, and the key index for the encryption key is 16.

      4. The EVSM generates new asymmetric keys and displays the public keys in plaintext and the private keys in ciphertext.

    3. Generate separate CSRs for the signing and encryption certificates.

      1. Method 1: Use the HSM instance management tool

        1. In the Asymmetric Key Management dialog box, click Generate SM2/ECC Request.

        2. In the Generate SM2/ECC Request dialog box, select an Algorithm Identifier and a Subject Identifier. Enter a Subject and a Key Index, and then click OK. Use a key index of 15 for the signing certificate's CSR and 16 for the encryption certificate's CSR.

        3. Copy the P10 requests and save them as CSR files. For example, name the signing CSR file SS_SM2_HSM.csr and the encryption CSR file SE_SM2_HSM.csr.

      2. Method 2: Use the TASSL script

        Go to the /home/tass/tassl/cert/sm2 directory on ECS2 to generate the CSR files for the signing and encryption certificates. For example, name the signing CSR file SS_SM2_HSM.csr and the encryption CSR file SE_SM2_HSM.csr.

        # Generate the signing certificate CSR file SS_SM2_HSM.csr
[tass@localhost rsa]# ./gen_sm2_csr_with_hsm -r SS_SM2_HSM.csr
Please enter DN: /C=CN/ST=BJ/L=HaiDian/O=Beijing JNTA Technology LTD./OU=BSRC of TASS/CN=sm2_commoname/
Enter the index for the private key stored in the HSM: 15
# Generate the encryption certificate CSR file SE_SM2_HSM.csr
[tass@localhost rsa]# ./gen_sm2_csr_with_hsm -r SE_SM2_HSM.csr
Please enter DN: /C=CN/ST=BJ/L=HaiDian/O=Beijing JNTA Technology LTD./OU=BSRC of TASS/CN=sm2_commoname/
Enter the index for the private key stored in the HSM: 16

  2. Issue the certificates.

    Important

    For testing purposes, we recommend using a self-signed certificate. For production environments, we recommend using a certificate issued by a certificate authority (CA) or through Alibaba Cloud Certificate Management Service.

    This topic uses a self-signed certificate as an example. For information about how to issue a certificate by using Certificate Management Service, see Submit a certificate application.

    1. Go to the /home/tass/tassl/cert/sm2 directory on ECS2.

    2. Issue the signing certificate file SS_SM2_HSM.crt and the encryption certificate file SE_SM2_HSM.crt.

      # Issue the signing certificate file SS_SM2_HSM.crt
./sign_cert_s.sh SS_SM2_HSM.csr SS_SM2_HSM.crt
# Issue the encryption certificate file SE_SM2_HSM.crt
./sign_cert_e.sh SE_SM2_HSM.csr SE_SM2_HSM.crt

ECC certificate request and issuance

  1. Generate a CSR.

    1. Log on to the HSM instance management tool.

      The default port is 8013. No changes are required.

    2. Generate a new key.

      1. Click the Key Management tab, and then click Asymmetric Key Management.

      2. In the Asymmetric Key Management dialog box, click Generate New Key.

      3. In the Generate Asymmetric Key dialog box, set Algorithm Identifier to NISTP256 (SECP256R1) and Key Index to 17, and then click Generate.

      4. The EVSM generates a new asymmetric key and displays the public key in plaintext and the private key in ciphertext.

    3. Generate the CSR.

      • Method 1: Use the HSM instance management tool

        1. In the Asymmetric Key Management dialog box, select the generated ECC key, and then click Generate SM2/ECC Request.

        2. In the Generate SM2/ECC Request dialog box, select an Algorithm Identifier and a Subject Identifier. Enter a Subject and a Key Index, and then click OK. Copy the P10 request and save it as a CSR file. For example, S_ECC_HSM.csr.

      • Method 2: Use the TASSL script

        Go to the /home/tass/tassl/cert/ecc directory on ECS2 and generate the CSR file S_ECC_HSM.csr.

        [tass@localhost rsa]# ./gen_ecc_csr_with_hsm -r S_ECC_HSM.csr
Please enter DN: /C=CNST=BJ/L=HaiDian/O=Beijing JNTA Technology LTD./OU=BSRC of TASS/CN=ecc_commoname/
Select digest algorithm:1)SHA1
							2)SHA224
							3)SHA256
							4)SHA384
							5)SHA512
Enter: 3
Enter the index for the private key in the HSM (0 means do not save and output the encrypted private key instead): 17

  2. Issue the certificate.

    Important

    For testing purposes, we recommend using a self-signed certificate. For production environments, we recommend using a certificate issued by a certificate authority (CA) or through Alibaba Cloud Certificate Management Service.

    This topic uses a self-signed certificate as an example. For information about how to issue a certificate by using Certificate Management Service, see Submit a certificate application.

    1. Go to the /home/tass/tassl/cert/ecc directory on ECS2.

    2. Issue the certificate file S_ECC_HSM.crt.

      ./sign_cert.sh S_ECC_HSM.csr S_ECC_HSM.crt

Step 5: Deploy Nginx service

  1. Configure the Nginx service to use the server certificates for each cryptographic algorithm.

    Edit the certificate section of the /home/tass/nginx/conf/nginx.conf configuration file, referring to the following examples.

    RSA

    worker_processes auto;
…
…
    # HTTPS server
    server {
        listen       8020 ssl;
        server_name  localhost;
        #use tasshsm engine by key index
        ssl_certificate  /home/tass/tassl/cert/rsa/S_RSA_HSM.crt;  # Path to the RSA certificate file.
        ssl_certificate_key  engine:tasshsm_rsa:15; # Index of the RSA private key stored in the HSM.
        ssl_verify_client off; #for one way https # Disables client certificate verification.
        ssl_session_cache    shared:SSL:1m;
        ssl_session_timeout  5m;
        ssl_ciphers  HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers  on;
        location / {
            root   html;
            index  index.html index.htm;
        }
}
…

    SM2

    worker_processes auto;
…
…
    # HTTPS server
    server {
        listen       8021 ssl;
        server_name  localhost;
        #use tasshsm engine by key index
        ssl_certificate   /home/tass/tassl/cert/sm2/SS_SM2_HSM.crt; # Path to the signing certificate file.
        ssl_certificate_key   engine:tasshsm_sm2:15; # Index of the signing private key stored in the HSM.
        ssl_enc_certificate   /home/tass/tassl/cert/sm2/SE_SM2_HSM.crt; # Path to the encryption certificate file.
        ssl_enc_certificate_key  engine:tasshsm_sm2:16; # Index of the encryption private key stored in the HSM.
        ssl_verify_client off; # for one way https # Disables client certificate verification.
        …
        location / {
            root   html;
            index  index.html index.htm;
        }
}
…

    ECC

    worker_processes auto;
…
…
    # HTTPS server
    server {
        listen       8022 ssl;
        server_name  localhost;
        #use tasshsm engine by key index
        ssl_certificate  /home/tass/tassl/cert/ecc/S_ECC_HSM.crt; # Path to the ECC certificate file.
        ssl_certificate_key  engine:tasshsm_ecc:17; # Index of the ECC private key stored in the HSM.
        ssl_verify_client off; #for one way https # Disables client certificate verification.
        ssl_session_cache    shared:SSL:1m;
        ssl_session_timeout  5m;
        ssl_ciphers  HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers  on;
        location / {
            root   html;
            index  index.html index.htm;
        }
}
…

  2. Run the following commands to start the Nginx proxy:

    cd /home/tass/nginx/sbin
./nginx

Step 6: Test and verify

After deployment, you can use the following methods to verify that the RSA and SM2 server certificates are deployed correctly.

  • To verify an RSA certificate deployment, access the server address (for example, 192.168.19.230) in a browser. The Nginx default welcome page (Welcome to nginx!) indicates that the server certificate is deployed and the Nginx service is running correctly.

  • If you are using an SM2 server certificate (dual certificates), verify the deployment as follows:

    1. On the client, install a browser that supports Chinese cryptographic algorithms, such as 360 Secure Browser. Then, import the CA certificate issued to the server into the browser and mark it as trusted.

    2. Copy the contents of the /home/tass/tassl/cert/sm2/ca.crt file on ECS2 to the C:\Users\Administrator\AppData\Roaming\360se6\User Data\Default\gmssl\ctl.dat file on the client.

    3. Restart the browser.

    4. In the C:\Windows\System32\drivers\etc path, edit the hosts file to map the server address to your test domain name.

    5. Access your test domain name in the browser.

Previous：Configure SSL offloading by using GVSM (SM)Next：Configure CloudHSM cluster for KMS hardware instance