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

> Platform-specific instructions for installing and configuring the Futurex PKCS #11 library.

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:

<Steps>
  <Step>
    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><code>PKCS11Manager.exe</code></td>
          <td>Program to test the connection to the CryptoHub and perform basic functions through the <strong>FXPKCS11</strong> module, such as logging in and generating random data.</td>
        </tr>

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

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

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

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

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

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

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

        <tr>
          <td><code>Futurex Test Root CA (ECC).cer</code> or <code>Futurex Test Root SSL CA.cer</code></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>

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

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

  <Step>
    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 EJBCA 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`.
    </Warning>
  </Step>

  <Step>
    **Logs**

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

  <Step>
    **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.
  </Step>
</Steps>

## Linux

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

<Steps>
  <Step>
    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><code>PKCS11Manager</code></td>
          <td>Program to test the connection to the CryptoHub and perform basic functions through the <strong>FXPKCS11</strong> module, such as logging in and generating random data.</td>
        </tr>

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

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

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

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

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

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

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

        <tr>
          <td><code>Futurex Test Root CA (ECC).cer</code> or <code>Futurex Test Root SSL CA.cer</code></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>

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

  <Step>
    <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`
    </Warning>

    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>

  <Step>
    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 EJBCA 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`.
    </Warning>
  </Step>

  <Step>
    **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>

  <Step>
    **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.
  </Step>
</Steps>

<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 EJBCA 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 EJBCA rather than in the FXPKCS11 configuration file.
</Note>