> ## Documentation Index > Fetch the complete documentation index at: https://docs.futurex.com/llms.txt > Use this file to discover all available pages before exploring further. # Configure TLS authentication > Configure TLS authentication for secure communication between the Futurex PKCS > [!NOTE] > > 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 options: 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: ```shell title="FXCLI" theme={null} tls-ports set -p "Excrypt Port" --anon tls-ports restart ``` ### Configure the client In the `` section of the `fxpkcs11.cfg` file, set the following fields: ```none title="fxpkcs11.cfg" theme={null} YES YES ``` ## 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). > [!NOTE] > > * 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. **Step 1** Open the FXCLI prompt by running `fxcli-hsm` in a terminal. **Step 2** Connect to the HSM. To connect through the front USB port, run the following command: ```shell title="FXCLI" theme={null} connect usb ``` **Step 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: ```shell title="FXCLI" theme={null} login user ``` **Step 4** Generate a TLS CA key pair and store it in an available key slot on the HSM: ```shell title="FXCLI" wrap theme={null} generate --algo RSA --bits 2048 --usage mak --name TlsCaKeyPair --slot next ``` **Step 5** Create a root certificate. Replace the example distinguished name with your organization's values: ```shell title="FXCLI" theme={null} x509 sign \ --private-slot TlsCaKeyPair \ --key-usage DigitalSignature --key-usage KeyCertSign \ --ca true --pathlen 0 \ --dn 'O=Example Corp\CN=HSM TLS Root' \ --out TlsCa.pem ``` **Step 6** Generate the server key and CSR for the Excrypt port: ```shell title="FXCLI" wrap theme={null} tls-ports request --pair "Excrypt Port" --file production.csr --pki-algo RSA ``` > [!WARNING] > > 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. **Step 7** Sign the server CSR with the TLS CA. Add a `--san` option for each hostname or IP address that clients use in the `
` field, such as `--san dns:hsm.example.com`. The library checks the hostname only if you set `` to **YES** in the `` section of `fxpkcs11.cfg`; without a matching SAN, that check fails: ```shell title="FXCLI" wrap theme={null} x509 sign \ --private-slot TlsCaKeyPair \ --issuer TlsCa.pem \ --csr production.csr \ --eku Server --key-usage DigitalSignature --key-usage KeyEncipherment --key-usage KeyAgreement \ --ca false \ --dn 'O=Example Corp\CN=HSM Excrypt Port' \ --out TlsProduction.pem ``` **Step 8** Push the signed server certificate and the CA to the Excrypt port, and require client certificates: ```shell title="FXCLI" theme={null} tls-ports set --pair "Excrypt Port" \ --enable \ --pki-source Generated \ --clear-pki \ --ca TlsCa.pem \ --cert TlsProduction.pem \ --no-anon ``` **Step 9** Restart the TLS service so that the HSM starts using the new certificate: ```shell title="FXCLI" theme={null} tls-ports restart ``` > [!NOTE] > > Existing connections to the Excrypt port drop while the TLS service restarts. The new certificate can take up to a minute to take effect. **Step 10** In a terminal (not the FXCLI prompt), use OpenSSL to generate the client key and CSR: ```shell title="Shell" wrap theme={null} openssl genrsa -out privatekey.pem 2048 openssl req -new -key privatekey.pem -out ClientPki.csr -subj '/O=Example Corp/CN=PKCS11 Client' ``` **Step 11** At the FXCLI prompt, sign the client CSR with the TLS CA: ```shell title="FXCLI" wrap theme={null} x509 sign \ --private-slot TlsCaKeyPair \ --issuer TlsCa.pem \ --csr ClientPki.csr \ --eku Client --key-usage DigitalSignature --key-usage KeyEncipherment --key-usage KeyAgreement \ --dn 'O=Example Corp\CN=PKCS11 Client' \ --out SignedPki.pem ``` **Step 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 `` field of the `fxpkcs11.cfg` file: ```shell title="Shell" wrap theme={null} openssl pkcs12 -export -inkey privatekey.pem -in SignedPki.pem -certfile TlsCa.pem -out PKI.p12 ``` **Step 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 title="Shell" theme={null} sudo mkdir -p /etc/fxpkcs11/tls sudo cp PKI.p12 /etc/fxpkcs11/tls/ sudo chown [app_user] /etc/fxpkcs11/tls/PKI.p12 sudo chmod 600 /etc/fxpkcs11/tls/PKI.p12 ``` After you create `PKI.p12`, delete `privatekey.pem` from the workstation. ### Configure the client In the `` section of the `fxpkcs11.cfg` file, set the following fields: ```none title="fxpkcs11.cfg" theme={null} YES NO /etc/fxpkcs11/tls/PKI.p12 env:FXPKCS11_P12_PASS ``` 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](https://docs.futurex.com/Integrations/HSM/Secrets_management/OpenBao/Edit_the_Futurex_PKCS_11_Configuration_File.md). 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.