Using Fortanix Data Security Manager with AWS CloudHSM

1.0 Introduction

This article explains how to set up Amazon Web Service (AWS) Cloud Hardware Security Module (CloudHSM) and integrate it with Fortanix Data Security Manager (DSM) using Fortanix HSM Gateway.

2.0 Prerequisites

Ensure the following:

• EC2 instance for Fortanix HSM Gateway configuration.

• A Fortanix DSM cluster service URL.

• Deploy Fortanix HSM Gateway and AWS Cloud HSM on the same network.

3.0 Port Requirements

The following table lists the port requirements for AWS CloudHSM and Fortanix HSM Gateway:

NOTE

A single security group is used for both AWS CloudHSM and Fortanix HSM Gateway. Therefore, custom TCP port 4442 is reserved for Fortanix HSM Gateway.

4.0 Product Version Tested

The following product versions were tested:

• Fortanix DSM - 5.0.2815-312

• AWS CloudHSM - LS2-FW-10.02-1102

• AWS PKCS#11 - cloudhsm-pkcs11-5.16.1-1.el9.x86_64

• AWS command line (CLI) - cloudhsm-cli-5.16.1-1.amzn2023.x86_64

• HSM GW EC2 instance running RHEL 9.2

• Fortanix HSM Gateway - fortanix-hsm-gateway-5.2.2852.3165.8-0.x86_64

5.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

5.1 Signing Up

5.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

6.0 Create VPC and a Subnet

Perform the following steps to create a Virtual Private Cloud (VPC) and a subnet:

1. Log in to the AWS Console.

2. Navigate to VPC dashboard.

3. Click Create VPC and then create a subnet.

NOTE

Use default VPC and subnet settings unless your deployment requires customization.

7.0 Create AWS CloudHSM Cluster

Perform the following steps to create the AWS CloudHSM cluster:

1. In the AWS Console, search for CloudHSM and go to CloudHSM dashboard, and click Create Cluster.

   

2. Select the Cluster Type such as FIPS or non-FIPS to configure the cluster.

3. Select the VPC and subnet from the drop down menu.

4. Click Next.

5. Set the Backup retention period (in days) to define how long backups are retained.

   

6. Click Next.

7. Review the cluster configuration and click Create cluster.

   

   

   NOTE

   Use the security group created by the AWS CloudHSM cluster for Fortanix HSM Gateway EC2 instance.

8.0 Initialize the AWS CloudHSM Cluster

Perform the following steps to initialize the AWS CloudHSM cluster:

1. In the AWS CloudHSM cluster, click Initialize.

   

2. On the Create an HSM in the cluster page, select the Availability Zone from the drop down menu and the click Create to create this AWS CloudHSM.

   

3. On the Download certificate signing request page, download the cluster.csr file from the cluster.

   

4. Use your Certificate Authority (CA) to:

   • Sign the cluster.csr.

   • Generate the cluster certificate and the customer certificate authority (CA) certificate.

   For more information on how to sign the Certificate Signing Request (CSR), refer to the AWS official documentation.

5. On the Upload certificate page, upload the following signed certificates:

   • Cluster certificate: cluster-certificate.crt

   • Issuing certificate: customerCA.crt

   

6. Once the certificates are uploaded, click Upload and initialize.

9.0 Activate the AWS CloudHSM Cluster

Perform the following steps to activate the AWS CloudHSM cluster:

1. Log in to the Fortanix HSM Gateway EC2 instance with network access to the AWS CloudHSM cluster.

2. Run the following command to download the AWS CloudHSM CLI:

   wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-cli-5.16.1-1.amzn2023.x86_64.rpm

3. Run the following command to update the permission of the AWS CloudHSM CLI:

   chmod +x cloudhsm-cli-5.16.1-1.amzn2023.x86_64.rpm

4. Run the following command to install the AWS CloudHSM CLI package:

   yum install ./cloudhsm-cli-5.16.1-1.amzn2023.x86_64.rpm

5. Run the following command to configure the AWS CloudHSM CLI with the CloudHSM internet protocol (IP) address:

   cd /opt/cloud/hsm/bin
   ./configure-cli -a <IP_ADDRESS_OF_AWS_CLOUD_HSM>

6. Run the following command to add the customer CA certificate as created in Step 5 of Section 8.0: Initialize the AWS CloudHSM Cluster:

   sudo cp customerCA.crt /opt/cloudhsm/etc/

   

7. Run the following command to connect to the AWS CloudHSM cluster:

   /opt/cloudhsm/bin/cloudhsm-cli interactive

   After connecting, you can manage users and keys within the cluster.

8. Run the following command to activate the AWS CloudHSM cluster:

   aws-cloudhsm> cluster activate

   When prompted, enter and confirm the password.

   

9. Run the following command to add the IP address of the AWS CloudHSM in configuration:

   ./configure-cli -a <IP_ADDRESS_OF_HSM1> <IP_ADDRESS_OF_HSM2>

   NOTE

   An AWS CloudHSM cluster requires a minimum of 2 HSMs to manage the keys with high availability.

10. Run the following command to verify the cloudhsm-cli.cfg file:

    cat /opt/cloudhsm/etc/cloudhsm-cli.cfg

    

11. Run the following commands to create the user in AWS CloudHSM:

    aws-cloudhsm> login --username admin --role admin
    aws-cloudhsm> user create --username cryptouser --role crypto-user

12. (Optional) Log in as a user (crypto-user: role) and run the following commands to create the keys:

    aws-cloudhsm>login --username crypto-user --role crypto-user
    aws-cloudhsm>key generate-symmetric aes --label test-key --key-length-bytes 32
    aws-cloudhsm>key list

    

10.0 Install the AWS CloudHSM PKCS#11 Package

Perform the following steps to download and install the AWS CloudHSM PKCS#11 package:

1. Run the following command to download the AWS CloudHSM PKCS#11 package:

   wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-5.16.1-1.el9.x86_64.rpm

2. Run the following command to update the permissions of the AWS CloudHSM PKCS#11 file:

    chmod +x cloudhsm-pkcs11-5.16.1-1.el9.x86_64.rpm

3. Run the following command to install the AWS CloudHSM PKCS#11 package:

   yum install ./cloudhsm-pkcs11-5.16.1-1.el9.x86_64.rpm

4. Run the following command to configure AWS CloudHSM PKCS#11 with HSM IP address:

   ./configure-pkcs11 -a <HSM1_IP_ADDRESS> <HSM2_IP_ADDRESS>

   Once PKCS#11 is configured with AWS CloudHSM, the cloudhsm-pkcs11.cfg configuration file is created in the /opt/cloudhsm/etc directory.

   

   The PKCS#11 library allows applications to securely interact with AWS CloudHSM and perform cryptographic operations such as key generation, encryption, and signing using PKCS#11 interface.

11.0 Set Up Fortanix HSM Gateway for AWS CloudHSM

Perform the following steps to install and configure Fortanix HSM Gateway in EC2 instance:

1. Run the following command to download the Fortanix HSM Gateway package:

   wget https://download.fortanix.com/clients/5.2.2852/fortanix-hsm-gateway-5.2.2852.3165.8-0.x86_64.rpm

2. Run the following command to update the permission of the Fortanix HSM Gateway file:

   chmod +x fortanix-hsm-gateway-5.2.2852.3165.8-0.x86_64.rpm

3. Run the following command to install the Fortanix HSM Gateway package:

    yum install ./fortanix-hsm-gateway-5.2.2852.3165.8-0.x86_64.rpm

4. Run the following command to edit and verify the ftx-hmg configuration file:

   cat /etc/default/ftx-hmg
   # This file contains configuration for the Fortanix HSM Gateway service
   # Path to the pkcs12 cert. This package provides path /etc/fortanix/pki/
   CERT_FILE=/etc/fortanix/pki/cert.p12
   
   # Path to the pem ca cert (to authenticate client cert). Set only if you want to run in mutual TLS mode.
   # CA_FILE=/etc/fortanix/pki/ca.pem
   
   # The network port for the HSM Gateway to listen on. Default is 4442
   HMG_TOKEN_LABEL=hsm1
   HMG_SLOT_ID=0
   HMG_TOKEN_PIN=cryptouser:password
   HMG_LISTEN_PORT=4442
   
   CKNFAST_OVERRIDE_SECURITY_ASSURANCES="tokenkeys;explicitness"
   
   CKNFAST_FAKE_ACCELERATOR_LOGIN=1
   
   # Enables verbose logging for application failures
   RUST_BACKTRACE=full
   
   # Default ncipher path = /opt/nfast/toolkits/pkcs11/libcknfast.so
   # Default luna path = /usr/safenet/lunaclient/lib/libCryptoki2_64.so
   PKCS11_LIB_PATH=/opt/cloudhsm/lib/libcloudhsm_pkcs11.so

   NOTE

   • Ensure that the necessary parameters such as HSM IP addresses, certificates, and logging options are correctly set.

   • Ensure to generate the PKCS#12 certificate (cert.p12) with OpenSSL before configuring the Fortanix HSM Gateway. For more information, refer to Section 11.1: Generating a PKCS#12 Certificate.

5. Run the following command to install the Open Smart Card (OpenSC) dependency:

   yum install opensc

11.1 Generating a PKCS#12 Certificate

Perform the following steps to generate a PKCS#12 certificate for standard mode connectivity from Fortanix DSM to HSM Gateway:

1. Run the following command to generate a self-signed certificate:

   openssl req -x509 -newkey rsa:4096 -keyout /path/to/cert/dir/key.pem -out /path/to/cert/dir/cert.pem -days 365 -nodes

2. Run the following command to export the certificate and private key into a PKCS#12 file:

   NOTE

   When prompted, press Enter without entering a password.

   openssl pkcs12 -export -out /path/to/cert/dir/cert.p12 -inkey /path/to/cert/dir/key.pem -in /path/to/cert/dir/cert.pem

   NOTE

   The PKCS#12 certificate (cert.p12) is required in the Fortanix HSM Gateway configuration file (/etc/default/ftx-hmg).

3. Run the following command to copy cert.p12 file to /etc/fortanix/pki directory to define the location of the certificate file in Fortanix HSM Gateway service:

   cp cert.p12 /etc/fortanix/pki

12.0 Start the Fortanix HSM Gateway Service

Perform the following steps to start the Fortanix HSM Gateway service:

1. Run the following command to start the Fortanix HSM Gateway service:

   systemctl start ftx-hmg

2. Run the following command to verify the service status:

   systemctl status ftx-hmg

   The output may resemble as follows:

   

3. Run the following command to list the available slots in AWS CloudHSM:

   pkcs11-tool --module /opt/cloudhsm/lib/libcloudhsm_pkcs11.so -L

   The output may resemble as follows:

   Available slots:
   Slot 0 (0x2000000000000001): hsm1
     token label        : hsm1
     token manufacturer : Marvell Semiconductors, Inc.
     token model        : LS2
     token flags        : login required, rng, token initialized
     hardware version   : 66.48
     firmware version   : 10.2
     serial num         : 
     pin min/max        : 8/32
     uri                : pkcs11:model=LS2;manufacturer=Marvell%20Semiconductors%2c%20Inc.;serial=;token=hsm1

13.0 Integrate AWS CloudHSM with Fortanix DSM

Perform the following steps to integrate AWS CloudHSM with Fortanix DSM:

1. In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.

2. On the Adding new group page, enter the following details:

   1. Title: Enter a title for your group.

   2. Description (optional): Enter a short description for the group.

   3. In the Configure as HSM/External KMS group section, click LINK HSM/EXTERNAL KMS and select the HSM type as AWS CloudHSM, so that Fortanix DSM can connect to it.

   4. In the Authentication section, do the following:

      1. HMG IP Address: Enter the IP address of the Fortanix HSM Gateway.

      2. Port: The default port value is 4442.

      3. Slot: Use the slot number obtained using the following pkcs11-tool command:

         pkcs11-tool --module /opt/cloudhsm/lib/libcloudhsm_pkcs11.so -L

         

         For more information to convert the slot ID from hexadecimal to decimal format, refer to Section 14.0: Slot ID Conversion.

      4. PIN: Use the format username:password. For example, cryptouser:password.

      5. To configure TLS configuration for standard mode, enter the output of cert.pem file in the CA certificate option as created in Step 1 of Section 11.1: Generating a PKCS#12 Certificate.

      6. Click TEST CONNECTION.

      

3. Click SAVE to create the group.

14.0 Slot ID Conversion

AWS CloudHSM generates slot IDs in hexadecimal, but Fortanix DSM requires the slot ID in decimal format.

Perform the following steps to configure the slot ID in Fortanix DSM:

1. Enter placeholder values for the slot ID in the Fortanix DSM user interface (UI) and save.

2. Open the browser developer tools, go to the Network tab, and capture the PATCH API call.

3. Use Postman to re-send the PATCH API request with the slot number in decimal format.

The following is an example for API Payload:

PATCH https://<DSM_URL>/sys/v1/groups/<GROUP_ID>

The following is the response body of the API:

{
  "group_id": "2b5663a3-eea9-4821-bb7b-98e1ad003717",
  "hmg_redundancy": "PriorityFailover",
  "mod_hmg": {
    "<HMG_ID>": {
      "kind": "AWSCLOUDHSM",
      "url": "13.50.107.118:4442",
      "tls": {
        "mode": "required",
        "validate_hostname": false,
        "ca": { "pinned": ["<CA_CERT_BASE64>"] },
        "client_key": "<CLIENT_KEY_BASE64>",
        "client_cert": "<CLIENT_CERT_BASE64>"
      },
      "slot": 2305843009213693953,
      "hsm_order": 1,
      "id": "<HMG_ID>",
      "credentials": [""],
      "pin": "cryptouser:password"
    }
  }
}

15.0 Verification

Perform the following steps to verify the integration between AWS CloudHSM and Fortanix DSM:

1. Test the connection. A successful message indicates that the configuration is correct.

   

2. Create a key with the Export permission in the AWS CloudHSM group.

   

3. Verify that the created key is virtually available in Fortanix DSM.

   

4. Log in to the AWS CloudHSM console to confirm that the key is present in AWS.

   

5. Verify the Fortanix HSM Gateway logs to ensure successful key creation and synchronization.