> ## 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 the FxPKCS11 module

> Procedural guide to install and configure Futurex PKCS #11 on the machine running OpenVPN Access Server.

<Steps>
  <Step>
    Download the **FxPKCS11** package from your CryptoHub deployment (the ZIP file from the previous step).
  </Step>

  <Step>
    Move the FxPKCS11 package to the Access Server host (the system needs access to CryptoHub to use external keys).
  </Step>
</Steps>

## Install FxPKCS11 on the Access Server host

Perform the following steps to install and configure FxPKCS11 on your Access Server Linux host.

### Step 1: Extract the CryptoHub package and create the FxPKCS11 directory

<Steps>
  <Step>
    Connect to the Access Server console and get root privileges.
  </Step>

  <Step>
    Transfer the ZIP file from CryptoHub to the server.
  </Step>

  <Step>
    Transfer the ZIP file downloaded from CryptoHub to the server.
  </Step>

  <Step>
    Extract the ZIP file. The ZIP contains:

    * `PKCS11Manager`: Program to test the connection to the CryptoHub and perform basic functions through the FxPKCS11 module (login, RNG, etc.)
    * `configTest`: Program to test configuration and connection to the CryptoHub.
    * `libfxpkcs11.so`: FxPKCS11 module.
    * `fxpkcs11.cfg`: Preconfigured FxPKCS11 configuration file for connecting/authenticating to CryptoHub.
    * `client-cert.pem`: Client TLS certificate.
    * `client.p12`: Full Client PKI in encrypted PKCS #12 format (CA chain + client cert + client private key).
    * `ca-chain.pem`: CA certificate bundle (Futurex Test CAs + auto-generated service CA).
    * `CryptoHub 1234567890.cer`: Auto-generated self-signed CA certificate used to issue client endpoint TLS certs (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 certs (ECC or RSA, based on the algorithm configured for the connection pair).

    <Tip>
      Ensure the contents are extracted into a dedicated directory (e.g., `/root/cryptohub-extract`) to avoid mixing files with other content in the same location.
    </Tip>
  </Step>

  <Step>
    Create the following directory:

    ```shell expandable lines wrap title="Shell" theme={null}
    mkdir /usr/local/lib/fxpkcs11
    ```
  </Step>
</Steps>

### Step 2: Move the extracted files

<Steps>
  <Step>
    Move the extracted files to `/usr/local/lib/fxpkcs11`:

    ```shell expandable lines wrap title="Shell" theme={null}
    cp PKCS11Manager ca-chain.pem client-cert.pem client.p12 configTest fxpkcs11.cfg libfxpkcs11.so CryptoHub*.cer Futurex*.cer /usr/local/lib/fxpkcs11
    ```
  </Step>

  <Step>
    The config references the following files by relative path, so they must all be in the same directory as `fxpkcs11.cfg`. Move them to `/etc` (the default expected location):

    * `fxpkcs11.cfg`
    * `client.p12`
    * `CryptoHub <number>.cer`
    * `Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer`

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

### Optional: Use a custom configuration location

If you prefer to store the configuration file elsewhere, define the environment variable. **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
```

**Certificate paths in `fxpkcs11.cfg`**

By default, the FxPKCS11 module expects certificate files to be in the same directory as the `fxpkcs11.cfg` file (whether at the default `/etc/` location or your custom location via `FXPKCS11_CFG`). You can customize the paths to your certificate files directly in the `fxpkcs11.cfg` file by modifying the following settings:

* `PROD-TLS-KEY`: Path to the `client.p12` PKCS#12 file
* `PROD-TLS-CA`: Path to the `CryptoHub 1234567890.cer` file
* `PROD-TLS-CA`: Path to the `Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer` file (depending on your CryptoHub connection type)

### Step 3: Enable automatic PIN loading (required)

Automatic PIN loading lets the PKCS#11 library authenticate without manual PIN entry.

<Steps>
  <Step>
    Extract the PIN value from `fxpkcs11.cfg` (between `<CRYPTO-OPR-PASS>` and `</CRYPTO-OPR-PASS>`) and write it to a file:

    ```shell expandable lines wrap title="Shell" theme={null}
    grep CRYPTO-OPR-PASS /etc/fxpkcs11.cfg | sed 's/.*<CRYPTO-OPR-PASS>\s*\(.*\)\s*<\/CRYPTO-OPR-PASS>.*/\1/' > /root/pkcs11-pin.txt
    ```
  </Step>

  <Step>
    Confirm the file contains only the PIN value:

    ```shell expandable lines wrap title="Shell" theme={null}
    cat /root/pkcs11-pin.txt
    ```
  </Step>

  <Step>
    For security, remove the `<CRYPTO-OPR-PASS>` entry from `/etc/fxpkcs11.cfg`.
  </Step>
</Steps>

<Tip>
  See the next page for configuring the `openssl.cnf` to use this PIN file: [Install and configure the pkcs11-provider module](./Install_and_configure_the_pkcs11-provider_module.mdx).
</Tip>

### Step 4: Configure secrets (PKCS #12 password)

<Steps>
  <Step>
    Extract the password from `fxpkcs11.cfg` (between `<PROD-TLS-KEY-PASS>` and `</PROD-TLS-KEY-PASS>`) and write it to a file:

    ```shell expandable lines wrap title="Shell" theme={null}
    echo "export PKCS11_P12=$(grep PROD-TLS-KEY-PASS /etc/fxpkcs11.cfg | sed 's/.*<PROD-TLS-KEY-PASS>\s*\(.*\)\s*<\/PROD-TLS-KEY-PASS>.*/\1/')" > /etc/profile.d/fxpkcs11.sh
    ```
  </Step>

  <Step>
    Confirm the file contains `export PKCS11_P12=password` where password is the password value between `<PROD-TLS-KEY-PASS>` and `</PROD-TLS-KEY-PASS>`:

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

    * This takes effect for new login shells. To apply it, either:
      * Sign out and back in
      * Start a new shell session
    * Do this prior to validating or running applications that rely on `PKCS11_P12`.
  </Step>
</Steps>

### Step 5: Validate with configTest (recommended)

<Steps>
  <Step>
    Run the configuration test tool:

    ```shell expandable lines wrap title="Shell" theme={null}
    /usr/local/lib/fxpkcs11/configTest
    ```
  </Step>

  <Step>
    Confirm the connection test succeeds.

    If you see:

    ```shell expandable lines wrap title="Shell" theme={null}
    -bash: /usr/local/lib/fxpkcs11/configTest: Permission denied
    ```

    Make the file executable:

    ```shell expandable lines wrap title="Shell" theme={null}
    chmod +x /usr/local/lib/fxpkcs11/configTest
    ```

    Then, run the test again.
  </Step>
</Steps>

### Step 6: Troubleshoot validation issues

If `configTest` fails:

<Steps>
  <Step>
    Check the FxPKCS11 log file:

    * Default location: same directory as `fxpkcs11.cfg`.
    * To customize, modify the `LOG-FILE` setting in `fxpkcs11.cfg`.
  </Step>

  <Step>
    * The PKCS #11 PIN is correct.
    * `fxpkcs11.cfg` resides at `/etc/fxpkcs11.cfg` (or confirm `FXPKCS11_CFG` points to the correct location).
    * All TLS files sit in the same directory as `fxpkcs11.cfg`, or in the location defined in `fxpkcs11.cfg` if you customized the paths:
      * `client.p12`
      * `CryptoHub 1234567890.cer`
      * `Futurex Test Root CA (ECC).cer` (for ECC connections) or `Futurex Test Root SSL CA.cer` (for RSA connections)
    * `PKCS11_P12` has the correct value.
  </Step>
</Steps>