Use the Guardian Series 3 to configure HSMs for PKCS #11 Integrations
This section explains how to create an Encryption Device Group and add HSMs to the device group for remote management.
Device groups simplify information management on client Futurex devices by controlling them through a single interface. Use the following procedures to create a device group and add devices.
Select Encryption Devices from the left toolbar, then select [ Add Group ] at the bottom of the window to open the Encryption Device Group window.
Enter a Group Name in the associated field.
Enter a group Description in the associated field
Select an Owner Group from the drop-down menu.
Select Hardware Security Module in the Group Type drop-down menu.
Devices that you add to the Hardware Security Module group must all be the same type (i.e., Vectera Plus, Excrypt Plus, Excrypt SSP Enterprise v.2).
Define Group Options.
Option
Description
Configuration
Enables remote configuration for all Futurex HSMs in the group.
Monitoring
Enables monitoring for all Futurex HSMs in the group.
Balancing
Enables load balancing between group devices for API calls sent to the group.
Choose the Connection Pair in the drop-down menu. The connection pairs available vary depending on the type of device group. For PKCS #11, only the Excrypt/Standard connection pair is required. The HTTP and International connection pairs should be disabled.
Port
Description
Excrypt/Standard
Enables you to connect with the Excrypt or Standard APIs for transaction processing using Futurex HSMs.
HTTP
Enables you to connect with the client Futurex device’s web management portal, or the Registration Authority if you added KMES Series 3 units with the Registration Authority functionality, or to the device’s RESTful web API.
International
Enables you to connect with the International API for transaction processing using Futurex HSMs, when the Excrypt Universal Interface license is enabled.
Check Allow Connection and choose the Port and Header Size, if applicable.
Select the Connection Type for each connection pair from the drop-down menu. The options are Clear, SSL (default), or Anonymous TLS. Futurex recommends using SSL.
Select [ OK ] to create the group.
Groups are defined by device type. When selecting a device to add, choose the group with the same model, because you can't mix and match different devices within the same group.
Select the group to add the client device to.
Select [ Add Device ] at the bottom of the screen to open the Encryption Device window.
Enter the Hostname or IP address of the client device.
HSMs managed by the Guardian Series 3 in a single group must use the same firmware version and feature set.
If using Futurex certificates, keep as default all the remaining settings in this menu (steps 4-11).
In the Connection Pair drop-down menu, select the proper TLS pair for the device in question.
Define the Port on which the client devices are configured to operate. You don't need to specify a Header Size.
Designate the desired Connection Type and Configuration by using the drop-down menus.
Select the device Role from the associated drop-down menu to specify the device's use in the assigned group. Only the Primary Device role is available for the first device added to the group.
Role
Description
Primary Device
Designates a device as a primary device in the device group. The configuration details on this device automatically replicate to any additional devices added to the device group. The primary device also functions in the same role as a production device.
Production Device
Designates a device as a production device. Production devices begin actively processes transactions as soon as you synchronize the device with the group. You can add multiple production devices to an individual device group.
Backup Device
Designating a device as a backup device causes it to remain synchronized with the group, but not process transactions. However, the device automatically begins processing transactions as soon as a production device is removed from service. Using backup devices is optional, and you can add multiple backup devices to an individual device group.
Select a Group from the drop-down menu.
Check the box next to Balancing enabled to enable balancing. This enables the Guardian to evenly distribute requests to devices in the group.
Set the number of seconds of failed pings before the Guardian considers the device disconnected.
Set the desired number of seconds for the ping timeout. The ping timeout is the amount of time before an individual ping is open
Select [ OK ] to save changes.
The Details window opens and displays the connection details and status for the device, and enables you to export this information after the process completes.
To reopen this window, right-click on the encryption device and select Show Connection Status.
If the connection is failing, consider the following:
- Are the Device Group and Device enabled?
- Are the Admin and Excrypt TLS ports configured on the HSM?
- Are the Guardian Series 3 and the HSM using the same CA tree? If using Futurex certificates, they both need to use either RSA or ECC CA.
If port 9100 fails to connect, there is a problem with the Excrypt port configuration. If port 9009 fails to connect, there is a problem with the Admin port configuration.
For this step you need to be logged in with an identity that has a role with permissions Major Keys:Load. You can use the default Administrator role and Admin identities.
The FTK wraps all keys stored on the HSM used with PKCS #11. If using multiple HSMs in a cluster, the same FTK can be used for syncing HSMs. Before you can use an HSM with PKCS #11, it must have an FTK.
The following instructions are for the Guardian Series 3, but you can also complete this process using either Excrypt Manager, FXCLI, or the Excrypt Touch. For more information about how to load the FTK into an HSM using the other tools or devices, see the relevant Administrative Guide.
After logging in, go to the Encryption Devices page. Right-click on the device group and select Remote Manage.
This will pull up the login screen. Once logged in, select Keys in the left-hand menu. This will bring you to the Major Keys tab. Once there, select [ Load ] next to the FTK.
In the first menu, select the Algorithm, Key length, and Key parts that you want to use. Load each of the key parts. You will receive confirmation that each key part that is loaded successfully.
After all key parts have been loaded, you will receive a Final Key Checksum. Select [ Next ] to finish loading the key.
For this step you need to be logged in with an identity that has a role with permissions Role:Add, Role:Assign All Permissions, Role:Modify, Keys:All Slots, Command Settings:Excrypt. You can use the default Administrator role and Admin identities.
For this integration guide, consider the terms Application Partition and Role to be synonymous.
Before an application logs in to the HSM with an authenticated user, it first connects through a Transaction Processing connection to the Transaction Processing Application Partition. For this reason, you must take steps to harden this Application Partition. The following items need to be configured for the Transaction Processing partition:
- l It should not have access to the All Slots permissions.
- It should not have access to any key slots.
- Only the PKCS #11 communication commands should be enabled.
While still logged in to the Device Group, select the Identities menu and select the Application Partition Management tab.
Select the Anonymous Application Partition and select [ Modify Partition ].
Select the Permissions tab, leave the top-level Keys permission checked, but uncheck the All Slots sub permission.
In the Key Slots tab, make sure that no key ranges are specified. The Anonymous Application Partition has access to the entire range of key slots on the HSM by default.
In the Commands tab, make sure to enable only the following PKCS #11 Communication commands:
Command
Description
ECHO
Communication Test/Retrieve Version
PRMD
Retrieve HSM restrictions
RAND
Generate random data
HASH
Retrieve device serial
GPKM
Retrieve key table information
GPKS
General purpose key settings get/change
GPKR
General purpose key settings get (read-only)
To segregate applications on the HSM, you must create an Application Partition specifically for your use case. Application partitions segment the permissions and keys on an HSM between applications. The following steps outline the process for configuring a new application partition:
Select the Application Partitions tab, then select [ Add Partition ] at the bottom of the menu.
Fill in all the fields in the Basic Information tab. Use the following settings (enter any name for the Application Partition that you like):
Setting
Required configuration
Logins Required
1
Ports
Prod
Connection Sources
Ethernet
Use Dual Factor
Never
Select the Permissions tab and select the following permissions:
Permission
Description
Keys
Top level permission
Authorized
Allows for keys that require login
Import PKI
Allows trusting an external PKI. Generally not recommended, but some applications use this to allow for PKI symmetric key wrapping.
No Usage Wrap
Allows for interoperable key wrapping without defining key usage as part of the wrapped key. Use this only if you want to exchange keys with external entities or use the HSM to wrap externally used keys.
In the Key Slots tab, we recommend you create a range of 1000 total keys that do not overlap with another Application Partition. Within the specified range, you should have ranges for both symmetric and asymmetric keys. If the application requires more keys, configure accordingly.
Based on application requirements, particular functions need to be enabled on the Application Partition to use the HSMs functionality. Some of the most often used commands are included on the next page, but these should be specific to your use-case. These can be enabled in the Commands tab.
PKCS #11 Communication Commands:
Command
Description
ECHO
Communication Test/Retrieve Version
PRMD
Retrieve HSM restrictions
RAND
Generate random data
HASH
Retrieve device serial
GPKM
Retrieve key table information
GPKS
General purpose key settings get/change
GPKR
General purpose key settings get (read-only)
Key Operations Commands:
Command
Description
APFP
Generate PKI Public Key from Private Key
ASYL
Load asymmetric key into key table
GECC
Generate an ECC Key Pair
GPCA
General purpose add certificate to key table
GPGS
General purpose generate symmetric key
GPKA
General purpose key add
GPKD
General purpose key slot delete/clear
GRSA
Generate RSA Private and Public Key
LRSA
Load key into RSA Key Table
RPFP
Get public components from RSA private key
Interoperable Key Wrapping:
Command
Description
GPKU
General purpose key unwrap (unrestricted)
GPUK
General purpose key unwrap (preserves key usage)
GPKW
General purpose key wrap (unrestricted)
GPWK
General purpose key wrap (preserves key usage)
Data Encryption Commands:
Command
Description
ADPK
PKI Decrypt Trusted Public Key
GHSH
Generate a Hash (Message Digest)
Starting in firmware version 7.x, this function is enabled by default and does not need to be specified.
GPSE
General Purpose Symmetric Encrypt
GPSD
General Purpose Symmetric Decrypt
GPGC
General purpose generate cryptogram from key slot
GPMC
General purpose MAC (Message Authentication Code)
GPSR
General purpose RSA encrypt/decrypt or sign/verify with recovery
HMAC
Generate a hash-based message authentication code
RDPK
Get Clear Public Key from Cryptogram
Signing Commands:
Command
Description
ASYS
Generate a Signature Using a Private Key
ASYV
Verify a Signature Using a Public Key
GPSV
General purpose data sign and verify
RSAS
Generate a Signature Using a Private Key
For this step you need to be logged in with an identity that has a role with permissions Identity: Add. You can use the default Administrator role and Admin identities.
You must create a new identity and associate it with the Application Partition created in the previous step. To create this new identity, select Identity Management > Add Identity.
Specify a name for the new identity. Select the Roles/Partitions dropdown option and select the name of the Application Partition created in the previous step. This associates the new identity with the Application Partition.
The new identity must be set inside the fxpkcs11.cfg file in the <CRYPTO-OPR> tag.
Select [ Finish ] and then [ Yes ] to exit out of this menu and log out of the device group.
For this step you need to be logged in with an identity that has a role with permissions Keys:All Slots, Management Commands:Certificates, Management Commands:Keys, Security:TLS Sign, TLS Settings:Upload Key. You can use the default Administrator role and Admin identities.
Futurex recommends that you mutually authenticate to the HSM using client certificates, but server-side authentication is also supported.
To enable server-side authentication, go to SSL/TLS Setup, select Excrypt Port, and change the settings to Allow Anonymous. Select [ Update Group Settings ].
Select [ OK ] and [ Finish ] to log out of the device group.
To create client certificates for mutual authentication, refer to Configure the Vectera Plus section of the HSM integration guide.
Because you’re going directly to an HSM to create the client certificates, it might cause the device to drop out of sync. To re-sync, log on to the Guardian, right-click on the device, and select [ Reconnect ].