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,
- Keeping keys safe, or
- Some modules may be able to offer both, but more often than not this is not the case.
Customers have a huge, complicated, and intertwined deployment of HSM infrastructure spread out across their data centers in global geo sites. These legacy HSMs belong to traditional vendors such as Thales (nShield → nCipher - Entrust Dataguard), SafeNet Luna, Cavium, and so on. In certain cases, customers have use-cases where they need to use Cloud HSMs such as AWS HSM, Azure Key Vaults or some 3rd party HSM-aaS. However, after learning about the Fortanix Self-Defending Key Management Service (KMS), customers want to not only consolidate their entire Key Management needs to Fortanix Self-Defending KMS but also want to gradually migrate over to Fortanix Self-Defending KMS without impact on their existing security posture.
Fortanix Self-Defending KMS HSM Gateway Workflow
Create a Group for HSM Connection
- In the Fortanix Self-Defending KMS 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 Self-Defending KMS can connect to it.
- Select the HSM Type:
- Click the drop-down to select the HSM Type. Currently, Fortanix Self-Defending KMS supports connecting to nCipher HSM and SafeNet Luna.
- Click ADD CERTIFICATE to add a certificate for authenticating your HSM. You can either upload the certificate file or copy the contents of the certificate in the textbox provided.
- After adding the certificate, enter the connection details for connecting your HSM.
- HMG IP-address: This is the IP address or hostname of the server running the HSM gateway.
- Slot: Each HSM has multiple slots, which are used for different purposes. A slot is identified by a number.
- PIN: A unique Personal Identification Number (PIN) used to protect the HSM slot.
- Click TEST CONNECTION to test your HSM connection. If Fortanix Self-Defending KMS 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 .
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 your group details, your group is created, and you will see the detailed view of your group.
Now you can see that there is an addition of the HSM tab in the group details, this tab shows the details about your HSM.
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. You can also view your certificate using the SHOW CERTIFICATE button.
It also shows the connection details you provided at the time of creation. Fortanix Self-Defending KMS automatically tests the connection and shows if we are able to connect to the HSM whose details you provided at the time of creation. You can edit this information at any time.
The PIN is not shown to the user but is stored securely. The user does not need to re-enter the “PIN”, to test the connection.
Now, after successfully connecting to the HSM, you can get the keys from the HSM into Fortanix Self-Defending KMS. To do this you need to click the SYNC KEYS button.
On clicking SYNC KEYS, Fortanix Self-Defending KMS connects to the HSM and gets all the keys available in the HSM and stores them as virtual keys in Fortanix Self-Defending KMS. Here, in this sample on clicking SYNC KEYS, five new keys from the HSM are added to Fortanix Self-Defending KMS.
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 Self-Defending KMS can connect to the node using the TEST CONNECTION button.
Not Connected Scenario
On clicking TEST CONNECTION, it is possible that Fortanix Self-Defending KMS 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.
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.
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 a group with a special symbol . The security objects table view will continue to show all the keys irrespective of if they belong to an HSM group or not.
Security Objects Detailed View
Click a security object from the Security Object table in Figure 14 to go to the detailed view.
It shows the following details:
- The group to which it belongs (in the Group field). It also shows if the group is mapped to a 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”.
Click the Users tab in the Fortanix Self-Defending KMS UI and click the user that says “You” to go the user’s detailed view, as shown below.
The detailed view shows all the groups which the user is a part of, additionally Fortanix Self-Defending KMS displays which groups are mapped to HSM and whether they are “Connected” or “Not Connected”.
Fortanix Self-Defending KMS HSM Gateway Security Objects
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.
Generate a Key in HSM
In your Fortanix Self-Defending KMS console, follow the process below to create/import a key:
- Click the Security Objects tab (Figure 19)
- Click to create a new Security Object.
- In the Add New Security Object form (Figure 20) enter a name for the Security Object (Key).
- Select the This is an HSM/external KMS object check box (Figure 20). This will show the HSM configured groups in the Assign to a group list.
- Select the HSM group that you want to assign to key to.
- 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.
Import a Key into HSM
In your Fortanix Self-Defending KMS console, follow the process below to import an key:
- Repeat steps 1- step 5 from the previous section Generate a Key in HSM.
- Click IMPORT to import a new key in HSM.
- 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.
Key Permissions in HSM Group
When a new key is created in an HSM group, all permissions as configured during the create key operation will be applied to the new key created inside 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.
Deactivate a Key in HSM Group
When you deactivate an HSM key in Fortanix Self-Defending KMS, the action will deactivate the virtual key in Fortanix Self-Defending KMS only.
To deactivate a virtual key in Fortanix Self-Defending KMS:
- Select the HSM key to deactivate.
- In the security object detailed view, scroll down, and click the DEACTIVATE button.
Delete a Key in HSM Group
When you delete a key from an HSM group, the action will only delete the virtual key in Fortanix Self-Defending KMS and will not delete the actual key in the configured HSM.
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.
Rotate a Key in HSM Group
When you rotate a key in a 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.
- A new rotated key is now generated.
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.
- The HSM vendor's PKCS11 library should be installed on this server.
- HSM Gateway requires a P12 file that contains 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 HMG is open.
Installing HSM Gateway
HSM gateway is available in the following package formats:
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>For example:
sudo dpkg –i fortanix-hsm-gateway-3.20.1917-amd64.deb
- RPM Package:
sudo rpm –i <HSM Gateway Package Name>For example:
sudo rpm –i fortanix-hsm-gateway-3.20.1917-0.x86_64.rpm
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 -nodesBy 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.
openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem
- Edit the configuration file “/etc/default/ftx-hmg” to update the following lines:
- CERT_FILE: If you are not using the default path for 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.
- 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
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
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-220Luna K7
|AWS Cloud HSM||