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

> Step-by-step instructions for installing and configuring Futurex PKCS #11 on Windows or Linux.

Install **Futurex PKCS #11 (FXPKCS11)** on the machine where you installed the third-party application. Select one of the following operating systems and perform the instructions:

## Windows

Perform the following instructions to install **FXPKCS11** on Windows:

**Step 1**

Extract the Endpoint zip file downloaded in your browser after deploying the service in CryptoHub. The zip file contains the following files:

<table>
  <thead>
    <tr>
      <th>File</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`PKCS11Manager.exe`</td>
      <td>Program to test the connection to the CryptoHub and perform basic functions through the **FXPKCS11** module, such as logging in and generating random data.</td>
    </tr>

    <tr>
      <td>`ca-chain.pem`</td>
      <td>CA certificate bundle</td>
    </tr>

    <tr>
      <td>`client-cert.pem`</td>
      <td>Client TLS certificate</td>
    </tr>

    <tr>
      <td>`client.p12`</td>
      <td>Full Client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key)</td>
    </tr>

    <tr>
      <td>`configTest.exe`</td>
      <td>Program to test the configuration and connection to the CryptoHub</td>
    </tr>

    <tr>
      <td>`fxpkcs11.cfg`</td>
      <td>Configuration file for the Futurex PKCS #11 library</td>
    </tr>

    <tr>
      <td>`fxpkcs11.dll`</td>
      <td>The Futurex PKCS #11 library file.</td>
    </tr>

    <tr>
      <td>`CryptoHub <number>.cer`</td>
      <td>Auto-generated self-signed CA certificate used to issue client endpoint TLS certs (number is random)</td>
    </tr>

    <tr>
      <td>`Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer`</td>
      <td>Futurex Test Root CA for embedded Futurex Test TLS certs (ECC or RSA, based on the algorithm configured for the connection pair)</td>
    </tr>
  </tbody>
</table>

**Step 2**

Move all of the preceding **FXPKCS11** files to `C:\Program Files\Futurex\fxpkcs11`. Create the `Futurex\fxpkcs11` directory as an administrator.

**Step 3**

The Futurex PKCS #11 module expects to find the **FXPKCS11** configuration file (`fxpkcs11.cfg`) in the `C:\Program Files\Futurex\fxpkcs11` directory by default. If you want to store the config elsewhere, set the **FXPKCS11\_CFG** environment variable to the full path of the config file. **Ensure the TLS files referenced in the config are also in the same directory.**

**Step 4**

Configure secrets (recommended: use an environment variable for the PKCS #12 password).

**PKCS #11 PIN**

* Find it in `CRYPTO-OPR-PASS` inside `fxpkcs11.cfg`.
* Copy the PIN to your clipboard, then comment out the `CRYPTO-OPR-PASS` line. You will configure this PIN in Axway VA in the next step.

**PKCS #12 password**

* Find it in `PROD-TLS-KEY-PASS` inside `fxpkcs11.cfg`.
* We recommend copying this password, then replacing the value in `fxpkcs11.cfg` with `env:PKCS11_P12`.
* Set the machine-wide environment variable in an **elevated** Command Prompt (**Run as Administrator**):

  ```shell expandable lines wrap title="Shell" theme={null}
  setx PKCS11_P12 safest /M
  ```

  Replace `safest` with the actual P12 password you copied to your clipboard.

> [!WARNING]
>
> Newly set/updated environment variables are only visible to **new** processes. Close and reopen Command Prompt/PowerShell (or log out/in) before validating or running applications that rely on `PKCS11_P12`.

**Step 5**

**Logs**

* Default FxPKCS11 log location: `C:\Program Files\Futurex\fxpkcs11`
* To customize, modify the `<LOG-FILE>` definition in `fxpkcs11.cfg`.

**Step 6**

**Quick validation (recommended)**

Validate config and connection:

* Run `configTest.exe` from `C:\Program Files\Futurex\fxpkcs11`.
* Confirm the connection test succeeds.
* If it fails, check the FxPKCS11 log file (see "Logs" above) and verify the PKCS #12 password and TLS materials are in the expected locations.

Validate PKCS #11 operations:

* Run `PKCS11Manager.exe` from `C:\Program Files\Futurex\fxpkcs11`.
* Confirm you can authenticate and perform a simple action (e.g., generate random data).
* If authentication fails, verify the PKCS #11 PIN is correct. To update the PKCS #11 PIN, log in to the CryptoHub dashboard, navigate to the **Identity and Access** menu, and select the **Applications & Partitions** tab. Find the application you deployed, and in the **Manage** section, select the **Authentication** button. This opens a dialog where you can change the PIN/password for the endpoint.

## Linux

Perform the following instructions to install **FXPKCS11** on Linux:

**Step 1**

Extract the zip file downloaded from CryptoHub. The zip file contains the following files:

<table>
  <thead>
    <tr>
      <th>File</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`PKCS11Manager`</td>
      <td>Program to test the connection to the CryptoHub and perform basic functions through the **FXPKCS11** module, such as logging in and generating random data.</td>
    </tr>

    <tr>
      <td>`ca-chain.pem`</td>
      <td>CA certificate bundle</td>
    </tr>

    <tr>
      <td>`client-cert.pem`</td>
      <td>Client TLS certificate</td>
    </tr>

    <tr>
      <td>`client.p12`</td>
      <td>Full Client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key)</td>
    </tr>

    <tr>
      <td>`configTest`</td>
      <td>Program to test the configuration and connection to the CryptoHub </td>
    </tr>

    <tr>
      <td>`fxpkcs11.cfg`</td>
      <td>Configuration file for the Futurex PKCS #11 library</td>
    </tr>

    <tr>
      <td>`libfxpkcs11.so`</td>
      <td>The Futurex PKCS #11 library file.</td>
    </tr>

    <tr>
      <td>`CryptoHub <number>.cer`</td>
      <td>Auto-generated self-signed CA certificate used to issue client endpoint TLS certs (number is random)</td>
    </tr>

    <tr>
      <td>`Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer`</td>
      <td>Futurex Test Root CA for embedded Futurex Test TLS certs (ECC or RSA, based on the algorithm configured for the connection pair)</td>
    </tr>
  </tbody>
</table>

**Step 2**

Move all the preceding files to one of the following locations:

* To make the **FXPKCS11** library accessible system-wide, use sudo to move the files to the `/usr/local/lib/fxpkcs11` directory.
* To make the **FXPKCS11** library accessible only for the current user, move the files to the `$HOME/lib/fxpkcs11` directory.

**Step 3**

> [!WARNING]
>
> IMPORTANT
>
> The Futurex PKCS #11 module expects `fxpkcs11.cfg` in the `/etc` directory by default. The config references the following files by relative path, so they must all be in the same directory as `fxpkcs11.cfg`:
>
> * `client.p12`
> * `CryptoHub <number>.cer`
> * `Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer`

Use the following command to move `fxpkcs11.cfg` and the TLS files to `/etc`:

```shell expandable lines wrap title="Shell" theme={null}
sudo mv fxpkcs11.cfg client.p12 CryptoHub*.cer Futurex*.cer /etc/
```

Alternatively, store the config elsewhere and set **FXPKCS11\_CFG**. **Ensure the TLS files listed above are also placed in the same directory as the config file:**

```shell expandable lines wrap title="Shell" theme={null}
export FXPKCS11_CFG=/path/to/your/fxpkcs11.cfg
```

**Step 4**

Configure secrets (recommended: use an environment variable for the PKCS #12 password).

**PKCS #11 PIN**

* Find it in `CRYPTO-OPR-PASS` inside `fxpkcs11.cfg`.
* Copy the PIN to your clipboard, then comment out the `CRYPTO-OPR-PASS` line. You will configure this PIN in Axway VA in the next step.

**PKCS #12 password**

* Find it in `PROD-TLS-KEY-PASS` inside `fxpkcs11.cfg`.
* We recommend copying this password, then replacing the value in `fxpkcs11.cfg` with `env:PKCS11_P12`.
* Set `PKCS11_P12` system-wide (RHEL or Debian/Ubuntu) by creating:

  ```shell expandable lines wrap title="Shell" theme={null}
  sudo nano /etc/profile.d/fxpkcs11.sh
  ```

  Contents:

  ```shell expandable lines wrap title="/etc/profile.d/fxpkcs11.sh" theme={null}
  export PKCS11_P12=safest
  ```

  Replace `safest` with the actual P12 password you copied to your clipboard.

> [!WARNING]
>
> This takes effect for **new login shells**. Log out/in or start a new shell session before validating or running applications that rely on `PKCS11_P12`.

**Step 5**

**Logs**

* Default FxPKCS11 log location: the current directory (i.e., the same directory as `fxpkcs11.cfg`)
* To customize, modify the `<LOG-FILE>` definition in `fxpkcs11.cfg`.

**Step 6**

**Quick validation (recommended)**

Validate config and connection:

* Run `configTest` and confirm the connection test succeeds.
* If it fails, check the FxPKCS11 log file (see "Logs" above) and verify:
  * `fxpkcs11.cfg` path (default: `/etc/fxpkcs11.cfg`), or `FXPKCS11_CFG` if overridden
  * `client.p12` and `.cer` files are in the same directory as `fxpkcs11.cfg`
  * `PKCS11_P12` is set correctly (start a new shell and run: `echo "$PKCS11_P12"`)

Validate PKCS #11 operations:

* Run `PKCS11Manager` and confirm you can authenticate and perform a simple action (e.g., generate random data).
* If authentication fails, verify the PKCS #11 PIN is correct. To update the PKCS #11 PIN, log in to the CryptoHub dashboard, navigate to the **Identity and Access** menu, and select the **Applications & Partitions** tab. Find the application you deployed, and in the **Manage** section, select the **Authentication** button. This opens a dialog where you can change the PIN/password for the endpoint.

> [!NOTE]
>
> The PKCS #11 PIN is located in the `<CRYPTO-OPR-PASS>` parameter in `fxpkcs11.cfg`. Copy this PIN value to your clipboard — you will need to paste it into Axway VA in the next step.
>
> After copying the PIN, comment out the `<CRYPTO-OPR-PASS>` line in `fxpkcs11.cfg`:
>
> ```cfg title="fxpkcs11.cfg" theme={null}
> # <CRYPTO-OPR-PASS>your-pin-here</CRYPTO-OPR-PASS>
> ```
>
> For PKCS #11 integrations, the PIN is always configured in Axway VA rather than in the FXPKCS11 configuration file.
