> ## 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 installation and configuration of Futurex PKCS #11 on the Linux host that runs step-ca.
Install **Futurex PKCS #11 (FXPKCS11)** on the Linux host that runs step-ca. Both runtimes in this integration load the same module from the same directory: the host toolchain uses it for key generation and signing checks, and the `smallstep/step-ca:hsm` container mounts the directory read-only.
This page places `fxpkcs11.cfg` and its TLS files in `/usr/local/lib/fxpkcs11` and rewrites the configuration to reference them by absolute path. Other CryptoHub integration guides put `fxpkcs11.cfg` in `/etc`, where the module finds it by default. Absolute paths in one directory are required here for two reasons: the module otherwise resolves `PROD-TLS-KEY` and `PROD-TLS-CA` relative to the current working directory, which differs between your shell and the container, and one mounted directory carries the whole configuration into the container unchanged. Do not split the configuration file from its TLS files.
## Step 1: Extract the package and create the FXPKCS11 directory
Connect to the step-ca host console and get root privileges.
Transfer the ZIP file you downloaded from CryptoHub to the host.
Extract the ZIP file. The ZIP contains the following files:
* `PKCS11Manager`: 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`: Program to test the configuration and connection to the CryptoHub.
* `libfxpkcs11.so`: The Futurex PKCS #11 library file.
* `fxpkcs11.cfg`: Preconfigured FXPKCS11 configuration file for connecting and authenticating to CryptoHub.
* `client-cert.pem`: Client TLS certificate.
* `client.p12`: Full client PKI in encrypted PKCS #12 format, containing the CA chain, client certificate, and client private key.
* `ca-chain.pem`: CA certificate bundle.
* `CryptoHub .cer`: Auto-generated self-signed CA certificate used to issue client endpoint TLS certificates. The number is random per deployment.
* `Futurex Test Root CA (ECC).cer` or `Futurex Test Root SSL CA.cer`: Futurex Test Root CA for the embedded Futurex Test TLS certificates, ECC or RSA based on the algorithm configured for the connection pair.
Extract the contents into a dedicated directory, for example `/root/cryptohub-extract`, to avoid mixing the files with other content.
Create the FXPKCS11 directory:
```shell expandable lines wrap title="Shell" theme={null}
sudo mkdir -p /usr/local/lib/fxpkcs11
```
## Step 2: Move the extracted files
Move every extracted file, including `fxpkcs11.cfg` and the TLS material, to `/usr/local/lib/fxpkcs11`:
```shell expandable lines wrap title="Shell" theme={null}
sudo cp PKCS11Manager configTest libfxpkcs11.so fxpkcs11.cfg client-cert.pem client.p12 ca-chain.pem 'CryptoHub '*.cer 'Futurex Test Root '*.cer /usr/local/lib/fxpkcs11/
```
The `CryptoHub *.cer` and `Futurex Test Root *.cer` wildcards match the files regardless of the number or the ECC/RSA wording. If your shell does not expand globs, substitute the exact file names from your extracted package.
Add the execute bit to the test utilities. They are not executable after unzipping:
```shell expandable lines wrap title="Shell" theme={null}
sudo chmod +x /usr/local/lib/fxpkcs11/configTest /usr/local/lib/fxpkcs11/PKCS11Manager
```
## Step 3: Rewrite the TLS paths to absolute paths
The generated `fxpkcs11.cfg` references its TLS material by file name only, which the module resolves relative to the current working directory. Rewrite those three values to absolute paths in `/usr/local/lib/fxpkcs11`.
Open the configuration file:
```shell expandable lines wrap title="Shell" theme={null}
sudo nano /usr/local/lib/fxpkcs11/fxpkcs11.cfg
```
Find the `PROD-TLS-KEY` and the two `PROD-TLS-CA` entries in the `` block. As generated, they look similar to the following:
```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
client.p12
CryptoHub 1234567890.cer
Futurex Test Root CA (ECC).cer
```
Replace each value with its absolute path under `/usr/local/lib/fxpkcs11`, keeping your own file names:
```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
/usr/local/lib/fxpkcs11/client.p12
/usr/local/lib/fxpkcs11/CryptoHub 1234567890.cer
/usr/local/lib/fxpkcs11/Futurex Test Root CA (ECC).cer
```
Substitute your own file names. The `CryptoHub .cer` number is generated per deployment, and the Futurex Test Root file is `Futurex Test Root CA (ECC).cer` for ECC connection pairs or `Futurex Test Root SSL CA.cer` for RSA connection pairs. List the directory to confirm the exact names:
```shell expandable lines wrap title="Shell" theme={null}
ls /usr/local/lib/fxpkcs11/*.cer
```
Point **FXPKCS11\_CFG** at the configuration file so the module finds it outside the default `/etc` location:
```shell expandable lines wrap title="Shell" theme={null}
export FXPKCS11_CFG=/usr/local/lib/fxpkcs11/fxpkcs11.cfg
```
This export applies to the current shell only. Add it to your shell profile so the host toolchain commands in the following pages find the configuration in every session. The container receives the same value through a `-e FXPKCS11_CFG=...` flag in [Start step-ca](/Integrations/CryptoHub/Certificate_Authority/Smallstep_step-ca/Start_step-ca).
## Step 4: Record the PKCS #11 PIN
step-ca and the step-kms-plugin supply the PKCS #11 PIN in the key management system URI rather than reading it from `fxpkcs11.cfg`. Write it to a protected file so you can reference it without retyping it.
Extract the PIN value from `fxpkcs11.cfg`, which sits between `` and ``, and write it to a file:
```shell expandable lines wrap title="Shell" theme={null}
sudo sh -c "grep CRYPTO-OPR-PASS /usr/local/lib/fxpkcs11/fxpkcs11.cfg | sed 's/.*\s*\(.*\)\s*<\/CRYPTO-OPR-PASS>.*/\1/' > /root/pkcs11-pin.txt"
sudo chmod 600 /root/pkcs11-pin.txt
```
Confirm the file contains only the PIN value:
```shell expandable lines wrap title="Shell" theme={null}
sudo cat /root/pkcs11-pin.txt
```
Leave the `` entry in place in `fxpkcs11.cfg`. `configTest` and `PKCS11Manager` read the PIN from the configuration file, and the validation steps in this guide use them. Restrict the file instead:
```shell expandable lines wrap title="Shell" theme={null}
sudo chmod 600 /usr/local/lib/fxpkcs11/fxpkcs11.cfg
```
## Step 5: Configure the PKCS #12 password
The module needs the password for `client.p12` to build its mutual TLS context. Supply it through the `PKCS11_P12` environment variable rather than leaving it in the configuration file.
Extract the password from `fxpkcs11.cfg`, which sits between `` and ``, and write it to a profile script:
```shell expandable lines wrap title="Shell" theme={null}
sudo sh -c "echo \"export PKCS11_P12=\$(grep PROD-TLS-KEY-PASS /usr/local/lib/fxpkcs11/fxpkcs11.cfg | sed 's/.*\s*\(.*\)\s*<\/PROD-TLS-KEY-PASS>.*/\1/')\" > /etc/profile.d/fxpkcs11.sh"
```
Replace the `` value in `fxpkcs11.cfg` with `env:PKCS11_P12` so the module reads the variable:
```cfg expandable lines wrap title="fxpkcs11.cfg" theme={null}
env:PKCS11_P12
```
Confirm the profile script contains the expected value:
```shell expandable lines wrap title="Shell" theme={null}
cat /etc/profile.d/fxpkcs11.sh
```
The file contains one line in the form `export PKCS11_P12=`, where the password matches the value that was between `` and ``.
Start a new login shell so the variable takes effect, then confirm it is populated:
```shell expandable lines wrap title="Shell" theme={null}
echo "$PKCS11_P12"
```
`/etc/profile.d` scripts run for login shells only. A variable set this way is not present in a non-login shell, in a `cron` job, or under `sudo` unless you pass it through explicitly. Confirm `echo "$PKCS11_P12"` prints a value in the shell you intend to use before you run the container in [Start step-ca](/Integrations/CryptoHub/Certificate_Authority/Smallstep_step-ca/Start_step-ca), where the value is passed to Docker.
## Step 6: Validate with configTest
Run the configuration test tool:
```shell expandable lines wrap title="Shell" theme={null}
/usr/local/lib/fxpkcs11/configTest
```
Confirm the connection test succeeds. `configTest` reports the slot, the token label, the HSM serial number, and the FXPKCS11 library version.
The tool connects and reports slot `Futurex 0` with token label `Futurex`, along with your appliance's serial number and FXPKCS11 firmware version. The validated run reported FXPKCS11 `5.23`.
If `configTest` fails, check the following:
* The FXPKCS11 log file. Its location comes from the `LOG-FILE` setting in `fxpkcs11.cfg`. If the module cannot write to the configured path, it falls back to `/tmp/fxpkcs11.log`.
* `FXPKCS11_CFG` points at `/usr/local/lib/fxpkcs11/fxpkcs11.cfg`.
* The `PROD-TLS-KEY` and `PROD-TLS-CA` values are absolute paths that match the file names present in `/usr/local/lib/fxpkcs11`.
* `PKCS11_P12` holds the correct password. Start a new shell and run `echo "$PKCS11_P12"`.
* The PKCS #11 PIN is correct. To change it, log in to the CryptoHub dashboard, go to **Identity and Access > Applications & Partitions**, find the application you deployed, and under **Manage** select **\[ Authentication ]**.