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.

Install Futurex PKCS #11 (FXPKCS11) on the machine where you installed the third-party application. Select one of the following operating systems and perform the instructions:

​
Windows

Perform the following instructions to install FXPKCS11 on Windows:
1
Extract the Endpoint zip file downloaded in your browser after deploying the service in CryptoHub. The zip file contains the following files:
FileDescription
PKCS11Manager.exeProgram to test the connection to the CryptoHub and perform basic functions through the FXPKCS11 module, such as logging in and generating random data.
ca-chain.pemCA certificate bundle
client-cert.pemClient TLS certificate
client.p12Full Client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key)
configTest.exeProgram to test the configuration and connection to the CryptoHub
fxpkcs11.cfgConfiguration file for the Futurex PKCS #11 library
fxpkcs11.dllThe Futurex PKCS #11 library file.
CryptoHub <number>.cerAuto-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.cerFuturex Test Root CA for embedded Futurex Test TLS certs (ECC or RSA, based on the algorithm configured for the connection pair)
2
Move all of the preceding FXPKCS11 files to C:\Program Files\Futurex\fxpkcs11. Create the Futurex\fxpkcs11 directory as an administrator.
3
The Futurex PKCS #11 module expects to find the FXPKCS11 configuration file (fxpkcs11.cfg) in the C:\Program Files\Futurex\fxpkcs11 directory by default. If you want to store the config elsewhere, set the FXPKCS11_CFG environment variable to the full path of the config file. Ensure the TLS files referenced in the config are also in the same directory.
4
Configure secrets (recommended: use an environment variable for the PKCS #12 password).PKCS #11 PIN
  • Find it in CRYPTO-OPR-PASS inside fxpkcs11.cfg.
  • Copy the PIN to your clipboard, then comment out the CRYPTO-OPR-PASS line. You will configure this PIN in OpenSSL in the next step.
PKCS #12 password
  • Find it in PROD-TLS-KEY-PASS inside fxpkcs11.cfg.
  • We recommend copying this password, then replacing the value in fxpkcs11.cfg with env:PKCS11_P12.
  • Set the machine-wide environment variable in an elevated Command Prompt (Run as Administrator):
    Shell
    setx PKCS11_P12 safest /M
    Replace safest with the actual P12 password you copied to your clipboard.
Newly set/updated environment variables are only visible to new processes. Close and reopen Command Prompt/PowerShell (or log out/in) before validating or running applications that rely on PKCS11_P12.
5
Logs
  • Default FxPKCS11 log location: C:\Program Files\Futurex\fxpkcs11
  • To customize, modify the <LOG-FILE> definition in fxpkcs11.cfg.
6
Quick validation (recommended)Validate config and connection:
  • Run configTest.exe from C:\Program Files\Futurex\fxpkcs11.
  • Confirm the connection test succeeds.
  • If it fails, check the FxPKCS11 log file (see “Logs” above) and verify the PKCS #12 password and TLS materials are in the expected locations.
Validate PKCS #11 operations:
  • Run PKCS11Manager.exe from C:\Program Files\Futurex\fxpkcs11.
  • Confirm you can authenticate and perform a simple action (e.g., generate random data).
  • If authentication fails, verify the PKCS #11 PIN is correct. To update the PKCS #11 PIN, log in to the CryptoHub dashboard, navigate to the Identity and Access menu, and select the Applications & Partitions tab. Find the application you deployed, and in the Manage section, select the Authentication button. This opens a dialog where you can change the PIN/password for the endpoint.

​
Linux

Perform the following instructions to install FXPKCS11 on Linux:
1
Extract the zip file downloaded from CryptoHub. The zip file contains the following files:
FileDescription
PKCS11ManagerProgram to test the connection to the CryptoHub and perform basic functions through the FXPKCS11 module, such as logging in and generating random data.
ca-chain.pemCA certificate bundle
client-cert.pemClient TLS certificate
client.p12Full Client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key)
configTestProgram to test the configuration and connection to the CryptoHub
fxpkcs11.cfgConfiguration file for the Futurex PKCS #11 library
libfxpkcs11.soThe Futurex PKCS #11 library file.
CryptoHub <number>.cerAuto-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.cerFuturex Test Root CA for embedded Futurex Test TLS certs (ECC or RSA, based on the algorithm configured for the connection pair)
2
Move all the preceding files to one of the following locations:
  • To make the FXPKCS11 library accessible system-wide, use sudo to move the files to the /usr/local/lib/fxpkcs11 directory.
  • To make the FXPKCS11 library accessible only for the current user, move the files to the $HOME/lib/fxpkcs11 directory.
3
IMPORTANTThe Futurex PKCS #11 module expects fxpkcs11.cfg in the /etc directory by default. The config references the following files by relative path, so they must all be in the same directory as fxpkcs11.cfg:
  • client.p12
  • CryptoHub <number>.cer
  • Futurex Test Root CA (ECC).cer or Futurex Test Root SSL CA.cer
Use the following command to move fxpkcs11.cfg and the TLS files to /etc:
Shell
sudo mv fxpkcs11.cfg client.p12 CryptoHub*.cer Futurex*.cer /etc/
Alternatively, store the config elsewhere and set FXPKCS11_CFG. 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
4
Configure secrets (recommended: use an environment variable for the PKCS #12 password).PKCS #11 PIN
  • Find it in CRYPTO-OPR-PASS inside fxpkcs11.cfg.
  • Copy the PIN to your clipboard, then comment out the CRYPTO-OPR-PASS line. You will configure this PIN in OpenSSL in the next step.
PKCS #12 password
  • Find it in PROD-TLS-KEY-PASS inside fxpkcs11.cfg.
  • We recommend copying this password, then replacing the value in fxpkcs11.cfg with env:PKCS11_P12.
  • Set PKCS11_P12 system-wide (RHEL or Debian/Ubuntu) by creating:
    Shell
    sudo nano /etc/profile.d/fxpkcs11.sh
    Contents:
    /etc/profile.d/fxpkcs11.sh
    export PKCS11_P12=safest
    Replace safest with the actual P12 password you copied to your clipboard.
This takes effect for new login shells. Log out/in or start a new shell session before validating or running applications that rely on PKCS11_P12.
5
Logs
  • Default FxPKCS11 log location: the current directory (i.e., the same directory as fxpkcs11.cfg)
  • To customize, modify the <LOG-FILE> definition in fxpkcs11.cfg.
6
Quick validation (recommended)Validate config and connection:
  • Run configTest and confirm the connection test succeeds.
  • If it fails, check the FxPKCS11 log file (see “Logs” above) and verify:
    • fxpkcs11.cfg path (default: /etc/fxpkcs11.cfg), or FXPKCS11_CFG if overridden
    • client.p12 and .cer files are in the same directory as fxpkcs11.cfg
    • PKCS11_P12 is set correctly (start a new shell and run: echo "$PKCS11_P12")
Validate PKCS #11 operations:
  • Run PKCS11Manager and confirm you can authenticate and perform a simple action (e.g., generate random data).
  • If authentication fails, verify the PKCS #11 PIN is correct. To update the PKCS #11 PIN, log in to the CryptoHub dashboard, navigate to the Identity and Access menu, and select the Applications & Partitions tab. Find the application you deployed, and in the Manage section, select the Authentication button. This opens a dialog where you can change the PIN/password for the endpoint.
The PKCS #11 PIN is located in the <CRYPTO-OPR-PASS> parameter in fxpkcs11.cfg. Copy this PIN value to your clipboard — you will need to paste it into OpenSSL in the next step.After copying the PIN, 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 OpenSSL rather than in the FXPKCS11 configuration file.