Install and configure Futurex PKCS #11

Install Futurex PKCS #11 (FXPKCS11) on the Linux host where you installed strongSwan, using the zip file you downloaded in Deploy client endpoint.

Step 1: Extract the package and install the library

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.

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

Shell

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

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.

Install the library system-wide rather than under $HOME. charon runs as a system daemon and cannot read a per-user directory.

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

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:

fxpkcs11.cfg

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

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

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

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 and for the secrets section of swanctl.conf later.

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.

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

sudo nano /etc/profile.d/fxpkcs11.sh

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

Shell

export PKCS11_P12=your-p12-password

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.

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:

fxpkcs11.cfg

<LOG-FILE>/tmp/fxpkcs11.log</LOG-FILE>

This log is the primary diagnostic for the rest of the guide. See Troubleshooting for how to read it.

Step 7: Validate with configTest

Shell

cd /usr/local/lib/fxpkcs11
sudo env FXPKCS11_CFG=/etc/fxpkcs11.cfg ./configTest

The connection test succeeds and the slot list includes the CryptoHub token.

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.

Confirm the token and the library version:

Shell

FXPKCS11_CFG=/etc/fxpkcs11.cfg \
pkcs11-tool --module /usr/local/lib/fxpkcs11/libfxpkcs11.so --show-info --list-slots

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.

Read the version from this runtime output rather than from info.txt, which is not reliable for this library family.

Validate login and PKCS #11 operations:

Shell

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

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.

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.

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

fxpkcs11.cfg

# <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 1: Extract the package and install the library

​Step 2: Place the configuration and TLS files

​Step 3: Rewrite the TLS paths to absolute paths

​Step 4: Record the PKCS #11 PIN

​Step 5: Configure the PKCS #12 password

​Step 6: Set the FXPKCS11 log path

​Step 7: Validate with configTest

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

Step 1: Extract the package and install the library

Step 2: Place the configuration and TLS files

Step 3: Rewrite the TLS paths to absolute paths

Step 4: Record the PKCS #11 PIN

Step 5: Configure the PKCS #12 password

Step 6: Set the FXPKCS11 log path

Step 7: Validate with configTest

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