> ## 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 Futurex PKCS #11 (FXPKCS11)

> Install the Futurex PKCS #11 (FXPKCS11) library on the Linux computer that runs OpenBao.

> [!NOTE]
>
> Install FXPKCS11 on the same computer as OpenBao.

Perform the following steps to install Futurex PKCS #11 on the Linux computer that runs OpenBao:

**Step 1**

Download the Futurex PKCS #11 tarball for Linux from the Futurex Portal.

**Step 2**

Extract the tarball into `/usr/local/lib`, which creates the `/usr/local/lib/fxpkcs11` directory:

```shell title="Shell" theme={null}
sudo tar -xf fxpkcs11-linux-<version>.tar -C /usr/local/lib
```

> [!NOTE]
>
> For the Futurex PKCS #11 module to be accessible system-wide, an administrative user must extract it into `/usr/local/lib`. If only the current user needs to use the module, extract it into `$HOME/.local/lib` instead and adjust the paths in the following steps.

The `fxpkcs11` directory contains the following files and directories:

| File or directory | Description |
| - | - |
| `fxpkcs11.cfg` | PKCS #11 configuration file for HSM integrations. |
| `fxpkcs11-extended.cfg` | Annotated example configuration with every supported setting. |
| `fxpkcs11-kms.cfg` | Example configuration for KMES Series 3 integrations. You don't need it for HSM integrations. |
| `config-reference.md` | Reference for every configuration setting and environment variable. |
| `x64/` | Builds for 64-bit systems, with one directory per OpenSSL branch (`OpenSSL-1.0.x`, `OpenSSL-1.1.x`, `OpenSSL-3.x`). |
| `x86/` | Builds for 32-bit systems, with directories for OpenSSL 1.0.x and 1.1.x only (`OpenSSL-1.0.x`, `OpenSSL-1.1.x`). |

Each OpenSSL directory contains `libfxpkcs11.so` (the PKCS #11 library), `configTest` (tests the configuration and connection to the HSM), and `PKCS11Manager` (tests the connection and manages the HSM through the library).

**Step 3**

Check which OpenSSL branch the computer uses:

```shell title="Shell" theme={null}
openssl version
```

For example, `OpenSSL 3.0.13` means you use the `OpenSSL-3.x` build. Ubuntu 22.04 and later and RHEL 9 and later use OpenSSL 3.x.

**Step 4**

Copy the matching build into `/usr/local/lib/fxpkcs11` so that the library path is `/usr/local/lib/fxpkcs11/libfxpkcs11.so`. The following example copies the 64-bit OpenSSL 3.x build:

```shell title="Shell" wrap theme={null}
sudo cp /usr/local/lib/fxpkcs11/x64/OpenSSL-3.x/{libfxpkcs11.so,configTest,PKCS11Manager} /usr/local/lib/fxpkcs11/
```

**Step 5**

Copy the configuration file to `/etc`, the default location where the library looks for it:

```shell title="Shell" wrap theme={null}
sudo cp /usr/local/lib/fxpkcs11/fxpkcs11.cfg /etc/fxpkcs11.cfg
```

> [!NOTE]
>
> To keep the configuration file somewhere else, set the `FXPKCS11_CFG` environment variable to its full path for every process that loads the library, including `configTest`, `PKCS11Manager`, and the OpenBao service (add it to `/etc/openbao/openbao.env`).