Skip to main content
This section explains how to create an Encryption Device Group and add HSMs to the device group for remote management.

​
Create a client Futurex device group

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.
1
Select Encryption Devices from the left toolbar, then select [ Add Group ] at the bottom of the window to open the Encryption Device Group window.
2
Enter a Group Name in the associated field.
3
Enter a group Description in the associated field
4
Select an Owner Group from the drop-down menu.
5
Select Hardware Security Module in the Group Type drop-down menu.
Devices that you add to the HSM group must all be the same type (such as Vectera Plus, Excrypt Plus, Excrypt SSP Enterprise v.2).
6
Define Group Options.
OptionDescription
ConfigurationEnables remote configuration for all Futurex HSMs in the group.
MonitoringEnables monitoring for all Futurex HSMs in the group.
BalancingEnables load balancing between group devices for API calls sent to the group.
7
Choose the Connection Pair in the drop-down menu. The connection pairs available vary depending on the type of device group. For PKCS #11, you need only the Excrypt/Standard connection pair. YOu should disable the HTTP and International connection pairs.
PortDescription
Excrypt/StandardEnables you to connect with the Excrypt or Standard APIs for transaction processing by using Futurex HSMs.
HTTPEnables you to connect with one of the following targets:
  • The client Futurex device web management portal
  • The Registration Authority (RA) if you added KMES Series 3 units with the RA functionality
  • The RESTful web API of the device
InternationalEnables you to connect with the International API for transaction processing by using Futurex HSMs when you enable the Excrypt Universal Interface license.
8
Select the Allow Connection checkbox and choose the Port and Header Size, if applicable.
9
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.
10
Select [ OK ] to create the group.

​
Add devices to a device group

Groups are defined by device type. Because you can’t mix and match different devices within the same group, choose the group with the same model when selecting a device to add. Perform the following steps to add a device to a group:
1
Select the group to add the client device to.
2
Select [ Add Device ] at the bottom of the screen to open the Encryption Device window.
3
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).
4
In the Connection Pair drop-down menu, select the proper TLS pair for the device in question.
5
Define the Port on which the client devices are configured to operate. You don’t need to specify a Header Size.
6
Designate the desired Connection Type and Configuration by using the drop-down menus.
7
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.
RoleDescription
Primary DeviceDesignates 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 DeviceDesignates a device as a production device. Production devices begin actively processing transactions when 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.
8
Select a Group from the drop-down menu.
9
Check the box next to Balancing enabled to enable balancing. This enables the Guardian to evenly distribute requests to devices in the group.
10
Set the number of seconds of failed pings before the Guardian considers the device disconnected.
11
Set the desired number of seconds for the ping timeout. The ping timeout is the amount of time before an individual ping is open
12
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.

​
Troubleshooting failed connections

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

​
Configure the HSM through the Guardian

Perform the tasks in this section to configure the HSM.

​
Load the Futurex key

For this step, you need to log in with an identity that has a role with Major Keys:Load permisision. 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, you can use the same FTK 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 by using 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.
1
After logging in, go to the Encryption Devices page. Right-click on the device group and select Remote Manage.
2
After you log in on the login screen, select Keys in the left-hand menu. Go to the Major Keys tab and select [ Load ] next to the FTK.
3
In the first menu, select the Algorithm, Key length, and Key parts that you want to use. Load each of the key parts.
You receive a confirmation that each key part loaded successfully. When they finish loading, you receive a Final Key Checksum.
4
Select [ Next ] to finish loading the key.

​
Configure a transaction processing connection and create an application partition

For this step, you need to log in with an identity that has a role with the following permissions: Role:Add, Role:Assign All Permissions, Role:Modify, Keys:All Slots, and Command Settings:Excrypt. You can use the default Administrator role and Admin identities.
This integration guide treats the terms application partition and role as synonymous.
Before logging in to the HSM with an authenticated user, an application connects through a transaction processing connection to the transaction processing application partition. Therefore, you must take steps to configure the following items to harden this partition:
  • It should not have access to the All Slots permissions.
  • It should not have access to any key slots.
  • Enable only the PKCS #11 communication commands.
Choose one of the following methods to configure the transaction processing connection:

​
Excrypt Manager

Perform the following steps to configure a transaction processing connection on Excrypt Manager:
1
Go to the Application Partitions menu, select the transaction processing application partition, and select [ Modify ].
2
In the Permissions tab, leave the top-level Keys permission checked and uncheck the All Slots sub permission.
3
In the Key Slots tab, ensure that the settings do not specify key ranges. By default, the transaction processing application partition can access the entire range of key slots on the HSM.
4
In the Commands tab, make sure to enable only the following PKCS #11 Communication commands:
CommandDescription
ASYSGenerate signature using PKI private key
ECHOCommunication Test/Retrieve Version
GPKMRetrieve key table information
GPKRGeneral-purpose key settings get (read-only)
GPKSGeneral-purpose key settings get/change
HASHRetrieve device serial
PRMDRetrieve HSM restrictions
RANDGenerate random data
STATHSM statistics
TIMESet time

​
FXCLI

Run the following role modify FXCLI commands to remove all permissions and key ranges that are currently assigned to the Transaction Processing role and enable only the PKCS #11 Communication commands:
Because the Transaction Processing role was previously called the Anonymous role, the following commands specify Anonymous in the name field.
FXCLI
  role modify --name Anonymous --clear-perms --clear-key-ranges
FXCLI
  role modify --name Anonymous --add-perm "Keys" --add-perm Excrypt:ASYS --add-perm Excrypt:ECHO --add-perm Excrypt:GPKM --add-perm Excrypt:GPKR --add-perm Excrypt:GPKS --add-perm Excrypt:HASH --add-perm Excrypt:PRMD --add-perm Excrypt:RAND --add-perm Excrypt:STAT --add-perm Excrypt:TIME

​
Create an application partition

To segregate applications on the HSM, you must create an application partition specifically for your use case. Application partitions segment the permissions and keys between applications on an HSM between applications. The following steps outline the process for configuring a new application partition:
1
Go to the Application Partitions tab and select [ Add Partition ].
2
In the Basic Information tab, configure all the fields as follows:
OptionRequired configuration
Logins Required Set to 1
If the HSM is in FIPS mode, you must set Logins Required to 2.
PortsSet to Prod.
Connection SourcesSet to Ethernet.
Use Dual FactorSet to Never.
3
Go to the Permissions tab and select the following permissions:
PermissionDescription
KeysTop-level permission
AuthorizedAllows 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 Enables 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.
4
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 it accordingly.
5
To use the HSM functionality, you must enable particular functions on the application partition based on application requirements. Enable the following commands under Commands:PKCS #11 communication commands:
CommandDescription
ECHOCommunication Test/Retrieve Version
PRMDRetrieve HSM restrictions
RANDGenerate random data
HASHRetrieve device serial
GPKMRetrieve key table information
GPKSGeneral-purpose key settings get/change
GPKRGeneral-purpose key settings get (read-only)
Key operations commands:
CommandDescription
APFPGenerate PKI Public Key from Private Key
ASYLLoad asymmetric key into the key table
GECCGenerate an ECC Key Pair
GPCAGeneral-purpose add certificate to key table
GPGSGeneral-purpose generate symmetric key
GPKAGeneral-purpose key add
GPKDGeneral-purpose key slot delete/clear
GRSAGenerate RSA Private and Public Key
LRSALoad key into RSA Key Table
RPFPGet public components from the RSA private key
Interoperable key wrapping commands:
CommandDescription
GPKUGeneral-purpose key unwrap (unrestricted)
GPUKGeneral-purpose key unwrap (preserves key usage)
GPKWGeneral-purpose key wrap (unrestricted)
GPWKGeneral-purpose key wrap (preserves key usage-
Data encryption commands:
CommandDescription
ADPKPKI Decrypt Trusted Public Key
GHSHGenerate a Hash (Message Digest)
Starting in firmware version 7.x, this function is enabled by default so you don’t need to specify it.
GPSEGeneral-purpose Symmetric Encrypt
GPSDGeneral-purpose Symmetric Decrypt
GPGCGeneral-purpose generate cryptogram from key slot
GPMCGeneral-purpose MAC (Message Authentication Code)
GPSRGeneral-purpose RSA encrypt/decrypt or sign/verify with recovery
HMACGenerate a hash-based message authentication code
RDPKGet Clear Public Key from Cryptogram
Signing commands:
CommandDescription
ASYSGenerate a Signature Using a PKI Private Key
ASYVVerify a Signature Using a Public Key
GPSVGeneral-purpose data sign and verify
RSASGenerate a Signature Using a RSA Private Key

​
Create a new identity and associate it with the new application partition

For this step, you must log in with an identity that has a role with the Identity:Add permission. You can use the default Administrator role and Admin identities.
1
To create this new identity, select Identity Management > Add Identity.
2
Specify a name for the new identity.
3
Then, in the Roles drop-down menu, select the name of the previously created application partition to associate the new identity with the previously created application partition.
You must set the new identity inside the fxpkcs11.cfg file in the <CRYPTO-OPR> tag.
4
Select [ Finish ] and then [ Yes ] to exit out of this menu and log out of the device group.

​
Configure TLS Authentication

For this step, you must log in with an identity that has a role with the following permissions: Keys:All Slots, Management Commands:Certificates, Management Commands:Keys, Security:TLS Sign, and TLS Settings:Upload Key. You can use the default Administrator role and Admin identities.
To configure TLS authentication, choose one of the following methods:
  1. Enable server-side authentication.
  2. Create connection certificates for mutual authentication.
We recommend option 2, mutual authentication.

​
Enable server-side authentication

We recommend mutually authenticating to the HSM using client certificates, but the Vectera Plus also supports server-side authentication. The following steps outline the process for enabling server-side authentication. Choose one of the following methods to enable server-side authentication:

​
Excrypt Manager

To use Excrypt Manager to enable server-side authentication, go to the SSL/TLS Setup menu. Then, select the Excrypt Port in the Connection Pair drop-down list, check the Allow Anonymous box, and select [ Save ].

​
FXCLI

To use FXCLI to enable server-side authentication, run the tls-ports set FXCLI command to enable server-side authentication with the Allow Anonymous SSL/TLS setting:
FXCLI
  tls-ports set -p "Excrypt Port" --anon

​
Create connection certificates for mutual authentication

As mentioned previously, we recommend mutually authenticating to the HSM by using client certificates, and the system enforces mutual authentication by default. The following example shows how to use FXCLI to generate a CA to sign the HSM server certificate and a client certificate. Then, it shows how to generate the client keys and CSR by using OpenSSL.
  • For this example, you must connect the computer that is running FXCLI to the front USB port of the HSM.
  • If you do not specify a file path for commands that create an output file, FXCLI saves the file to the current working directory.
  • Using user-generated certificates requires you to load a PMK on the HSM.
  • If you run help by itself, a full list of available commands displays. You can see all options for a command by running the command name followed by help.
1
Open the FXCLI prompt by running fxcli-hsm in a terminal.
2
Connect your laptop to the HSM by using the USB port on the front, and run the following command.
FXCLI
  connect usb
3
Run the following command to log in with both default Admin identities. When prompted for the username and password, enter them. You must run this command twice.
FXCLI
  login user
4
Generate a TLS CA and store it in an available key slot on the HSM.
FXCLI
  generate --algo RSA --bits 2048 --usage mak --name TlsCaKeyPair --slot next
5
Create a root certificate.
FXCLI
  x509 sign \
      --private-slot TlsCaKeyPair \
      --key-usage DigitalSignature --key-usage KeyCertSign \
      --ca true --pathlen 0 \
      --dn 'O=Futurex\CN=Root' \
      --out TlsCa.pem
6
Generate the server keys for the HSM.
FXCLI
  tls-ports request --pair "Excrypt Port" --file production.csr --pki-algo RSA
7
Sign the server CSR with the newly created TLS CA.
FXCLI
  x509 sign \
      --private-slot TlsCaKeyPair \
      --issuer TlsCa.pem \
      --csr production.csr \
      --eku Server --key-usage DigitalSignature --key-usage KeyAgreement \
      --ca false \
      --dn 'O=Futurex\CN=Production' \
      --out TlsProduction.pem
8
Push the signed server PKI to the production port on the HSM.
FXCLI
  tls-ports set --pair "Excrypt Port" \
      --enable \
      --pki-source Generated \
      --clear-pki \
      --ca TlsCa.pem \
      --cert TlsProduction.pem \
      --no-anon
9
To generate client keys and CSR, run the following OpenSSL commands from Windows PowerShell rather than from the FXCLI program:
Powershell
# Generate the client keys
$ openssl genrsa -out privatekey.pem 2048
Powershell
# Generate a client CSR
$ openssl req -new -key privatekey.pem -out ClientPki.csr -days 365
10
Using FXCLI, sign the client CSR that was just generated using OpenSSL.
FXCLI
  x509 sign  \
   --private-slot TlsCaKeyPair \
   --issuer TlsCa.pem \
   --csr ClientPki.csr \
   --eku Client --key-usage DigitalSignature --key-usage KeyAgreement \
   --dn 'O=Futurex\CN=Client' \
   --out SignedPki.pem
11
Run the following command from PowerShell. Use OpenSSL to create a PKCS #12 file that you can use to authenticate as a client by using our PKCS #11 library:
Powershell
openssl pkcs12 -export -inkey privatekey.pem -in SignedPki.pem -certfile TlsCa.pem -out PKI.p12