--- title: "HSM Gateway" slug: "fortanix-dsm-hsm-gateway" updated: 2026-08-21T07:18:38Z published: 2026-08-21T07:18:38Z canonical: "support.fortanix.com/fortanix-dsm-hsm-gateway" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.fortanix.com/llms.txt > Use this file to discover all available pages before exploring further. # HSM Gateway ## 1.0 Introduction This article describes how to add a new HSM Gateway to the Fortanix-Data-Security-Manager (DSM). 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. ## 2.0 HSM Gateway Architecture ![Architecture-HSM.png](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/14606487075092.png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D) **Figure 1: 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. In the DSM left navigation panel, click the**Groups** menu item, and then click **ADD GROUP** to create a new group. ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Add-Group(78).png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D) **Figure 2: Add group** 2. On the **Adding new group** page: 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** to select the HSM type, so that Fortanix DSM can connect to it. ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/image-1769075245419.png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D) **Figure 3: Add new custom account role form** 4. In the **Choose Type** field, click the drop down and select the HSM Type. Currently, Fortanix DSM supports connecting to **Entrust nShield 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**: ```bash 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: ```bash 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*](https://linux.die.net/man/1/pkcs11-tool)*.* 6. Add TLS configuration (optional). *For more information, refer to* [*Section 3.1: Add TLS Configuration (Optional)*](/v1/docs/fortanix-dsm-hsm-gateway#31-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 ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/360082238652(10).png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D). Otherwise, it shows the status as “**Not Connected**” with a yellow warning sign ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Screenshot (1811)(10).png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D). 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: 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: > [!NOTE] > NOTE > > The client should also be set up in mutual authentication mode if this option is set, otherwise the connection will fail. - **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. 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*](/v1/docs/users-guide-hsm-gateway#30-create-fortanix-dsm-hsm-group). 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*](/v1/docs/users-guide-hsm-gateway#30-create-fortanix-dsm-hsm-group). 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: Fortanix DSM UI displays the backend priority number for each HSM node when multiple nodes are configured. > [!NOTE] > 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. - Move to top - Move up - Move down - Move to bottom - Delete Connection 6. Click **SAVE CHANGES**. ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/HSM_Add_Connections(2).png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D) **Figure 4: Add connections** ### 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] > 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. > > ```bash > 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 ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Screenshot (1812)(17).png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D). 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 ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Screenshot (1812)(18).png?sv=2026-02-06&spr=https&st=2026-10-27T13%3A25%3A10Z&se=2026-10-27T14%3A25%3A10Z&sr=c&sp=r&sig=Gf6dxa8JkwV1%2F9G8S5WuOwjJrbsYjnBtzjh%2FbO8drOE%3D) 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] > 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 behaviors: - 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 **Apply changes performed on virtual keys in Data Security Manager to corresponding keys in HSM**. The following are the key behaviors: - 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] > 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. In the DSM left navigation panel, click the **Security Objects** menu item, and then click **ADD SECURITY OBJECT** to create a new security object. 2. On the **Add New Security Object** page: 1. **Security Object name**: Enter a name for the security object. 2. 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. 3. In the HSM group list, select the HSM group into which the keys will be generated. 4. Select **GENERATE** to initiate the generate key in the HSM workflow. 5. In the **Choose a type** section, select the key type for the new HSM key. > [!NOTE] > 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 information about the Cryptographic policy, refer to* [*Account Cryptographic Policy*](https://support.fortanix.com/v1/docs/users-guide-account-cryptographic-policy)*.* 6. Enter the **Key size**. 7. In the **Key operations permitted** section, select the permitted key operations. 8. 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] > 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. In the DSM left navigation panel, click the **Security Objects** menu item, and then click **ADD SECURITY OBJECT** to create a new security object. 2. On the **Add New Security Object** page: 1. **Security Object name**: Enter a name for the security object. 2. 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. 3. In the HSM group list, select the HSM group into which the keys will be generated. 4. Select **IMPORT** to initiate the import key in the HSM workflow. 5. In the **Choose a type** section, select the key type for the new HSM key. > [!NOTE] > 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 information the Cryptographic policy, refer to* [*Account Cryptographic Policy*](https://support.fortanix.com/v1/docs/users-guide-account-cryptographic-policy) *and* [*Group Cryptographic Policy*](/v1/docs/users-guide-group-cryptographic-policy)*.* 6. 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. 7. In the **Key operations permitted** section, select the permitted key operations. 8. 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 - Date of Copy