Edit the Futurex PKCS #11 configuration file

The Futurex PKCS #11 library reads its settings from the fxpkcs11.cfg file. This page covers the settings that most integrations need: the <HSM> section, which defines the connection to the HSM, and the logging settings in the <CONFIG> 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:

fxpkcs11.cfg

<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                               </SLOT>
    <LABEL>                 Futurex                         </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]                 </CRYPTO-OPR>
    # FIPS mode only: the second identity
    #<CRYPTO-OPR2>          [second_identity_name]          </CRYPTO-OPR2>

    # Connection information
    <ADDRESS>               [hsm_address]                   </ADDRESS>
    <PROD-PORT>             9100                            </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                             </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                              </PROD-TLS-ANONYMOUS>
    <PROD-TLS-KEY>          /etc/fxpkcs11/tls/PKI.p12       </PROD-TLS-KEY>
    <PROD-TLS-KEY-PASS>     env:FXPKCS11_P12_PASS           </PROD-TLS-KEY-PASS>

    # YES = This is communicating through a Guardian
    <FX-LOAD-BALANCE>       NO                              </FX-LOAD-BALANCE>
</HSM>

EJBCA supplies the identity password when it logs in, so this example doesn’t set <CRYPTO-OPR-PASS>. If the HSM is in FIPS mode, uncomment <CRYPTO-OPR2> and set it to the second identity that you created for the EJBCA application partition.

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
`<SLOT>`	The PKCS #11 slot number. Leave it set to 0 unless you configure more than one HSM.
`<LABEL>`	The token label that applications see. Leave it set to Futurex unless the application requires a specific label.
`<CRYPTO-OPR>`	The name of the identity that you created for the application partition.
`<CRYPTO-OPR-PASS>`	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.
`<CRYPTO-OPR2>`, `<CRYPTO-OPR-PASS2>`	FIPS mode only. The name and password of the second identity.
`<ADDRESS>`	The IP address or hostname of the HSM. If you exempted the HSM FQDN from TLS inspection, use that FQDN.
`<PROD-PORT>`	The Excrypt port of the HSM. The default is 9100.
`<PROD-TLS-ENABLED>`	Set to YES.
`<PROD-TLS-ANONYMOUS>`	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.
`<PROD-TLS-KEY>`	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.
`<PROD-TLS-KEY-PASS>`	The password of the PKCS #12 file or the encrypted private key.
`<PROD-TLS-CERT>`, `<PROD-TLS-CA>`	Mutual authentication with PEM files only. The client certificate and the CA certificate. Repeat `<PROD-TLS-CA>` for each CA in the chain. You don’t need these fields when `<PROD-TLS-KEY>` is a PKCS #12 file.
`<FX-LOAD-BALANCE>`	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 <PROD-TLS-ANONYMOUS> to YES and omit the <PROD-TLS-KEY>, <PROD-TLS-KEY-PASS>, <PROD-TLS-CERT>, and <PROD-TLS-CA> fields.

Protect passwords

Every password field (<CRYPTO-OPR-PASS>, <CRYPTO-OPR-PASS2>, and <PROD-TLS-KEY-PASS>) 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 <CRYPTO-OPR-PASS> and <CRYPTO-OPR-PASS2> for every slot.

Configure logging

The <CONFIG> section at the top of the file controls logging. To troubleshoot a connection or a failed operation, set the following fields:

fxpkcs11.cfg

<CONFIG>
    <LOG-MODE>          TRAFFIC              </LOG-MODE>
    <LOG-FILE>          /tmp/fxpkcs11.log    </LOG-FILE>
    <LOG-TRAFFIC>       YES                  </LOG-TRAFFIC>
    <LOG-TEMPLATES>     YES                  </LOG-TEMPLATES>
</CONFIG>

Field	Description
`<LOG-MODE>`	The amount of detail to log: NONE, ERROR, INFO, TRAFFIC, or DEBUG.
`<LOG-FILE>`	The path of the log file. The process that loads the library must be able to write to it.
`<LOG-TRAFFIC>`	Set to YES to log the Excrypt commands sent to the HSM and their responses. The log masks passwords.
`<LOG-TEMPLATES>`	Set to YES to log the PKCS #11 attribute templates that the application sends.

After you finish troubleshooting, set <LOG-MODE> 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 <FORCED-SYMMETRIC-USAGE> or <FORCED-ASYMMETRIC-USAGE> field in the <CONFIG> section, for example <FORCED-ASYMMETRIC-USAGE> SIGN | VERIFY </FORCED-ASYMMETRIC-USAGE>.
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 <GPED-EXPAND> to YES in the <CONFIG> section, it uses GPSE and GPSD instead. The application partition must allow whichever commands the library uses.

Special defines required with HSM in FIPS mode

Add the following defines to the <CONFIG> section of the fxpkcs11.cfg file:

fxpkcs11.cfg

<FORCED-ASYMMETRIC-USAGE>   SIGN | VERIFY       </FORCED-ASYMMETRIC-USAGE>
<KEY-REQUIRE-LOGIN>         NO                  </KEY-REQUIRE-LOGIN>

Ensure that the EJBCA application server user has read permission on the libfxpkcs11.so and fxpkcs11.cfg files, and write permission on the <LOG-FILE> directory that you set in the fxpkcs11.cfg file. If you use WildFly as the application server, this is the wildfly user.

Verify the connection

Run configTest from the fxpkcs11 directory. It connects to the HSM and prints the slot and token information:

Shell

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

./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, 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.

​Configure the HSM connection

​Protect passwords

​Configure logging

​Configure key usage

​Special defines required with HSM in FIPS mode

​Verify the connection

Configure the HSM connection

Protect passwords

Configure logging

Configure key usage

Special defines required with HSM in FIPS mode

Verify the connection