Skip to main content
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 (anonymous TLS). The connection is encrypted and the HSM doesn’t require a client certificate.
  2. Create connection certificates for mutual authentication. The HSM and the client each present a certificate.
Futurex recommends option 2, mutual authentication, for production. Server-side authentication is simpler to set up for testing.

​
Enable server-side authentication

Choose one of the following methods to enable server-side authentication:

​
Excrypt Manager

Go to the SSL/TLS Setup menu, select the Excrypt Port in the Connection Pair drop-down list, check the Allow Anonymous box, and select [ Save ]. Then select [ Restart Connection Pair ] so that the change takes effect.

​
FXCLI

Run the following tls-ports FXCLI commands to allow anonymous TLS on the Excrypt port and restart the TLS service so that the change takes effect:
FXCLI

​
Configure the client

In the <HSM> section of the fxpkcs11.cfg file, set the following fields:
fxpkcs11.cfg

​
Create connection certificates for mutual authentication

The following example shows how to use FXCLI to create a CA, use it to sign the HSM server certificate and a client certificate, and push the server certificate to the Excrypt port. It uses OpenSSL to create the client key and certificate signing request (CSR).
  • Run FXCLI on a computer connected to the HSM, either through the front USB port or over the network on the admin port (9009).
  • If you don’t 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.
  • HSM key slot labels, such as TlsCaKeyPair, can contain only letters, digits, and underscores.
  • Run help to list all commands, or a command name followed by help to list its options.
1
Open the FXCLI prompt by running fxcli-hsm in a terminal.
2
Connect to the HSM. To connect through the front USB port, run the following command:
FXCLI
3
Log in with both default Admin identities. Run the following command twice, once for each identity, and enter the username and password when prompted:
FXCLI
4
Generate a TLS CA key pair and store it in an available key slot on the HSM:
FXCLI
5
Create a root certificate. Replace the example distinguished name with your organization’s values:
FXCLI
6
Generate the server key and CSR for the Excrypt port:
FXCLI
Each tls-ports request command replaces the server key. Complete the following steps with this CSR before you run tls-ports request again; a certificate signed from an earlier CSR doesn’t match the new key.
7
Sign the server CSR with the TLS CA. Add a --san option for each hostname or IP address that clients use in the <ADDRESS> field, such as --san dns:hsm.example.com. The library checks the hostname only if you set <TLS-CHECK-SANS> to YES in the <CONFIG> section of fxpkcs11.cfg; without a matching SAN, that check fails:
FXCLI
8
Push the signed server certificate and the CA to the Excrypt port, and require client certificates:
FXCLI
9
Restart the TLS service so that the HSM starts using the new certificate:
FXCLI
Existing connections to the Excrypt port drop while the TLS service restarts. The new certificate can take up to a minute to take effect.
10
In a terminal (not the FXCLI prompt), use OpenSSL to generate the client key and CSR:
Shell
11
At the FXCLI prompt, sign the client CSR with the TLS CA:
FXCLI
12
In a terminal, create a PKCS #12 file that contains the client key, the client certificate, and the CA. OpenSSL prompts for an export password; you set this password in the <PROD-TLS-KEY-PASS> field of the fxpkcs11.cfg file:
Shell
13
Copy PKI.p12 to the computer where you installed Futurex PKCS #11, and make it readable only by the user that runs the application. For example, on Linux, replace [app_user] with that user:
Shell
After you create PKI.p12, delete privatekey.pem from the workstation.

​
Configure the client

In the <HSM> section of the fxpkcs11.cfg file, set the following fields:
fxpkcs11.cfg
In this example, the library reads the PKCS #12 password from the FXPKCS11_P12_PASS environment variable. For more information, see Edit the Futurex PKCS #11 configuration file. Because the Excrypt port now requires client certificates (--no-anon), the HSM rejects any client that connects without one. It accepts the TLS handshake and then closes the connection.