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

# Install and configure Futurex PKCS #11

> Install the Futurex PKCS #11 library in the SAP ASE library directory, place the endpoint configuration in /etc, and test the connection to CryptoHub.

Install **Futurex PKCS #11 (FXPKCS11)** on the SAP ASE host. SAP ASE loads the module from `$SYBASE/ASE-16_0/lib`, and the module reads `/etc/fxpkcs11.cfg`.

This guide uses `/opt/sap` as `$SYBASE` and `sybase` as the account that runs SAP ASE. Replace them if your installation differs. Run the commands on this page as root, unless a step says otherwise.

## Extract the endpoint bundle

**Step 1**

Copy the endpoint ZIP file to the SAP ASE host, and then extract it to a root-only staging directory:

```shell expandable lines wrap title="Shell" theme={null}
umask 077
mkdir -p /root/fxpkcs11
cd /root/fxpkcs11
unzip /path/to/ENDPOINT_ZIP_FILE.zip
```

The ZIP file contains the following files:

| File | Description |
| - | - |
| `libfxpkcs11.so` | The Futurex PKCS #11 library. |
| `fxpkcs11.cfg` | Configuration file for the Futurex PKCS #11 library. It contains the CryptoHub address, the endpoint identity, and the TLS settings. |
| `configTest` | Program to test the configuration and connection to the CryptoHub. |
| `PKCS11Manager` | Program to test PKCS #11 operations, such as logging in and generating random data. |
| `client.p12` | Full client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key). |
| `client-cert.pem` | Client TLS certificate. |
| `ca-chain.pem` | CA certificate bundle. |
| `CryptoHub <number>.cer` | Auto-generated self-signed CA certificate used to issue client endpoint TLS certificates (the number is random). |
| `Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer` | Futurex Test Root CA for embedded Futurex Test TLS certificates (ECC or RSA, based on the algorithm configured for the connection pair). |

## Install the library for SAP ASE

SAP ASE loads the PKCS #11 library that its HSM credential names from the `$SYBASE/ASE-16_0/lib` directory.

**Step 1**

Copy the library to the SAP ASE library directory, and then give the SAP ASE account ownership of it:

```shell expandable lines wrap title="Shell" theme={null}
install -m 0755 -o sybase -g sybase /root/fxpkcs11/libfxpkcs11.so /opt/sap/ASE-16_0/lib/libfxpkcs11.so
```

> [!TIP]
>
> `ls -l /opt/sap/ASE-16_0/lib/libfxpkcs11.so` shows the library owned by `sybase` and executable.

## Place the configuration and TLS files

The Futurex PKCS #11 library reads `/etc/fxpkcs11.cfg` by default. The configuration refers to the TLS files by relative path, so the TLS files must be in the same directory as the configuration.

**Step 1**

Copy the configuration and the TLS files to `/etc`:

```shell expandable lines wrap title="Shell" theme={null}
cd /root/fxpkcs11
cp fxpkcs11.cfg client.p12 client-cert.pem ca-chain.pem CryptoHub*.cer Futurex*.cer /etc/
```

**Step 2**

Give the SAP ASE account ownership of the files. The configuration and the PKCS #12 file contain secrets, so only the owner can read them:

```shell expandable lines wrap title="Shell" theme={null}
cd /etc
chown sybase:sybase fxpkcs11.cfg client.p12 client-cert.pem ca-chain.pem CryptoHub*.cer Futurex*.cer
chmod 600 fxpkcs11.cfg client.p12
chmod 644 client-cert.pem ca-chain.pem CryptoHub*.cer Futurex*.cer
```

**Step 3**

Create a log directory that the SAP ASE account can write:

```shell expandable lines wrap title="Shell" theme={null}
install -d -m 0750 -o sybase -g sybase /var/log/fxpkcs11
```

**Step 4**

Open `/etc/fxpkcs11.cfg` in a text editor, and then set the log file location:

```text title="/etc/fxpkcs11.cfg" theme={null}
<LOG-FILE> /var/log/fxpkcs11/fxpkcs11.log </LOG-FILE>
```

## Test the connection to CryptoHub

**Step 1**

Copy the test programs to a directory that the SAP ASE account can use:

```shell expandable lines wrap title="Shell" theme={null}
install -d -m 0750 -o sybase -g sybase /opt/sap/fxpkcs11-tools
install -m 0750 -o sybase -g sybase /root/fxpkcs11/configTest /root/fxpkcs11/PKCS11Manager /opt/sap/fxpkcs11-tools/
```

**Step 2**

As the SAP ASE account, run the configuration test:

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

> [!TIP]
>
> The **Token Info** section shows `Label: Futurex` and a **Serial Number** that matches your CryptoHub. The log file shows `Established connection to HSM`.

If the test fails, see [Troubleshooting](/Integrations/CryptoHub/Database/SAP_ASE/Troubleshooting).

## Move the PIN to SAP ASE

The `<CRYPTO-OPR-PASS>` value in `fxpkcs11.cfg` is the PIN for the endpoint identity. SAP ASE gives this PIN to the library through its HSM credential, so the configuration file does not need to keep it.

**Step 1**

Copy the `<CRYPTO-OPR-PASS>` value from `/etc/fxpkcs11.cfg`, and then store it in a secure location. This guide calls this value the *CryptoHub endpoint PIN*.

**Step 2**

Comment out the `<CRYPTO-OPR-PASS>` line:

```text title="/etc/fxpkcs11.cfg" theme={null}
# <CRYPTO-OPR-PASS> CRYPTOHUB_ENDPOINT_PIN </CRYPTO-OPR-PASS>
```

**Step 3**

As the SAP ASE account, run `PKCS11Manager`, log in with the CryptoHub endpoint PIN, and generate random data:

```shell expandable lines wrap title="Shell" theme={null}
su - sybase
cd /opt/sap/fxpkcs11-tools
./PKCS11Manager
```

> [!TIP]
>
> The login succeeds and the random data request returns a result. The library no longer logs in by itself, so the PIN you enter is the control.

**Step 4**

Delete the staging directory:

```shell expandable lines wrap title="Shell" theme={null}
rm -rf /root/fxpkcs11
```

Keep the endpoint ZIP in protected storage or delete it, according to your credential-handling policy.