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

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. Select the HSM type:

   1. Click the drop-down to select the HSM Type. Currently, Fortanix DSM supports connecting to nCipher HSM, SafeNet Luna, and AWS CloudHSM.

   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. 

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

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

      • 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

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.

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.

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 2 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/KMS Tab

The HSM/KMS tab shows the details of the HSM that was added such as, HSM type which is “nCipher HSM” in this case. You can also test the connection using the TEST CONNECTION button.

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.

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.

2.9 Security Objects Table View

After you add new HSM virtual 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.

2.10 Security Objects Detailed View

Click a security object from the Security Object table to go to the 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 whether the group is “Connected” or “Not Connected”.

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. 

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

3.0 HSM Key Management Policy

The HSM 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 not to apply the virtual key changes to the corresponding HSM. 

3.1 Edit 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: 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. 
    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. 

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

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

• Applicable for all keys in HSM: 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 Data Security Manager 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 DSM HSM Gateway Security Objects

4.1 Create a key in HSM Group

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.

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 enter a name for the Security Object (Key).

4. Select the This is an HSM/external KMS object check box. 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. 

6. Select GENERATE as the method of key creation.

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 users-guide-account-cryptographic-policy.

   • Enter the Key size and select the permitted key operations under Key operations permitted section.

8. Click GENERATE to generate the key in HSM.

9. 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 button and follow the steps described in Section Generate a Key in HSM.

4.1.2 Import a Key into HSM

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

1. Repeat step 1- step 5 from Setion 4.1.1.

2. Click IMPORT to import a new key in HSM. 

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 users-guide-account-cryptographic-policy.

   • Upload the key file or paste the contents of the key in the textbox provided for Place value here or import from file.

4. Select the key operations permitted.

5. Click IMPORT to import the key into HSM.

6. The new key will be added to the Security Objects table.

4.1.3 Copy a Key in HSM

This feature has the following advantages:

• It maintains a single source key while copying/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

• Date of Copy

• Target copy group name

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 key and click the Copy Key button on the far right of the screen.

2. In the COPY KEY window, update the name of the key if required by clicking the pencil   icon. 

3. Copy the new key to a group(s) from the GROUP section. To filter only HSM/External KMS groups, select Import key to HSM/External KMS option. 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 crypto policy for the account or group. For more details about the crypto policy, please refer to the article: docs/users-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. Add Deactivation Date: 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.

7. If there is a Quorum 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.

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

4.1.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 on the permissions on any existing key in the HSM group will either be applied to its virtual key representation only or it will also be applied to both the virtual key representation and the actual key in the configured HSM depending on the HSM Key Management Policy configuration. For more details refer to Section 5.0.

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.  

   

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

   

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

4.4.1 Rotate a HSM Native Key with Another Native Key

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

When you rotate a virtual key in a HSM group, the action will only rotate the key inside the HSM by generating another key 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.

3. In the Key Rotation window, click the ROTATE KEY button to rotate the virtual key.

A new rotated key is now generated.

4.4.2 Rotate Linked Key - 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 as the native key, then the user is given the option to select the linked keys for key rotation.

1. Click ROTATE KEY in the detailed view of a Fortanix DSM virtual key.

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

3. Select the linked keys that must be rotated along with the Fortanix DSM virtual key

4. Click ROTATE KEY to rotate the key.

5. The virtual key will now appear as a key link in the KEY LINKS tab in the detailed view of the rotated virtual key.

4.4.3 Rotate Linked Keys - In DSM Regular 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 the user is given the option to select the linked keys for key rotation. If these linked keys belong to an HSM group, then rotating the linked keys results in rotating the keys in HSM as well by generating new keys within the configured HSM.

1. Click ROTATE KEY in the detailed view of a Fortanix DSM Source Key.

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

3. Select the HSM virtual keys that must be rotated along with the Fortanix DSM source key.

4. Click ROTATE KEY to rotate the key.

5. The source key will now appear as a key link in the KEY LINKS tab in the detailed view of the 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 Install 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 

  For example:

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

• RPM Package:

  sudo rpm –i 

  For example:

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

5.3 Configure 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 Run 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 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 2.1 to Section 2.4 is configured with the load balancer’s IP address.

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

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