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

> Configure fxpkcs11.cfg on the SAP ASE host to connect to the Excrypt HSM, and verify the connection as the SAP ASE account.

The Futurex PKCS #11 library reads its settings from `/etc/fxpkcs11.cfg`. This page covers the settings that SAP ASE needs: the `<HSM>` section, which defines the connection to the HSM, and the `<CONFIG>` settings for logging and for the commands that the library sends.

Open `/etc/fxpkcs11.cfg` in a text editor as root and edit it.

> [!WARNING]
>
> 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.

## Configure the HSM connection

The following example connects to the HSM by using mutual TLS authentication with a PKCS #12 file:

```none title="/etc/fxpkcs11.cfg" theme={null}
<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                               </SLOT>
    <LABEL>                 Futurex                         </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]                 </CRYPTO-OPR>
    # SAP ASE supplies the password at login, so don't set CRYPTO-OPR-PASS

    # 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>     [p12_password]                  </PROD-TLS-KEY-PASS>

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

| Field | Description |
| - | - |
| `<SLOT>` | The PKCS #11 slot number. Leave it set to **0**. The SAP ASE HSM credential in this guide uses `slot=0`. |
| `<LABEL>` | The token label. Leave it set to **Futurex**. |
| `<CRYPTO-OPR>` | The name of the identity that you created for the SAP ASE application partition. |
| `<CRYPTO-OPR-PASS>` | Leave it out. SAP ASE stores the identity password in its encrypted HSM credential and passes it to the library at login, so the configuration file doesn't need to keep it. |
| `<CRYPTO-OPR2>` | FIPS mode only. The name of the second identity. Both identities must have the same password, because SAP ASE supplies one password at login. |
| `<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 **NO** for mutual authentication, or **YES** for server-side authentication (anonymous TLS). It must match the TLS authentication that you configured on the HSM. |
| `<PROD-TLS-KEY>` | Mutual authentication only. The path to the PKCS #12 file that contains the client key and certificates. |
| `<PROD-TLS-KEY-PASS>` | Mutual authentication only. The password of the 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>` and `<PROD-TLS-KEY-PASS>` fields.

> [!NOTE]
>
> `/etc/fxpkcs11.cfg` contains the PKCS #12 password when you use mutual authentication. Keep the file owned by the SAP ASE account with mode `0600`, as set in [Install Futurex PKCS #11 (FXPKCS11)](https://docs.futurex.com/Integrations/HSM/Database/SAP_ASE/Install_Futurex_PKCS_11_FXPKCS11.md). The password field also accepts `env:` followed by a variable name, but then you must set that variable in the environment that starts SAP ASE.

## Configure the library settings

The `<CONFIG>` section at the top of the file controls logging and how the library talks to the HSM. Set the following fields and leave the others at their default values:

```none title="/etc/fxpkcs11.cfg" theme={null}
<CONFIG>
    <LOG-MODE>              ERROR                             </LOG-MODE>
    <LOG-FILE>              /var/log/fxpkcs11/fxpkcs11.log    </LOG-FILE>
    <LOG-CONSOLE>           NO                                </LOG-CONSOLE>

    <GPED-EXPAND>           YES                               </GPED-EXPAND>
    <UNIQUE-CONNECTIONS>    YES                               </UNIQUE-CONNECTIONS>
</CONFIG>
```

| Field | Description |
| - | - |
| `<LOG-MODE>` | The amount of detail to log: **NONE**, **ERROR**, **INFO**, **TRAFFIC**, or **DEBUG**. Use **ERROR** in production. |
| `<LOG-FILE>` | The path of the log file. The SAP ASE account must be able to write to it. |
| `<LOG-CONSOLE>` | Set to **NO**. The library runs inside the SAP ASE server process, which has no console to write to. |
| `<GPED-EXPAND>` | Set to **YES** so that the library encrypts and decrypts with **GPSE** and **GPSD**, which the application partition allows. |
| `<UNIQUE-CONNECTIONS>` | Set to **YES** so that each PKCS #11 session that SAP ASE opens has its own connection to the HSM. |

To troubleshoot a connection or a failed operation, set `<LOG-MODE>` to **TRAFFIC**, and set `<LOG-TRAFFIC>` and `<LOG-TEMPLATES>` to **YES**. The library then logs each Excrypt command and response, and the attributes of each key that SAP ASE requests. The log masks passwords. After you finish troubleshooting, set `<LOG-MODE>` back to **ERROR**.

## Verify the connection

Run the tests as the SAP ASE account, so that they use the same file permissions as SAP ASE.

**Step 1**

Run `configTest`. It connects to the HSM and prints the slot and token information:

```shell title="Shell" theme={null}
su - sybase
cd /opt/sap/fxpkcs11-tools
./configTest /etc/fxpkcs11.cfg
```

> [!TIP]
>
> The output includes a **Token Info** section with the label **Futurex** and the serial number of the HSM.

**Step 2**

Run `PKCS11Manager` to test a login with the identity password:

```shell title="Shell" theme={null}
./PKCS11Manager /etc/fxpkcs11.cfg
```

In the main menu, select **2. Login**, then **1. Text**, and enter the identity password.

> [!TIP]
>
> The program reports `Logged in.` The configuration file doesn't contain the password, so this test confirms the password that you store in SAP ASE in the next section.

**Step 3**

If either test fails, enable traffic logging as described in [Configure the library settings](#configure-the-library-settings), 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. If the login fails with `PIN_INCORRECT` and the log shows the HSM response `Major key not set`, load the major keys on the HSM as described in [Load major keys](https://docs.futurex.com/Integrations/HSM/Database/SAP_ASE/Configure_the_Excrypt_HSM/Load_major_keys.md).