Skip to main content

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.

1
Download the FxPKCS11 package from your CryptoHub deployment (the ZIP file from the previous step).
2
Move the FxPKCS11 package to the Access Server host (the system needs access to CryptoHub to use external keys).

​
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

1
Connect to the Access Server console and get root privileges.
2
Transfer the ZIP file from CryptoHub to the server.
3
Transfer the ZIP file downloaded from CryptoHub to the server.
4
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).
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.
5
Create the following directory:
Shell
mkdir /usr/local/lib/fxpkcs11

​
Step 2: Move the extracted files

1
Move the extracted files to /usr/local/lib/fxpkcs11:
Shell
cp PKCS11Manager ca-chain.pem client-cert.pem client.p12 configTest fxpkcs11.cfg libfxpkcs11.so CryptoHub*.cer Futurex*.cer /usr/local/lib/fxpkcs11
2
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
sudo mv fxpkcs11.cfg client.p12 CryptoHub*.cer Futurex*.cer /etc/

​
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
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.
1
Extract the PIN value from fxpkcs11.cfg (between <CRYPTO-OPR-PASS> and </CRYPTO-OPR-PASS>) and write it to a file:
Shell
grep CRYPTO-OPR-PASS /etc/fxpkcs11.cfg | sed 's/.*<CRYPTO-OPR-PASS>\s*\(.*\)\s*<\/CRYPTO-OPR-PASS>.*/\1/' > /root/pkcs11-pin.txt
2
Confirm the file contains only the PIN value:
Shell
cat /root/pkcs11-pin.txt
3
For security, remove the <CRYPTO-OPR-PASS> entry from /etc/fxpkcs11.cfg.
See the next page for configuring the openssl.cnf to use this PIN file: Install and configure the pkcs11-provider module.

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

1
Extract the password from fxpkcs11.cfg (between <PROD-TLS-KEY-PASS> and </PROD-TLS-KEY-PASS>) and write it to a file:
Shell
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
2
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
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.
1
Run the configuration test tool:
Shell
/usr/local/lib/fxpkcs11/configTest
2
Confirm the connection test succeeds.If you see:
Shell
-bash: /usr/local/lib/fxpkcs11/configTest: Permission denied
Make the file executable:
Shell
chmod +x /usr/local/lib/fxpkcs11/configTest
Then, run the test again.

​
Step 6: Troubleshoot validation issues

If configTest fails:
1
Check the FxPKCS11 log file:
  • Default location: same directory as fxpkcs11.cfg.
  • To customize, modify the LOG-FILE setting in fxpkcs11.cfg.
2
  • 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.