User's Guide: HSM Gateway

1.0 Introduction

A Hardware Security Module (HSM) can come in various shapes and forms; there are smart cards, PCI cards to plug into a PC, USB tokens, separate boxes that communicate over channels like TCP/IP, USB or rs-232, and so on. Regardless of the shape or package, the main purpose of these modules is either:

• Speeding up cryptographic operations, or
• Keeping keys safe, or
• Some modules may be able to offer both but more often than not this is not the case.

1.1 HSM Gateway Architecture

Figure 1: HSM Gateway Architecture

The Fortanix HSM Gateway solution requires that the customer applications use one of the Fortanix Data Security Manager (DSM) interfaces (REST, PKCS#11, KMIP, JCE, or CNG) to interact with Fortanix DSM for key management and cryptographic operations. These applications should be configured to authenticate to Fortanix DSM using API keys, Certificate, Trusted CA, or JWT instead of talking directly to Thales HSMs.

An HSM group is created in Fortanix DSM and this group is configured with the HSM Gateway’s IP and HSM slot’s pin. Each HSM Gateway will be talking to exactly one HSM slot with a unique pin. After the HSM group successfully connects to the HSM using the connection details, the keys from the HSM are stored in the Fortanix DSM HSM group as virtual keys. A virtual key is a key whose key material is not present in the HSM group. The key material is stored securely in an External HSM, Cloud HSM, or even in another Fortanix DSM group. The virtual key is only a pointer with the key information and key attributes, but it does not hold the key material.

2.0 Fortanix Data Security Manager HSM Gateway Workflow

2.1 Create a Group for HSM Connection

1. In the Fortanix DSM Groups  page, click the  button to create a new group.
2. In the Add new group form,
   
   1. Enter a title and description for your group.
   2. Next, click the LINK HSM/EXTERNAL KMS button to choose the HSM type, so that Fortanix DSM can connect to it.

2.2 Configure HSM

1. 1. Click the drop-down to select the HSM Type. Currently, Fortanix DSM supports connecting to nCipher HSM, SafeNet Luna, and AWS CloudHSM.
      Figure 2: Select HSM Type
   2. Enter the connection details to connect with your HSM.
      1. HMG IP-address: This is the IP address or hostname of the server running the HSM gateway.
      2. Port: This is the port number on which the HSM instance is running. The port number is 4442 by default. You can override it by providing a different port number.
      3. Slot: Each HSM has multiple slots, which are used for different purposes. A PKCS#11 slot is identified by a number. The PKCS#11 slot ID can be obtained using a pkcs11-tool which can be downloaded separately from the internet.
         For example, to get the Slot ID for nCipher HSMs, use the following command:

         pkcs11-tool -L --module /opt/nfast/toolkits/pkcs11/libcknfast.so

         This will list all the available slots in hexadecimal format. Fortanix DSM requires that the Slot ID be in a decimal format. This conversion must be done by the user. The example output of the above command is:

         Available slots:
         Slot 0 (0x1d622495): XXXX-XXXX-XXXX Rt1
          token state: uninitialized
         Slot 1 (0x1d622496): XXXX-XXXX-XXXX Rt1 slot 0
          (empty)
         

      4. PIN: A unique Personal Identification Number (PIN) used to protect the HSM slot. The pkcs-11 tool can be used to initialize the PIN (--init-pin)  or update the PIN (--change-pin) using the PKCS#11 API.  This requires the user to be a “security officer”. For more details refer to the pkcs11-tool documentation.
         Figure 3: HSM connection details
   3. Click + ADD CONFIGURATION to add a certificate for authenticating your HSM. There are two certificate options to choose from.
      • Global Root CA - This option is for a self-signed certificate from a well-known CA. By default, every HSM Group is configured with a Global Root CA Certificate.
      • Custom CA Certificate – Use this certificate if you as an enterprise want to self-sign the certificate using your own internal CA. You can override the default Global CA cert with a Custom CA Certificate for an HSM group. You can either upload the certificate file or copy the contents of the certificate in the textbox provided.
        Figure 4: Custom CA certificate
      • Client Certificate (optional): A Custom CA Certificate also has a Client Certificate section where you can configure a client certificate and a private key (Fortanix DSM Certificate and Key). This field is used to run the service in mutual authentication mode. This allows Fortanix DSM to authenticate itself to the HSM gateway and vice versa.
        NOTE

        The client should also be set up in mutual authentication mode if this option is set, otherwise, the connection will fail.
        
        Figure 5: Add client cert and private key
      • Select the Validate Host check box to check if the certificate that the HSM provided has the same subjectAltName or Common Name (CN) as the hostname that the server certificate is coming from.

2.3 Test Connection

1. Click TEST CONNECTION to test your HSM connection. If Fortanix DSM is able to connect to your HSM using your connection details, then it shows the status as “Connected” with a green tick . Otherwise, it shows the status as “Not Connected” with a yellow warning sign .

2.4 Save HSM Group Details

Though testing the connection in the previous section is an optional step, you can save your group details even if the connection information might be incorrect or incomplete, you can edit these details later. Now, save your group details by clicking the SAVE button.

Figure 6: Save HSM Group

Once you save the group details, a group is created, and you will see the detailed view of that group.

2.4.1 Add Connection

If you have other nodes connecting to the same HSM, you can add another connection for high availability using the ADD CONNECTION button. As explained before, enter the HMG IP-address, Slot, and PIN for the new connection. You can edit these details any time and test if Fortanix DSM can connect to the node using the TEST CONNECTION button.

Figure 7: Add New Connection

After adding a new node, you will have the option to reorder the nodes to set the priority of HA instances. You can reorder the connection as seen in Figure 7 by using the following options available in the drop-down list:

• Move to the top
• Move up
• Move down
• Move to bottom
• Delete connection

You can also see the HSM node’s backend priority number in the UI when there are multiple nodes configured.

A new HSM tab is created in the group details, this tab shows the details about your HSM.

2.5 The HSM Tab

The HSM tab shows the details of the HSM that was added such as, HSM type which is “nCipher HSM” in this case. 

Figure 8: HSM Tab with reordering options

The HSM tab also shows the connection details you provided at the time of creation. You can edit this information at any time. Fortanix DSM automatically tests the connection. Then it shows if a connection to the HSM was successful.

The PIN is not shown to the user, but it is stored securely. The user does not need to re-enter the “PIN”, to test the connection.

In case, you have high-availability (HA) nodes, the HSM tab shows the connection details of the configured nodes and gives the option to reorder the nodes. You can reorder the connection by using the following options available in the drop-down list:

• Move to the top
• Move up
• Move down
• Move to bottom
• Delete connection

2.6 Sync Keys

Now, after successfully connecting to the HSM, you can get the keys from the HSM into Fortanix DSM. To do this you need to click the SYNC KEYS button in the HSM tab.

 On clicking SYNC KEYS, Fortanix DSM connects to the HSM and gets all the keys available from the HSM. These keys are stored as virtual keys in Fortanix DSM. Here, in this sample on clicking SYNC KEYS, 151 new keys from the HSM are added to Fortanix DSM.

Figure 9: Import Virtual Keys

2.7 Not Connected Scenario

On clicking TEST CONNECTION, it is possible that Fortanix DSM is not able to connect to the HSM node, in that case, it displays a “Not Connected” status with a warning symbol . You can save the details of the new connection details provided and edit them later.

2.8 Groups Table View

After saving the group details, you can see the list of all groups and notice the special symbol next to the newly created group, this symbol differentiates it from the other groups as it shows that it is an HSM group.

Figure 10: HSM Groups

2.9 Security Objects Table View

After you add new HSM keys by clicking SYNC KEYS, go to the Security Objects page to view all the security objects from all the groups (HSM and non-HSM).

In the security object table, you will notice that every key belongs to a group and some keys which are virtual keys added from an HSM, belongs to a group with a special symbol . The security objects table view will continue to show all the keys, whether they belong to an HSM group or not.

Figure 11: Security Objects Table View

2.10 Security Objects Detailed View

Click a security object from the Security Object detailed view.

The INFO tab shows the following details:

• The group to which it belongs (in the Group field). It also shows if the group is mapped to an HSM or not using the special icon .
• How the key was created (in the Created by field). If it is an HSM key, this field shows the group that created this key. It also shows minor details such as, if the group is “Connected” or “Not Connected”.

Figure 12: Security Object Detailed View

The ATTRIBUTES/TAGS tab shows the standard PKCS#11, CNG, and Custom attributes of the SO.

• As part of the key sync operation, Fortanix DSM reads the PKCS#11 attributes CKA_ID and CKA_LABEL of each key in the external HSM and adds them as PKCS#11 attributes for the corresponding virtual key in Fortanix DSM. These values are unique for every external HSM’s key.
  Figure 13: HSM key attributes
  NOTE

  The CKA_ID and CKA_LABEL PKCS#11 attributes are editable in Fortanix DSM. So, if any user edits the values of these attributes by mistake, they will need to resync the keys in the HSM group to get the original attribute values back from the external HSM for the corresponding key.

2.11 User View

Click the Users tab in the Fortanix DSM UI and click the user that says “You” to go to the user’s detailed view.

The detailed view shows all the groups which the user is a part of, additionally Fortanix DSM displays which groups are mapped to HSM and whether they are “Connected” or “Not Connected”.

                       Figure 14: User Detailed View

3.0 HSM Key Management Policy

The Key Management Policy can be configured in the detailed view of an HSM group in the INFO tab. This policy helps to manage virtual key changes in Fortanix DSM to the corresponding keys in the configured HSM. The users can select whether to apply or not apply changes performed on virtual keys such as destroying security objects, removing the private component of asymmetric keys, key permissions changes to the corresponding keys in the HSM. The default policy setting is to not apply the virtual key changes to the corresponding HSM as shown in Figure 15.

3.1 Edit Key Management Policy

• • When an existing virtual key is updated: When the virtual keys are updated/deleted, then these changes will only be applied to the virtual keys and will not be applied to the actual keys in the configured HSM (slot).
  • When a new virtual key is created: When a new virtual key is created in the HSM group, a new key is created in the configured HSM (slot) immediately with the exact metadata and key permissions as defined in the virtual key.
  • Permission changes: When the keys are scanned from HSM and if there are differences found between the virtual key’s permissions and the corresponding HSM key’s permissions, then the HSM key’s permissions will not overwrite the corresponding virtual key’s permissions.The default setting for the HSM Key Management policy is Do not apply changes performed on virtual keys in Self-Defending KMS to corresponding keys in HSM. The following are the key behaviors:
    For example, consider that the “encrypt” permission was removed for a virtual key in an HSM group. Now, when the keys are scanned from HSM using the SYNC KEYS button, and if the “encrypt” permission was present in the HSM then the scan will not overwrite the virtual key’s permission. Figure 15: Configure HSM policy
• To edit the default policy, click EDIT POLICY in Figure 15 and select the Apply changes performed on virtual keys in Self-Defending KMS to corresponding keys in HSM radio button. The following are the key behaviors:
  • When an existing virtual key is updated: When the virtual keys are updated/deleted, then this change will be applied immediately to the corresponding keys in HSM.
  • When a new virtual key is created: When a new virtual key is created in the HSM group, a new key is created in the configured HSM (slot) immediately with the exact metadata and key permissions as defined in the virtual key.
  • Permission changes: When the keys are scanned from HSM and if there are differences found between the virtual key’s permissions and the corresponding HSM key’s permissions, then the HSM key’s permissions will not overwrite the corresponding virtual key’s permissions.
    For example: Consider that the “encrypt” permission was removed for a virtual key in an HSM group in Fortanix DSM. This change is immediately applied to the corresponding HSM key. Now, when the keys are scanned from HSM using the SYNC KEYS button, and if the “encrypt” permission was added back in the HSM then the scan will not overwrite the virtual key’s permission. Figure 16: Configure HSM policy

3.2  Key Scan

Users can configure multiple Fortanix DSM groups to map to the same HSM (slot) and manage keys from these groups using the Key Scan options that allow them to do one of the following:

• Only manage the keys that were created from within the respective Fortanix DSM group.
• Manage all the keys in the HSM (slot).

Figure 17: Key scan options

• Applicable for all keys in HSM slot: If this option is selected, when the keys are scanned from HSM using the SYNC KEYS button:
  • For each new key created in the configured HSM (slot) without using Fortanix DSM, a new virtual key will be imported in the corresponding Fortanix DSM groups.
• Applicable only to keys created from Self-Defending KMS group in HSM slot : If this option is selected, when the keys are scanned from HSM using the SYNC KEYS button:
  • For each new key created in the configured HSM (slot) without using Fortanix DSM, NO NEW virtual key will be imported in the corresponding Fortanix DSM group. However, if the key scan was performed before modifying the default Key Scan settings (that is, with the Key Scan option Applicable for all keys in HSM slot), then all keys that were imported as virtual keys in the Fortanix DSM group from the HSM (slot) will also be managed by the Fortanix DSM group and synced to the HSM (slot).

4.0 Fortanix Data Security Manager HSM Gateway Security Objects

4.1 Create a key in HSM Group

You can either generate a key or import a key in a configured HSM.

• Generate a key: This action will generate the configured key type in the configured HSM directly and will be represented as a virtual key in the corresponding HSM group.
• Import a key: This action will import the key in the configured HSM directly and will be represented as a virtual key in the corresponding HSM group.

4.1.1 Generate a Key in HSM

In your Fortanix DSM console, follow the process below to create/import a key:

1. Click the Security Objects tab.
2. Click  to create a new Security Object.
3. In the Add New Security Object form (Figure 18) enter a name for the Security Object (Key).
4. Select the This is an HSM/external KMS object check box (Figure 18). This will show the HSM configured groups in the Assign to a group list.
5. Select the HSM group to which you want to assign the key.
   Figure 18: Select HSM group
6. Click GENERATE to generate a new key.
7. Select the key type for the new HSM key.
   NOTE

   The allowed key types for an HSM key are AES, DES3, RSA, DES, and EC. These key types can further be restricted by setting a crypto policy for the account or group. For more details about the crypto policy, please refer to the article https://support.fortanix.com/hc/en-us/articles/360042064051-User-s-Guide-Crypto-Policy.
8. Enter the Key size and select the permitted key operations under Key operations permitted
9. Click GENERATE to generate the key in HSM.
10. The new key will be added to the Security Objects table.
    TIP

    • You can also access the new key from the Group detailed view from the SECURITY OBJECTS tab (Figure 19).
    • You can also add a new key from the Group detailed view from the SECURITY OBJECTS tab (Figure 19), click ADD SECURITY OBJECT button and follow the steps described in section Generate a Key in HSM.

    
    Figure 19: View/Add HSM security objects

4.1.2 Import a Key into HSM

In your Fortanix DSM console, follow the process below to import a key:

1. Repeat steps 1- step 5 from section 4.1.1.
2. Click IMPORT to import a new key in HSM.
   Figure 20: Import new key
3. Select the key type for the new HSM key.
   NOTE

   The allowed key types for an HSM key are AES, DES3, RSA, DES, and EC. These key types can further be restricted by setting a crypto policy for the account or group. For more details about the crypto policy, please refer to the article https://support.fortanix.com/hc/en-us/articles/360042064051-User-s-Guide-Crypto-Policy.
4. Upload the key file or paste the contents of the key in the textbox provided for Place value here or import from file.
5. Select the key operations permitted.
6. Click IMPORT to import the key into HSM.
7. The new key will be added to the Security Objects table.

4.1.3 Key Permissions in HSM Group

When a new key is created in an HSM group, all permissions configured during the create key operation will be applied to the new key in the configured HSM. However, any update on the permissions on any existing key in the HSM will only be applied to its virtual key representation in the Corresponding HSM group.

4.2 Deactivate a Key in HSM Group

When you deactivate an HSM key in Fortanix DSM, the action will deactivate the virtual key in Fortanix DSM only.

To deactivate a virtual key in Fortanix DSM:

1. Select the HSM key to deactivate.
2. In the security object detailed view, scroll down, and click the DEACTIVATE button.
   Figure 21: Deactivate Key

4.3 Delete a Key in HSM Group

When you delete a virtual key from an HSM group in Fortanix DSM, the action will either only delete the virtual key in Fortanix DSM, or it will delete both the virtual key and the actual key in the configured HSM depending on the HSM Key Management Policy configuration. For more details refer to Section 3.0. To delete a virtual key:

To delete a virtual key:

1. Select the HSM key to delete.
2. In the security object detailed view, scroll down and click the DELETE SECURITY OBJECT button.
   Figure 22: Delete HSM Key

4.4 Rotate a Key in HSM Group

When you rotate a key in an HSM group, the action will only rotate the key inside the HSM by generating another key which will be generated again within the configured HSM.

To rotate a key in HSM:

1. Select the HSM key to rotate.
2. In the security object detailed view, click the ROTATE KEY button.
   Figure 23: Rotate Key
3. A new rotated key is now generated.
   Figure 24: Rotated Key

5.0 Running HSM Gateway

The HSM (Hardware Security Module) Gateway binary needs to be run on a host/server and it will act as a client to the desired HSM.

5.1 Prerequisites

1. The HSM vendor's PKCS11 library should be installed on this server.
2. HSM Gateway requires a P12 file that contains a private key and certificate that will be used for TLS. Please have a key and certificate ready. You may also use a self-signed certificate for this.
3. HSM Gateway by default listens on port 4442. You can change the port as necessary. Please make sure the port you use for HSM Management Gateway (HMG) is open.

5.2 Installing HSM Gateway

HSM gateway is available in the following package formats:

• Debian
• RPM

After downloading the appropriate package for your platform, use the following steps to install it:

1. To start HSM Gateway, run the following command:

• Debian Package:
  

  sudo dpkg –i <HSM Gateway Package Name>

    For example:
  

  sudo dpkg –i fortanix-hsm-gateway-3.20.1917-amd64.deb

• RPM Package:
  

  sudo rpm –i <HSM Gateway Package Name>

    For example:
  

  sudo rpm –i fortanix-hsm-gateway-3.20.1917-0.x86_64.rpm

5.3 Configuring HSM Gateway

Before running HSM Gateway, it needs to be configured to point to the appropriate TLS certificate file and HSM’s PKCS11 library file.

1. A p12 file containing TLS private key and certificate is required to start HMG. You can generate a self-signed certificate and create a P12 file as follows:

   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
   openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem

   By default, HSM gateway expects this P12 file to be present at “/etc/fortanix/pki/cert.p12 ”. Either copy your P12 file to this location or change the location of this file as explained in the next step.
   WARNING

   The P12 file does not require a password to be set. If you set a password on this file, then the HSM gateway daemon will crash upon start-up.
2. Edit the configuration file “/etc/default/ftx-hmg” to update the following lines:
   • CERT_FILE: If you are not using the default path for the certificate P12 file, then update this value.
   • HMG_LISTEN_PORT: If you want to use a port different from the default port 4442 then update this value.
   • CA_FILE: If you want to run the service in mutual authentication mode then provide a CA file in this option in PEM format to authenticate the client certificate.
     NOTE

     The client should also be set up in mutual authentication mode if this option is set, otherwise, the connection will fail.
   • PKCS11_LIB_PATH: Update this value to point to your HSM’s PKCS11 library file.
     • The default location of PKCS11 library for nCipher HSMs is: /opt/nfast/toolkits/pkcs11/libcknfast.so
     • The default location of PKCS11 library for Luna HSMs is: /usr/safenet/lunaclient/lib/libCryptoki2_64.so
   For example, you would set the value of this variable as follows for Luna HSMs:
   PKCS11_LIB_PATH=/usr/safenet/lunaclient/lib/libCryptoki2_64.so

5.4 Running HSM Gateway

1. To start HSM Gateway, run the following commands:

   sudo systemctl enable ftx-hmg
   sudo systemctl start ftx-hmg

2. To check the status of HSM Gateway service, run the following command:

   systemctl status ftx-hmg

3. In case of errors and troubleshooting, you can look at the logs by running the following command:
   

   journalctl -u ftx-hmg

6.0 Configuring External Load Balancer for Health Check

An external load balancer can be configured optionally, to evenly distribute traffic across multiple HSM Gateways to ensure high availability. The external load balancer calls HSM Gateway’s health check API. A health check detects the following:

• The HSM Gateway is up and running.
• The HSM Gateway and HSM connectivity are not down.
• The HSM itself is able to service PKCS#11 calls.

To point the load balancer to the HSM Gateway, the HSM group created in Section 2.1 to Section 2.4 is configured with the load balancer’s IP address.

GET http://HSM_GATEWAY_IP:4441/health

GET https://HSM_GATEWAY_IP:4440/health

The HSM is considered as healthy only if every Slot is healthy. If a request on a Slot fails with a “server-side error” like CKR_DEVICE_ERROR, as opposed to a “client-side error” like CKR_ARGUMENTS_BAD, then the Slot is marked as unhealthy. ​

The load balancer treats the node as healthy only when it receives the status code 204(No Content). If unhealthy, it will return the status code 500 Internal Server Error.  This allows the load balancer to route traffic away from unhealthy gateways/HSMs.

7.0 HSMs Tested With Fortanix HSM Gateway