Skip to main content
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

1
Connect to the step-ca host console and get root privileges.
2
Transfer the ZIP file you downloaded from CryptoHub to the host.
3
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 <number>.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.
4
Create the FXPKCS11 directory:
Shell

​
Step 2: Move the extracted files

1
Move every extracted file, including fxpkcs11.cfg and the TLS material, to /usr/local/lib/fxpkcs11:
Shell
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.
2
Add the execute bit to the test utilities. They are not executable after unzipping:
Shell

​
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.
1
Open the configuration file:
Shell
2
Find the PROD-TLS-KEY and the two PROD-TLS-CA entries in the <KMS> block. As generated, they look similar to the following:
fxpkcs11.cfg
3
Replace each value with its absolute path under /usr/local/lib/fxpkcs11, keeping your own file names:
fxpkcs11.cfg
Substitute your own file names. The CryptoHub <number>.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
4
Point FXPKCS11_CFG at the configuration file so the module finds it outside the default /etc location:
Shell
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.

​
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.
1
Extract the PIN value from fxpkcs11.cfg, which sits between <CRYPTO-OPR-PASS> and </CRYPTO-OPR-PASS>, and write it to a file:
Shell
2
Confirm the file contains only the PIN value:
Shell
Leave the <CRYPTO-OPR-PASS> 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

​
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.
1
Extract the password from fxpkcs11.cfg, which sits between <PROD-TLS-KEY-PASS> and </PROD-TLS-KEY-PASS>, and write it to a profile script:
Shell
2
Replace the <PROD-TLS-KEY-PASS> value in fxpkcs11.cfg with env:PKCS11_P12 so the module reads the variable:
fxpkcs11.cfg
3
Confirm the profile script contains the expected value:
Shell
The file contains one line in the form export PKCS11_P12=<password>, where the password matches the value that was between <PROD-TLS-KEY-PASS> and </PROD-TLS-KEY-PASS>.
4
Start a new login shell so the variable takes effect, then confirm it is populated:
Shell
/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, where the value is passed to Docker.

​
Step 6: Validate with configTest

1
Run the configuration test tool:
Shell
2
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 ].