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 often this is not the case.

This article describes how to add a new HSM Gateway to the Fortanix-Data-Security-Manager (DSM).

2.0 HSM Gateway Architecture

The Fortanix HSM Gateway solution requires that the customer applications use one of the Fortanix 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.

3.0 Create Fortanix DSM HSM Group

Perform the following steps to create a group for HSM connection in Fortanix DSM:

1. Click the Groups menu item in the DSM left navigation panel and click the + button on the Groups page to add a new group.

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

   • Title: Enter a title for your group.

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

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

   

4. In the Choose Type field, click the drop down and select the HSM Type.

   Currently, Fortanix DSM supports connecting to Entrust nShiled HSM, Thales Luna HSM, and AWS CloudHSM.

5. Based on the HSM type selected in Step 4, enter the connection details to connect with your HSM.

   • HMG IP-address: Enter the IP address or hostname of the server running the HSM Gateway

   • Port: Enter the port number used by the HSM instance. The default port is 4442. You can override this by specifying a different port number.

   • Slot: HSM devices support multiple PKCS#11 slots, each identified by a numeric Slot ID. Retrieve the Slot ID using the pkcs11-tool, which is available as a separate download from the internet.

     For example, run the following command to get the Slot ID for Entrust nShield HSM:

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

     This command lists all the available slot IDs in hexadecimal format. Fortanix DSM requires the Slot ID in decimal format so users must manually convert the hexadecimal value to decimal.

     The following is the example output of the command:

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

   • PIN: Enter the Personal Identification Number (PIN) associated with the HSM slot. Use the pkcs11-tool to initialize (--init-pin) or change (--change-pin) the PIN using the PKCS#11 API. These operations require security officer privileges. For more information, refer to pkcs11-tool(1) - Linux man page.

6. Add TLS configuration (optional). For more details, refer to Section 3.1: Add TLS Configuration (Optional).

7. Click TEST CONNECTION to test your HSM connection. If Fortanix DSM can 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 .

8. Click SAVE to create the new group.

3.1 Add TLS Configuration (Optional)

In the TLS configuration section, click + ADD AUTHENTICATION CERTIFICATE to add a certificate for authenticating your HSM.

In the CONFIGURE CUSTOM CERTIFICATE dialog box, do the following:

1. Select the Validate host check box to ensure that the HSM server hostname mentioned above matches the hostname specified in the server certificate.

2. There are two certificate options to select from:

   • Global Root CA: Select this option if you are using a certificate signed by a well-known public CA. By default, every HSM Group is configured with a Global Root CA Certificate.

   • Custom CA Certificate: Select this option, if your organization uses a self-signed certificate issued by an internal Certificate Authority (CA). When Fortanix DSM, acting as a client, connects to the HSM server and receives the server’s certificate, it validates the certificate using the uploaded custom CA certificate. You can either upload the certificate file or copy the contents of the certificate in the textbox provided.

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

3. Click SAVE.

3.2 HSM/KMS Tab

The HSM/KMS tab displays the connection details of the configured HSM, such as the HSM type. You can view and edit these connection settings directly from this tab. Fortanix DSM automatically tests the HSM connection upon saving any changes and displays the connection status accordingly.

The PIN used to connect to the HSM is securely stored and not displayed to the user. You are not required to re-enter the PIN to test the connection.

3.2.1 Add Connection

Perform the following steps to add additional connections for nodes that connect to the same HSM for high availability:

1. Navigate to the HSM group as created in Section 3.0: Create a Group for HSM Connection.

2. In the HSM/KMS tab, click ADD CONNECTION.

3. Enter the HMG IP-address, Slot, and PIN for the new connection as explained in Section 3.0: Create a Group for HSM Connection. You can edit these details at any time.

4. Click TEST CONNECTION to verify connectivity between Fortanix DSM and the new node.

5. After you add a new node, you can reorder the nodes to set the priority of High Availability (HA) instances from the drop down list:

   • Move to top

   • Move up

   • Move down

   • Move to bottom

   • Delete Connection

   Fortanix DSM UI displays the backend priority number for each HSM node when multiple nodes are configured.

   NOTE

   If the backend priority number displays as NaN (Not a Number) for any existing HSM configuration, reorder the connections using the overlay menu. The correct priority number will then appear for the node.

6. Click SAVE CHANGES.

3.3 Sync Keys

Perform the following steps to sync the HSM keys:

1. Go to the HSM group detailed view.

2. Click the HSM/KMS tab.

3. Click SYNC KEYS to import the new virtual keys.

Fortanix DSM will then connect to HSM, fetch all available keys, and store them as virtual keys.

NOTE

• Clicking SYNC KEYS only returns the keys from the HSM that are not present in Fortanix DSM, that is, every click appends only the new keys to Fortanix DSM.

• For Entrust nShield HSM, if you are using existing keys on your HSMs then you need to make sure that they must be "pkcs11" type keys. Other keys need to be retargeted to pkcs11 before they can be consumed using HSM Gateway. Use the following command to convert the HSM keys to “pkcs11” type keys.

  generatekey --retarget pkcs11 from-application={original_app} from-ident={key_ident}

3.4 Security Objects Table View

After adding new HSM virtual keys, navigate to the Security Objects menu item to view all the security objects from all the groups (HSM and non-HSM).

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

3.5 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 external Managed HSM group.

3.6 Attributes/Tags Tab

The tab displays the standard PKCS#11, CNG, and Custom attributes associated with the security object.

As part of the key sync process, Fortanix DSM automatically retrieves the CKA_ID and CKA_LABEL PKCS#11 attributes from each key in the external HSM and maps them as PKCS#11 attributes to the corresponding virtual key in Fortanix DSM. These attribute values are unique for every key in the external HSM.

NOTE

The CKA_ID and CKA_LABEL attributes are editable within Fortanix DSM. If these values are modified manually, you must re-sync the keys in the HSM group to restore the original attribute values from the external HSM.

3.7 User’s View

Navigate to the Users menu item in the DSM left navigation bar and click the user that says “You” on the Users page to view the user’s detailed view.

The detailed view shows all the groups the user belongs to and indicates which groups are mapped to HSM, displaying their status as "connected" or "not connected."

4.0 HSM Key Management Policy

The HSM Key Management Policy can be configured in the detailed view of an HSM group under the INFO tab. This policy manages virtual key changes in Fortanix DSM to the corresponding keys in the configured HSM. The users can choose whether or not to apply or not apply changes named to virtual keys such as destroying security objects, removing the private component of asymmetric keys, or modifying key permissions changes to the corresponding keys in the HSM. By default, the policy is set to not apply virtual key changes to the corresponding HSM.

4.1 Edit HSM Key Management Policy

• The default setting for the HSM Key Management policy is Do not apply changes performed on virtual keys in Data Security Manager to corresponding keys in HSM. The following are the key behaviours:

  • When an existing virtual key is updated or deleted: 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: A corresponding key is immediately created in the configured HSM slot with the same metadata and key permissions as defined in the virtual key.

  • Permission changes: If keys are scanned from the HSM and differences are found between the virtual key’s permissions and the HSM key’s permissions, the HSM key’s permissions will not overwrite the virtual key’s permissions.

    For example, if the “encrypt” permission is removed from a virtual key in an HSM group, and during a key scan using SYNC KEYS the corresponding HSM key still has the “encrypt” permission, the scan will not overwrite the virtual key’s permissions.

• To edit the default policy, click EDIT POLICY and select the Apply changes performed on virtual keys in Data Security Manager to corresponding keys in HSM radio button. The following are the key behaviours:

  • When an existing virtual key is updated or deleted: Changes will be applied immediately to the corresponding keys in HSM.

  • When a new virtual key is created: A corresponding key is immediately created in the configured HSM slot with the same metadata and key permissions as defined in the virtual key.

  • Permission changes: If keys are scanned from the HSM and differences are found between the virtual key’s permissions and the HSM key’s permissions, the HSM key’s permissions will not overwrite the 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. If the “encrypt” permission is removed from a virtual key in an HSM group, and the change is immediately applied to the corresponding HSM key. Later, if the “encrypt” permission is manually added back to the key in the HSM and a key scan is performed using SYNC KEYS, the scan will not overwrite the virtual key’s permissions.

4.2 Key Scan

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

• Manage only the keys that were created from within the respective Fortanix DSM group.

• Manage all the keys in the HSM (slot).

NOTE

When a user configures a Fortanix DSM group with on e of the key scan options and saves the setting, it cannot be modified. They can only create a new group with a new configuration.

• Applicable for all keys in HSM: If this option is selected, when the keys are scanned from HSM using SYNC KEYS:

  • For each new key created in the configured HSM (slot) outside of Fortanix DSM, a corresponding virtual key will be imported into the relevant Fortanix DSM groups.

• Applicable only to keys created from Data Security Manager group in HSM slot: If this option is selected, when the keys are scanned from the HSM using SYNC KEYS:

  • Any new key created directly in the configured HSM (slot) outside of Fortanix DSM will not be imported as a virtual key into the corresponding Fortanix DSM group. However, if the key scan was performed before modifying the default Key Scan settings (that is, when the option Applicable for all keys in HSM slot was selected), then all previously imported keys will continue to be managed by the Fortanix DSM group and remain synced with the HSM slot.

5.0 Create Fortanix DSM HSM Security Objects

You can either generate a key, import, or copy 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.

• Copy a key: This action will copy a key from a standard Fortanix DSM or HSM group to another HSM group.

5.1 Generate a Key in HSM

Perform the following steps to generate a key in HSM:

1. Click the Security Objects menu item in the DSM left navigation panel and click the + button on the Security Objects page to add a new key.

2. On the Add New Security Object page, do the following:

   • Security Object name: Enter a name for the security object.

   • Select the This is an HSM/external KMS object check box to filter the groups to show only HSM groups in the Select group list.

   • In the HSM group list, select the HSM group into which the keys will be generated.

   • Select GENERATE to initiate the generate key in the HSM workflow.

   • In the Choose a type section, 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 Cryptographic policy for the account or group. For more details about the Cryptographic policy, refer to User's Guide: Account Cryptographic Policy.

   • Enter the Key size.

   • In the Key operations permitted section, select the permitted key operations.

   • In the Custom Attributes section, click ADD ATTRIBUTE to add any attributes if required.

3. Click GENERATE to generate the key in HSM.

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.

• You can also add a new key from the Group detailed view from the SECURITY OBJECTS tab, click ADD SECURITY OBJECT and follow the steps described in the section.

5.2 Import a Key into HSM

Perform the following steps to import a key in HSM:

1. Click the Security Objects menu item in the DSM left navigation panel and click the + button on the Security Objects page to add a new key.

2. On the Add New Security Object page, do the following:

   • Security Object name: Enter a name for the security object.

   • Select the This is an HSM/external KMS object check box to filter the groups to show only HSM groups in the Select group list.

   • In the HSM group list, select the HSM group into which the keys will be generated.

   • Select IMPORT to initiate the import key in the HSM workflow.

   • In the Choose a type section, 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 Cryptographic policy for the account or group. For more details about the Cryptographic policy, refer to User's Guide: Account Cryptographic Policy.

   • In the Place value here or import from file section, click UPLOAD A FILE to upload the key file or paste the contents of the key in the provided textbox.

   • In the Key operations permitted section, select the permitted key operations.

   • In the Custom Attributes section, click ADD ATTRIBUTE to add any attributes if required.

3. Click IMPORT to import the key in HSM.

The new key will be added to the security objects table.

5.3 Copy a Key in HSM

This feature has the following advantages:

• It maintains a single source key while copying or importing that key into various Fortanix DSM groups where applications may need to use a single key to meet business objectives.

• It maintains a link of various copies of the same key material to the source key for ability to name, and rotate keys everywhere all at once, as well as audit and tracking purposes.

The following actions will happen as part of the copy key operation:

• A new key will be created in the target group: The new key will have the same key material as the original key.

• The Source key links to the copied keys: A link will be maintained between all copied keys and the source key.

The Source key will also have basic metadata-based information about the linked keys such as:

• Copied by <user-name/app id>

• Date of Copy <time stamp>

• Target copy group name

NOTE

The name of the copied key is suggested automatically to the user as [original key name]_[copy1,2,...], but can be replaced with an alternative unique name.

Perform the following steps to copy a key from a regular Fortanix DSM group to an HSM group or vice versa:

1. Go to the detailed view of a security object and click COPY KEY on the right of the screen.

   

2. In the COPY KEY window, you may update the name of the key by clicking on the pencil icon.

   

3. Copy the new key to a group(s) from the Group section. Select the Import key to HSM/External KMS option to filter only HSM/External KMS groups. Select the group for the new key into which the copied key should be imported.

   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 Cryptographic policy for the account or group. For more details about the Cryptographic policy, refer to User's Guide: Account Cryptographic Policy.

   • The key to be copied must have the Export permission enabled or the copy key operation will fail.

4. Click EDIT PERMISSIONS if you want to modify the permissions of the key.

   

5. The Deactivation Date of the security object can be set to 'Never' or to a specified time in the future. To specify the deactivation date, click EDIT.

6. Click CREATE COPY to create a copy of the key.

   NOTE

   If there is a Quorum approval policy configured in the source group that contains the original key, then a quorum approval request is created. Only after the request is approved the copy key operation will be successful.

7. The source key will now appear as a key link in the KEY LINKS tab in the detailed view of the copied key.

   

5.4 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 to the permissions on any existing key in the HSM group will either apply only to its virtual key representation only or to 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 5.0: Create Fortanix DSM HSM Security Object.

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

Perform the following steps to deactivate a virtual key in Fortanix DSM:

1. Go to the detailed view of a HSM key that you want to deactivate.

2. In the detailed view of the key, scroll to the bottom of the screen, and click DEACTIVATE NOW.

   

3. On the Deactivation confirmation dialog box, select the check box to acknowledge the warning before deactivating the security object. Additionally, select The key has been compromised check box, if the key is compromised.

4. Click SAVE.

   

5.6 Delete a Key in HSM Group

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

Perform the following steps to delete a virtual key:

1. Go to the detailed view of the security object, scroll to the bottom of the screen and click DELETE KEY.

   

   Alternatively, you can select the key you want to delete from the security objects table, and then click DELETE SELECTED from the top navigation bar.

   

2. In the Delete key confirmation dialog box, select the check box to acknowledge the warning before deleting the security object.

3. Click PROCEED.

6.0 Rotate a Key in HSM Group

The following section explains the key rotation in HSM group. A key is rotated when you want to retire an encryption key and replace that old key by generating a new cryptographic key.

6.1 Rotating HSM Native Key with Another Native

*Native key is one where the key material was generated by HSM.

When you rotate a virtual key in an HSM group, the action will rotate the key inside the HSM by generating another key within the configured HSM in a nested way by moving the key alias from the old key to the new key.

Perform the following steps to rotate a key in HSM:

1. Navigate to the Security Objects menu item in the DSM left navigation panel to go to the detailed view of an HSM virtual key and click ROTATE KEY.

2. In the KEY ROTATION window, the Generate new key radio button is selected by default.

3. Click ROTATE KEY to rotate a virtual key.

4. On the next screen, select both the check boxes to confirm your understanding about the action.

5. Click PROCEED.

6.2 Rotating HSM Keys – in HSM Group

If the HSM native key has linked keys that are copies of the Fortanix DSM native key with the same key material, the user is given the option to select these linked keys for key rotation.

Perform the following steps to rotate a virtual key with Fortanix DSM backed key:

1. Navigate to the Security Objects menu item in the DSM left navigation panel to go to the detailed view of an Fortanix DSM virtual key and click ROTATE KEY.

2. In the Key Rotation window, select the Rotate linked key check box.

3. Select the HSM virtual keys to rotate with the Fortanix DSM source key and click ROTATE KEY.

4. On the Rotate key window, select both the check boxes to confirm your understanding about the action. Click PROCEED.

5. After the keys are rotated, click OK.

6.3 Rotating HSM Keys – in Fortanix DSM Group

When a key is rotated that belongs to a Fortanix DSM source group and has linked keys that are copies of the Fortanix DSM source key with the same key material as the source key, then you are given the option to select the linked keys for the key rotation. If these linked keys are part of an HSM group, rotating the linked keys also rotates the keys in HSM by making nested copies of the keys in the configured HSM.

Perform the following steps to rotate a key in HSM:

1. Navigate to the Security Objects menu item in the DSM left navigation panel to go to the detailed view of a Fortanix DSM source key and click ROTATE KEY.

2. In the KEY ROTATION window, select the Rotate linked keys check box. For more information on the key rotation policy, refer to the User's Guide: Fortanix Data Security Manager Key Lifecycle Management.

3. Select the HSM virtual keys to rotate with the Fortanix DSM source key and click ROTATE KEY.

4. On the Rotate key window, select both the check boxes to confirm your understanding about the action. Click PROCEED.

5. After the keys are rotated, click OK.

7.0 Run HSM Gateway

The HSM Gateway binary must be executed on a designated host or server. This instance will serve as a client that interfaces with the target HSM.

7.1 Prerequisites

Ensure the following:

• The HSM vendor’s PKCS#11 library is installed on the server where the gateway will run.

• The HSM Gateway requires a PKCS#12 file containing a private key and corresponding certificate for establishing TLS communication. This can be a valid CA-signed certificate or a self-signed certificate.

• By default, the HSM Gateway listens on port 4442. This port can be modified if needed. Ensure that the selected port is open and accessible for HSM Management Gateway (HMG) operations.

7.2 Install HSM Gateway

The HSM Gateway is available in the two package formats: Debian (.deb) and RPM (.rpm).

Run the following commands to install the HSM Gateway based on your system’s package format:

• For Debian package:

  sudo dpkg –i <HSM Gateway Package Name>

  For example:

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

• For RPM package:

  sudo rpm –i <HSM Gateway Package Name>

  For example:

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

7.3 Configure HSM Gateway

Before launching the HSM Gateway, it must be configured to reference the correct TLS certificate file and the HSM’s PKCS#11 library file.

1. A PKCS#12 file containing the TLS private key and certificate is required to start the HSM Gateway. Run the following command to generate a self-signed certificate and create a PKCS#12 file:

   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, the HSM Gateway expects the PKCS#12 file to be located at /etc/fortanix/pki/cert.p12. You can either place your PKCS#12 file in this location or update the configuration to reference a different path, as explained in the next step.

   WARNING

   The PKCS#12 file should not have a password. If a password is set, the HSM gateway will fail to start.

2. Modify /etc/default/ftx-hmg configuration file to set the following values:

   • CERT_FILE: Update this value with the correct path, if PKCS#12 certificate file is stored in a different location instead of the default location.

   • HMG_LISTEN_PORT: Update this value accordingly, if using a port other than the default (4442).

   • 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 PKCS#11 library file.

     For example:

     • For Entrust nShield HSMs, the default PKCS#11 library location is: /opt/nfast/toolkits/pkcs11/libcknfast.so

     • For Thales Luna HSMs, the default PKCS#11 library location is: /usr/safenet/lunaclient/lib/libCryptoki2_64.so

     • For AWS CloudHSMs, the default PKCS#11 library location is: /usr/safenet/lunaclient/lib/libCryptoki2_64.so

     For Luna HSMs, the configuration may be as follows:

     PKCS11_LIB_PATH=/usr/safenet/lunaclient/lib/libCryptoki2_64.so

7.4 Launch HSM Gateway

Perform the followings steps to launch the HSM Gateway:

1. Run the following command to start HSM Gateway:

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

2. Run the following command to check the status of HSM Gateway service:

   systemctl status ftx-hmg

3. Run the following command to view the HSM Gateway logs for errors and troubleshooting:

   journalctl -u ftx-hmg

8.0 Configure 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 can service PKCS#11 calls.

To point the load balancer to the HSM Gateway, the HSM group created in Section 3.0: Create Fortanix DSM HSM Group to Section 3.2: HSM/KMS Tab is configured with the load balancer’s IP address.

8.1 HSM Health Check Mechanism

HSM Gateway listens on two ports, that, is port 4441 (HTTP) and 4440 (HTTPS). The load balancers perform a health check to detect the health of the HSM Gateways using a GET request as follows:

GET http://HSM_GATEWAY_IP:4441/health

or

GET https://HSM_GATEWAY_IP:4440/health

NOTE

For the external load balancer-HSM Gateway configuration to work, the user needs to ensure that each HSM Gateway behind the load balancer uses the same PIN and Slot.

The HSM is considered as healthy only if every Slot is healthy. If a request on a Slot fails with a “server-side error” such as CKR_DEVICE_ERROR, as opposed to a “client-side error” such as 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.

9.0 HSM Tested with Fortanix HSM Gateway