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
- In the Fortanix DSM Groups
page, click the
button to create a new group.
- In the Add new group form,
- Enter a title and description for your group.
- 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
-
- 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 - Enter the connection details to connect with your HSM.
- HMG IP-address: This is the IP address or hostname of the server running the HSM gateway.
- 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.
- 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
Available slots:
Slot 0 (0x1d622495): XXXX-XXXX-XXXX Rt1
token state: uninitialized
Slot 1 (0x1d622496): XXXX-XXXX-XXXX Rt1 slot 0
(empty) - 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
- 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.
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
orCommon Name (CN)
as the hostname that the server certificate is coming from.
- Click the drop-down to select the HSM Type. Currently, Fortanix DSM supports connecting to nCipher HSM, SafeNet Luna, and AWS CloudHSM.
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.
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
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:
- Click the Security Objects
tab.
- Click
to create a new Security Object.
- In the Add New Security Object form (Figure 18) enter a name for the Security Object (Key).
- 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.
- Select the HSM group to which you want to assign the key.
Figure 18: Select HSM group - Click GENERATE to generate a new key.
- Select the key type for the new HSM key.
- Enter the Key size and select the permitted key operations under Key operations permitted
- Click GENERATE to generate the key in HSM.
- The new key will be added to the Security Objects table.
4.1.2 Import a Key into HSM
In your Fortanix DSM console, follow the process below to import a key:
- Repeat steps 1- step 5 from section 4.1.1.
- Click IMPORT to import a new key in HSM.
Figure 20: Import new key - Select the key type for the new HSM key.
- Upload the key file or paste the contents of the key in the textbox provided for Place value here or import from file.
- Select the key operations permitted.
- Click IMPORT to import the key into HSM.
- 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:
- Select the HSM key to deactivate.
- 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:
- Select the HSM key to delete.
- 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:
- Select the HSM key to rotate.
- In the security object detailed view, click the ROTATE KEY button.
Figure 23: Rotate Key - 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
- The HSM vendor's PKCS11 library should be installed on this server.
- 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.
- 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:
- To start HSM Gateway, run the following command:
- Debian Package:
sudo dpkg –i <HSM Gateway Package Name>
sudo dpkg –i fortanix-hsm-gateway-3.20.1917-amd64.deb
- RPM Package:
sudo rpm –i <HSM Gateway Package Name>
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.
- 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/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. - 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.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
- The default location of PKCS11 library for nCipher HSMs is:
PKCS11_LIB_PATH=/usr/safenet/lunaclient/lib/libCryptoki2_64.so
5.4 Running HSM Gateway
- To start HSM Gateway, run the following commands:
sudo systemctl enable ftx-hmg
sudo systemctl start ftx-hmg - To check the status of HSM Gateway service, run the following command:
systemctl status ftx-hmg
- 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
or
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
Vendor | HSM Model | Client Software Version | Firmware Version | PKCS11 Library Version |
---|---|---|---|---|
nCipher | nShield Edge | 12.40.2 | 2.33.60 | nCipher PKCS#11 12.40+ (ver 12.40) |
nCipher | nShield Connect | 12.40.2 | 2.38.7 | nCipher PKCS#11 12.40+ (ver 12.40) |
Thales / SafeNet / Gemalto |
SafeNet Luna SA 7.2.0-220 Luna K7 |
7.4.0 | 7.0.3 | 7.4 |
AWS Cloud HSM |
Cavium |
3.1.2-1 | 2.04 | 3.1.2-1 |
Comments
Please sign in to leave a comment.