> ## 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
> Step-by-step guide to configure TLS authentication, including mutual authentication certificates.
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:
```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).
* 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.
Open the FXCLI prompt by running `fxcli-hsm` in a terminal.
Connect to the HSM. To connect through the front USB port, run the following command:
```shell title="FXCLI" theme={null}
connect usb
```
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
```
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
```
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
```
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
```
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.
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
```
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
```
Restart the TLS service so that the HSM starts using the new certificate:
```shell title="FXCLI" theme={null}
tls-ports restart
```
Existing connections to the Excrypt port drop while the TLS service restarts. The new certificate can take up to a minute to take effect.
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'
```
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
```
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
```
Copy `PKI.p12` to the Windows computer where you installed Futurex PKCS #11, for example to `C:\Futurex\tls\PKI.p12`. Restrict the file permissions so that only administrators and the account that runs ISC CertAgent can read it.
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
C:\Futurex\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](/Integrations/HSM/Certificate_Authority/ISC_CertAgent_integrations/ISC_CertAgent_-_Windows/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.