> ## 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 and configure Futurex PKCS #11 on the Linux host that runs strongSwan, rewrite the TLS file paths, and confirm slot enumeration.

Install **Futurex PKCS #11 (FXPKCS11)** on the Linux host where you installed strongSwan, using the zip file you downloaded in [Deploy client endpoint](/Integrations/CryptoHub/VPN/strongSwan/Deploy_client_endpoint).

## Step 1: Extract the package and install the library

<Steps>
  <Step>
    Extract the zip file downloaded from CryptoHub. It contains the Futurex PKCS #11 library and the material the library needs to authenticate to the appliance:

    * `libfxpkcs11.so` — the Futurex PKCS #11 library.
    * `fxpkcs11.cfg` — the configuration file for the library.
    * `PKCS11Manager` — a program to test the connection to the CryptoHub and perform basic functions through the FXPKCS11 module, such as logging in and generating random data.
    * `configTest` — a program to test the configuration and connection to the CryptoHub.
    * `client.p12` — the full client PKI in encrypted PKCS #12 format, containing the CA chain, client certificate, and client private key.
    * `client-cert.pem` — the client TLS certificate.
    * `ca-chain.pem` — the CA certificate bundle.
    * `CryptoHub <serial>.cer` — an auto-generated self-signed CA certificate used to issue client endpoint TLS certificates. The file name carries your appliance's serial number.
    * `Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer` — the Futurex Test Root CA for embedded Futurex Test TLS certificates. Only one is included, depending on the algorithm configured for the connection pair.
  </Step>

  <Step>
    Move the library and the test utilities to a system library path so charon can load them:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo mkdir -p /usr/local/lib/fxpkcs11
    sudo cp libfxpkcs11.so PKCS11Manager configTest /usr/local/lib/fxpkcs11/
    sudo chmod 755 /usr/local/lib/fxpkcs11/libfxpkcs11.so
    sudo chmod +x /usr/local/lib/fxpkcs11/configTest /usr/local/lib/fxpkcs11/PKCS11Manager
    ```

    <Note>
      `configTest` and `PKCS11Manager` are not executable after the zip is extracted. Without the `chmod +x`, both report `Permission denied` when you run the validation steps later on this page.
    </Note>

    <Warning>
      Install the library system-wide rather than under `$HOME`. charon runs as a system daemon and cannot read a per-user directory.
    </Warning>
  </Step>
</Steps>

## Step 2: Place the configuration and TLS files

The Futurex PKCS #11 module expects `fxpkcs11.cfg` in the `/etc` directory by default. The configuration references `client.p12` and the two CA certificates, so those files must resolve from wherever the module runs.

This guide keeps the configuration at `/etc/fxpkcs11.cfg` and the TLS material in `/etc/fxpkcs11/`:

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

## Step 3: Rewrite the TLS paths to absolute paths

The configuration file ships with the TLS files named by relative path. Relative names resolve against the **working directory** of whatever process loads the module, not against the location of `fxpkcs11.cfg`. Because charon's working directory differs from your shell's, the files must either sit in the directory the process runs from or be referenced by absolute path. This guide uses absolute paths.

Rewrite the three entries in `/etc/fxpkcs11.cfg`:

```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
<PROD-TLS-KEY> /etc/fxpkcs11/client.p12 </PROD-TLS-KEY>
<PROD-TLS-CA> /etc/fxpkcs11/CryptoHub 1234567890.cer </PROD-TLS-CA>
<PROD-TLS-CA> /etc/fxpkcs11/Futurex Test Root CA (ECC).cer </PROD-TLS-CA>
```

Substitute your own appliance serial in the `CryptoHub <serial>.cer` file name, and use whichever `Futurex Test Root` certificate your zip contained.

<Note>
  Two separate `<PROD-TLS-CA>` entries are correct. The module expects one entry per CA certificate, so both lines are required.
</Note>

Alternatively, store the configuration elsewhere and set `FXPKCS11_CFG`. If you do, the TLS files must still resolve, either by absolute path as above or by sitting in the working directory:

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

## Step 4: Record the PKCS #11 PIN

The PKCS #11 PIN is the value of the `<CRYPTO-OPR-PASS>` parameter in `fxpkcs11.cfg`. Copy it now: you need it for the key-generation commands in [Create the HSM-backed CA and responder keys](/Integrations/CryptoHub/VPN/strongSwan/Create_the_HSM_backed_CA_and_responder_keys) and for the `secrets` section of `swanctl.conf` later.

<Warning>
  Leave the `<CRYPTO-OPR-PASS>` entry in place in `fxpkcs11.cfg` for now. `configTest` and `PKCS11Manager` read the PIN from the configuration file, so removing it before the validation steps on this page makes them fail. You comment it out in step 8, after validation passes.
</Warning>

## Step 5: Configure the PKCS #12 password

The PKCS #12 password is the value of `<PROD-TLS-KEY-PASS>` in `fxpkcs11.cfg`. Futurex recommends copying this password, then replacing the value in `fxpkcs11.cfg` with `env:PKCS11_P12`.

Set `PKCS11_P12` system-wide:

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

Add the following, replacing `your-p12-password` with the password you copied:

```shell expandable lines wrap title="Shell" theme={null}
export PKCS11_P12=your-p12-password
```

<Warning>
  A variable set in `/etc/profile.d/` reaches new **login shells** only. It does **not** reach a systemd-managed daemon such as charon. If you use `env:PKCS11_P12`, also add it to the strongSwan service environment, for example with `sudo systemctl edit strongswan-starter` and an `Environment=PKCS11_P12=...` line. Otherwise leave the password in `fxpkcs11.cfg` with the file mode set to `600`.
</Warning>

## Step 6: Set the FXPKCS11 log path

The log path comes from the `LOG-FILE` setting in `fxpkcs11.cfg`. A relative value resolves against the working directory of the process that loaded the module, and charon's working directory is not writable. Set an explicit absolute path:

```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
<LOG-FILE>/tmp/fxpkcs11.log</LOG-FILE>
```

This log is the primary diagnostic for the rest of the guide. See [Troubleshooting](/Integrations/CryptoHub/VPN/strongSwan/Troubleshooting) for how to read it.

## Step 7: Validate with configTest

```shell expandable lines wrap title="Shell" theme={null}
cd /usr/local/lib/fxpkcs11
sudo env FXPKCS11_CFG=/etc/fxpkcs11.cfg ./configTest
```

<Check>
  The connection test succeeds and the slot list includes the CryptoHub token.
</Check>

If it fails, read the FXPKCS11 log at the `LOG-FILE` path from step 6, then verify:

* The `fxpkcs11.cfg` path (default `/etc/fxpkcs11.cfg`), or `FXPKCS11_CFG` if you overrode it.
* `client.p12` and the `.cer` files resolve from the paths written in the configuration.
* `PKCS11_P12` is set correctly, if you used it. Start a new shell and run `echo "$PKCS11_P12"`. An empty value passes through silently.
* The host can reach the CryptoHub address and port named in `fxpkcs11.cfg`.

## Step 8: Confirm the token, the version, and login

<Steps>
  <Step>
    Confirm the token and the library version:

    ```shell expandable lines wrap title="Shell" theme={null}
    FXPKCS11_CFG=/etc/fxpkcs11.cfg \
    pkcs11-tool --module /usr/local/lib/fxpkcs11/libfxpkcs11.so --show-info --list-slots
    ```

    <Check>
      The `Library` line reads `FxPKCS11 (ver 6.1)` or later, and `Cryptoki version` reads `3.0`. The slot list shows a token whose flags include `token initialized` and `PIN initialized`. If the token is not initialized, initialize it in the CryptoHub before continuing.
    </Check>

    <Note>
      Read the version from this runtime output rather than from `info.txt`, which is not reliable for this library family.
    </Note>
  </Step>

  <Step>
    Validate login and PKCS #11 operations:

    ```shell expandable lines wrap title="Shell" theme={null}
    read -rsp "HSM PIN: " HSM_PIN
    echo

    FXPKCS11_CFG=/etc/fxpkcs11.cfg \
    pkcs11-tool \
    --module /usr/local/lib/fxpkcs11/libfxpkcs11.so \
    --slot 0 \
    --login --pin "$HSM_PIN" \
    --list-objects

    unset HSM_PIN
    ```

    <Check>
      The command completes without an authentication error. On a new endpoint the object list is empty, which is expected; you create the keys in a later step.
    </Check>

    <Note>
      Reading the PIN with `read -rsp` keeps it out of the page and out of your shell history. Every later command in this guide that needs the PIN uses the same idiom.
    </Note>
  </Step>

  <Step>
    Now that validation has passed, comment out the `<CRYPTO-OPR-PASS>` line in `fxpkcs11.cfg`:

    ```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
    # <CRYPTO-OPR-PASS>your-pin-here</CRYPTO-OPR-PASS>
    ```

    For PKCS #11 integrations, the PIN is always configured in the third-party application rather than in the FXPKCS11 configuration file. For strongSwan, that means the `pin` value in the `secrets` section of `swanctl.conf`.
  </Step>
</Steps>