> ## 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

> Guide to editing the fxpkcs11.cfg file to configure HSM connection parameters for the PKCS#11 library.

The Futurex PKCS #11 library uses the application configuration file (`fxpkcs11.cfg`) to connect to the HSM. It enables you to modify certain configurations and set connection details. This section covers the `<HSM>` portion of the **FXPKCS11** config file, where you set the connection details.

<Note>
  By default, the FXPKCS11 library looks for the configuration file in `C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg` for Windows and `/etc/fxpkcs11.cfg` for Linux. Alternatively, you can set the FXPKCS11\_ CFG environment variable to the location of the `fxpkcs11.cfg` file.
</Note>

Open the `fxpkcs11.cfg` file in a text editor as an administrator and edit it accordingly.

```none expandable lines wrap title="None" theme={null}
<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                       </SLOT>
    <LABEL>                 Futurex                 </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]         </CRYPTO-OPR>
    
    # FIPS-mode requirement
    #<CRYPTO-OPR2>           [second_identity]       </CRYPTO-OPR2>

    # Connection information
    <ADDRESS>               [hsm_ip_address]        </ADDRESS>
    <PROD-PORT>             9100                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
#    <PROD-TLS-CA>           /home/user/tls/root.pem        </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub1.pem     </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub2.pem     </PROD-TLS-CA>
    <PROD-TLS-KEY>          /home/user/tls/PKI.p12       </PROD-TLS-KEY>
    <PROD-TLS-KEY-PASS>     safest                  </PROD-TLS-KEY-PASS>

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

<Warning>
  If you are deploying the EJBCA integration with the HSM in FIPS mode, you must uncomment and configure dual-login in the `<HSM>` section shown above. Add the second user you created for the EJBCA application partition inside the `CRYPTO-OPR2` tag.
</Warning>

<table>
  <thead>
    <tr>
      <th><em><strong>Field</strong></em></th>
      <th><em><strong>Description</strong></em></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>\<SLOT></code></td>
      <td>Leave it set to the default value of <code>0</code>.</td>
    </tr>

    <tr>
      <td><code>\<LABEL></code></td>
      <td>Leave it set to the default value of <strong>Futurex</strong>.</td>
    </tr>

    <tr>
      <td><code>\<CRYPTO-OPR></code></td>
      <td>Specify the name of the<strong> identity</strong> created for the application partition.</td>
    </tr>

    <tr>
      <td><code>\<CRYPTO-OPR-PASS></code></td>
      <td>Specify the password of the identity configured in the <code>\<CRYPTO-OPR></code> field. Use this to log the application into the HSM automatically if required.</td>
    </tr>

    <tr>
      <td><code>\<ADDRESS></code></td>
      <td>Specify the <strong>IP address</strong> of the HSM to which the PKCS #11 library should connect.</td>
    </tr>

    <tr>
      <td><code>\<PROD-PORT></code></td>
      <td>Set the port number of the HSM that the <strong>FXPKCS11</strong> library should connect to.</td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-ENABLED></code></td>
      <td>Set the field to <strong>YES</strong>. </td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-ANONYMOUS></code></td>
      <td>Defines whether the <strong>FXPKCS11</strong> library authenticates to the server.</td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-KEY></code></td>
      <td>Set the location of the client private key. Supported formats for the TLS private key are <strong>PKCS #1</strong> clear private keys, <strong>PKCS #8</strong> encrypted private keys, or a <strong>PKCS #12</strong> file that contains the private key and certificates encrypted under a password.<br /><Note>Because you define a PKCS #12 file in the <code>\<PROD-TLS-KEY></code> field in this example, you don't need to define the signed client certificate with the <code>\<PROD-TLS-CERT></code> tag or define the CA certificates with one or more instances of the <code>\<PROD-TLS-CA></code> tag.<br /></Note></td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-KEY-PASS></code></td>
      <td>Set the password of the PKCS #12 file, if necessary.</td>
    </tr>

    <tr>
      <td><code>\<FX-LOAD-BALANCE></code></td>
      <td>Set this field to <strong>YES</strong> if you use a Guardian to manage HSM devices in a cluster. If you don't use a Guardian, set it to <strong>NO</strong>.</td>
    </tr>
  </tbody>
</table>

After you finish editing the `fxpkcs11.cfg` file, run the `PKCS11Manager` file to test the connection against the HSM, and check the `fxpkcs11.log` for errors and information. For more information, refer to the Futurex PKCS #11 technical reference found on the Futurex Portal.

## Special defines required with HSM in FIPS mode

Add the following defines to the `<CONFIG>` section of the **FXPKCS11** configuration file:

```none expandable lines wrap title="None" theme={null}
<FORCED-ASYMMETRIC-USAGE>   SIGN | VERIFY       </FORCED-ASYMMETRIC-USAGE>
<KEY-REQUIRE-LOGIN>         NO                  </KEY-REQUIRE-LOGIN>
```

<Warning>
  Ensure EJBCA's app server user has read permissions on the `libfxpkcs11.so` and `fxpkcs11.cfg` files, and write permissions on the configured `<LOG-FILE>` directory.

  In the case where you are using Wildfly for the app server, the `wildfly` user needs read permission over the `libfxpkcs11.so` and `fxpkcs11.cfg` files, and write permission over the `<LOG-FILE>` directory you have set in the Futurex PKCS #11 configuration file.
</Warning>