> ## 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. # Edit the Futurex PKCS #11 configuration file > Instructions for modifying the fxpkcs11.cfg file to configure HSM connection parameters. The Futurex PKCS #11 library reads its settings from the `fxpkcs11.cfg` file. This page covers the settings that most integrations need: the `` section, which defines the connection to the HSM, and the logging settings in the `` section. The `config-reference.md` file in the Futurex PKCS #11 package describes every setting. By default, the library reads `C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg` on Windows and `/etc/fxpkcs11.cfg` on Linux. To use a different file, set the `FXPKCS11_CFG` environment variable to its full path. Open the `fxpkcs11.cfg` file in a text editor as an administrator and edit it. ## Configure the HSM connection The following example connects to the HSM by using mutual TLS authentication with a PKCS #12 file: ```none title="fxpkcs11.cfg" theme={null} # Which PKCS11 slot 0 Futurex # HSM crypto operator user name [identity_name] # Automatically log in on session open env:FXPKCS11_IDENTITY_PASS # Connection information

[hsm_address]

9100

YES

/etc/fxpkcs11/tls/PKI.p12

env:FXPKCS11_P12_PASS # YES = This is communicating through a Guardian NO ``` Comments in `fxpkcs11.cfg` must start with `#`. The library doesn't support XML comments (``); a single XML comment stops the library from reading the rest of the section. | Field | Description | | - | - | | `` | The PKCS #11 slot number. Leave it set to **0** unless you configure more than one HSM. | | `` | The token label that applications see. Leave it set to **Futurex** unless the application requires a specific label. | | `` | The name of the identity that you created for the application partition. | | `` | Optional. The password of the identity. When you set it, the library logs in automatically when a session opens. Omit it if the application supplies the password at login. For ways to avoid storing the password in clear text, see [Protect passwords](#protect-passwords). | | ``, `` | FIPS mode only. The name and password of the second identity. | | `

` | The IP address or hostname of the HSM. If you exempted the HSM FQDN from TLS inspection, use that FQDN. | | `` | The Excrypt port of the HSM. The default is **9100**. | | `` | Set to **YES**. | | `` | Set to **YES** for server-side authentication (anonymous TLS), or **NO** for mutual authentication. It must match the TLS authentication that you configured on the HSM. | | `` | Mutual authentication only. The path to the client private key: a PKCS #12 file that contains the key and certificates, an encrypted PKCS #8 key, or a clear PKCS #1 key. | | `` | The password of the PKCS #12 file or the encrypted private key. | | ``, `` | Mutual authentication with PEM files only. The client certificate and the CA certificate. Repeat `` for each CA in the chain. You don't need these fields when `` is a PKCS #12 file. | | `` | Set to **YES** if the library connects through a Guardian Series 3 that manages a cluster of HSMs. Otherwise, set it to **NO**. | For server-side authentication, set `` to **YES** and omit the ``, ``, ``, and `` fields. ## Protect passwords Every password field (``, ``, and ``) accepts the following forms: * **Environment variable:** `env:` followed by a variable name, such as `env:FXPKCS11_IDENTITY_PASS`. The library reads the variable when it starts. If the variable isn't set, the password is empty. * **Windows registry (Windows only):** the full path of a `REG_SZ` value, such as `HKEY_LOCAL_MACHINE\Software\Futurex\fxpkcs11\Password`. * **Clear text:** the password itself. Use it only for testing. You can also set the `FXPKCS11_PASS` and `FXPKCS11_PASS2` environment variables. They override `` and `` for every slot. ## Configure logging The `` section at the top of the file controls logging. To troubleshoot a connection or a failed operation, set the following fields: ```none title="fxpkcs11.cfg" theme={null}

TRAFFIC

/tmp/fxpkcs11.log

YES

``` | Field | Description | | - | - | | `` | The amount of detail to log: **NONE**, **ERROR**, **INFO**, **TRAFFIC**, or **DEBUG**. | | `` | The path of the log file. The process that loads the library must be able to write to it. | | `` | Set to **YES** to log the Excrypt commands sent to the HSM and their responses. The log masks passwords. | | `` | Set to **YES** to log the PKCS #11 attribute templates that the application sends. | After you finish troubleshooting, set `` to **ERROR** or **NONE**. ## Configure key usage The HSM accepts only the key usage combinations allowed by its multi-usage settings. By default, it allows encrypt and decrypt, sign and verify, wrap and unwrap, and derive, each as a separate combination. If an application asks the library to create a key with a combination the HSM doesn't allow, such as sign, verify, encrypt, and decrypt on one key, the HSM rejects it with the error `VALUE OUT OF RANGE`. To fix it, use one of the following methods: * Request an allowed combination in the application. * If the application can't do that, set a usage for all new keys with the `` or `` field in the `` section, for example ` SIGN | VERIFY `. * Allow the combination on the HSM. To view the allowed combinations, run the `multi-usage list` FXCLI command. To add one, run `multi-usage add`, for example `multi-usage add --asymmetric --auth --encrypt --decrypt --sign --verify`. Allowing more usages on a single key weakens key separation, so add only the combination that the application requires. For symmetric encryption, the library uses the **GPED** command by default. If you set `` to **YES** in the `` section, it uses **GPSE** and **GPSD** instead. The application partition must allow whichever commands the library uses. ## Required configurations for the Ansible Vault integration Add the following lines to the `` section of the `fxpkcs11.cfg` file to force encryption and decryption usage on generated keys and suppress non-critical error messages: ```none title="fxpkcs11.cfg" theme={null} ENCRYPT | DECRYPT NO ``` ## Verify the connection Run `configTest` from the `fxpkcs11` directory. It connects to the HSM and prints the slot and token information: ```shell title="Shell" theme={null} cd /usr/local/lib/fxpkcs11 ./configTest ``` The output includes a **Token Info** section with the label **Futurex** and the serial number of the HSM. Run `PKCS11Manager` to test a login. Pass the configuration file path if it isn't the default: ```shell title="Shell" theme={null} ./PKCS11Manager /etc/fxpkcs11.cfg ``` In the menu, select **2. Login** and enter the identity password, then select **8. Generate Random Data**. The login succeeds and the HSM returns random data. If either test fails, enable traffic logging as described in [Configure logging](#configure-logging), run the test again, and check the log file for `ERROR` lines. For example, `certificate verify failed` means that the client doesn't trust the HSM certificate, and `Connection refused` means that the address or port is wrong or that a firewall blocks the connection.