Skip to main content
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:
The endpoint ZIP bundles FXPKCS11 4.59, which does not support the keytool key-generation flow used in this guide and lists 0 keystore entries. Before continuing, obtain FXPKCS11 6.0 rev dc27 or later from the Futurex Portal and use its library file (libfxpkcs11.so on Linux, fxpkcs11.dll on Windows) in place of the bundled one. Keep the other files from the ZIP (fxpkcs11.cfg, the TLS materials, and the test utilities).
Match the library build to your platform. The 6.x download contains one library per architecture and OpenSSL version, such as x64/OpenSSL-3.x/libfxpkcs11.so for 64-bit Linux with OpenSSL 3.x. Each directory holds an info.txt that states the version and revision, and configTest reports the same version once the library is in place.

​
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 JSign in a later 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
    Replace <your-p12-password> 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
The extracted test utilities are not executable after unzipping. Add the execute bit before you run them:
Shell
The ZIP stores configTest and PKCS11Manager without the execute bit, so running either one before this step fails with a permission error.
4
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
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
5
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 JSign in a later 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
    Contents:
    /etc/profile.d/fxpkcs11.sh
    Replace <your-p12-password> 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.
6
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.
7
Quick validation (recommended)Validate config and connection:
  • Run configTest and confirm the connection test succeeds. It prints the slot and token information, including the token label and serial number, and exits with status 0.
  • If it fails, check the FxPKCS11 log file (see “Logs” above) and verify:
    • The <ADDRESS> and <SERVERNAME> tags in fxpkcs11.cfg hold the CryptoHub address. CryptoHub leaves both empty when the endpoint was created without a Hostname value, and the library cannot connect until you fill them in.
    • 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 supply it to keytool and JSign in later steps.After copying the PIN, comment out the <CRYPTO-OPR-PASS> line in fxpkcs11.cfg:
fxpkcs11.cfg
For PKCS #11 integrations, the PIN is always supplied to the signing application rather than stored in the FXPKCS11 configuration file. JSign accepts it through --storepass, and keytool prompts for it as the KeyStore password.

​
Java and OpenSSL installed on the same device

If you install Java and OpenSSL on the same system, refer to the Using OpenSSL and Java guide.