> ## 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 to configure fxpkcs11.cfg for KMES Series 3 connectivity.

The `fxpkcs11.cfg` file enables you to set the FXPKCS #11 library to connect to the KMES Series 3. To edit the file, run a text editor as an Administrator on Windows or as root on Linux and edit the configuration file accordingly. Most notably, you must set the fields described in this section inside the `<KMS>` section of the file.

Our PKCS #11 library expects to find the PKCS #11 config file in a certain location `(C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg` for Windows and `/etc/fxpkcs11.cfg `for Linux), but you can override that location by using the **FXPKCS11\_CFG** environment variable.

To configure the `fxpkcs11.cfg` file, edit the following sections of the partial file sample:

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

    # Login username
    <CRYPTO-OPR>            [identity_name]         </CRYPTO-OPR>
    # Automatically login on session open
    #<CRYPTO-OPR-PASS>      [identity_password]     </CRYPTO-OPR-PASS>

    # Key group name
    <KEYGROUP-NAME>         keygroup1               </KEYGROUP-NAME>

    # Asymmetric key group name
    <ASYM-KEYGROUP-NAME>    ASYM-RHCS           </ASYM-KEYGROUP-NAME>

    # Connection information
    <ADDRESS>               [kmes_ip_address]       </ADDRESS>
    <PROD-PORT>             2001                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
    <PROD-TLS-CA>           /connection_certs/root.pem        </PROD-TLS-CA>
    <PROD-TLS-CERT>         /connection_certs/fxpkcs11_tls_cert.pem      </PROD-TLS-CERT>
    <PROD-TLS-KEY>          /connection_certs/fxpkcs11_tls_privatekey.pem       </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>
</KMS>
```

<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>Can leave set to the default value of <code>0</code>.</td>
    </tr>

    <tr>
      <td><code>\<CRYPTO-OPR></code></td>
      <td>Specify the name of the<strong> identity</strong> you created on the KMES.</td>
    </tr>

    <tr>
      <td><code>\<KEYGROUP-NAME></code></td>
      <td>If an application creates symmetric keys on the KMES, the value specified in this field is the name of the symmetric key group to which you add the keys.</td>
    </tr>

    <tr>
      <td><code>\<ASYM-KEYGROUP-NAME></code></td>
      <td>If an application creates asymmetric keys on the KMES, the value specified in this field is the name of the asymmetric key group to which you add the keys.</td>
    </tr>

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

    <tr>
      <td><code>\<LOG-FILE></code></td>
      <td>Set the path of the PKCS #11 log file.</td>
    </tr>

    <tr>
      <td><code>\<PROD-PORT></code></td>
      <td>Set the PKCS #11 library to connect to the default Host API port on the KMES, port <code>2001</code><strong>.</strong></td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-ENABLED></code></td>
      <td>Set the field to <code>YES</code>. The only way to connect to the Host API port on the KMES is over TLS.</td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-ANONYMOUS></code></td>
      <td>Set this value to <code>NO</code> because you're connecting to the Host API port by using mutual authentication. This field defines whether the PKCS #11 library authenticates to the KMES. </td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-CA></code></td>
      <td>Define the location of the CA certificates with one or more instances of this tag. In this example, there is only one CA certificate.</td>
    </tr>

    <tr>
      <td><code>\<PROD-TLS-CERT></code></td>
      <td>Set the location of the signed client certificate.</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 include <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.</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 <code>YES</code> if you use a Guardian to manage KMES Series 3 devices in a cluster. If you don't use a Guardian, set it to <code>NO</code>.</td>
    </tr>
  </tbody>
</table>

After you finish editing `fxpkcs11.cfg`, run the **PKCS11Manager** file to test the connection against the KMES 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 for this integration

For the RHCS integration, add the following two 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>
<CHECK-ALREADY-LOGGED-IN>      NO                 </CHECK-ALREADY-LOGGED-IN>
<IGNORE-SESSION-CLOSE>         YES                </IGNORE-SESSION-CLOSE>
<LOGOUT-ON-SESSION-CLOSE>      NO                 </LOGOUT-ON-SESSION-CLOSE>
<FAILOVER-CACHE-LOGIN>         YES                </FAILOVER-CACHE-LOGIN>
<SANITIZE-LABELS>              NONE               </SANITIZE-LABELS>
<LOCAL-STORAGE>         /var/lib/pki/rhcs10-RootCA/fx  </LOCAL-STORAGE>
<CHECK-ALREADY-ACTIVE>         NO                 </CHECK-ALREADY-ACTIVE>
```