Skip to main content
This page describes how to deploy the CryptoHub Client Library service, provision a client endpoint, install the CryptoHub-backed PKCS#11 module from the endpoint download, place its configuration file, and verify the installation before you connect a production application.
This guide covers the CryptoHub-backed module (libcryptohub-pkcs11.*). If you installed the legacy fxpkcs11 module (libfxpkcs11.so / fxpkcs11.dll), follow the PKCS#11 developer guide instead.

​
How the module is delivered

Unlike the legacy Host-API libraries (FXPKCS11 and FXCNG), the CryptoHub Client Library reaches CryptoHub over the v2 REST API on port 443. It also ships inside the endpoint download rather than as a standalone package. You deploy a service in CryptoHub, add an endpoint to it, and download a zip file that contains the module, its supporting tools, a pre-filled cryptohub.json, and the TLS material for that endpoint. Deploying the endpoint provisions the identity and connection details the module uses to authenticate. The workflow is therefore:
  1. Deploy the CryptoHub Client Library service and provision an endpoint (on the CryptoHub appliance).
  2. Install the module from the endpoint download (on the application host).
  3. Place cryptohub.json where the module can find it.
  4. Verify the module reaches and authenticates to CryptoHub.

​
Before you start

Make sure you have the following:
  • Access to a CryptoHub appliance (7.2 or later) and permission to deploy a service.
  • Network access from the application host to your CryptoHub appliance over HTTPS on port 443.
  • The operating system and architecture of the application host, so you can select the matching endpoint platform.

​
Step 1: Deploy the service and provision an endpoint

Perform these steps in the CryptoHub web interface. They provision the identity, connection details, and download that the following steps use.
  1. Deploy the CryptoHub Client Library service (from the Service Management store) into CryptoHub. If you already deployed a supported application’s service, use that service instead.
  2. Open the deployed service and navigate to its Endpoints menu. An endpoint is a device authorized to access the service.
  3. In the Manage Endpoints menu, click [ Add New ].
  4. In the Add Endpoint dialog:
    • Enter a Name for the endpoint.
    • Leave the auto-populated CryptoHub Hostname as-is.
    • Select the Platform the module will run on.
  5. Click [ Add Endpoint ]. The browser downloads a zip file that contains a pre-filled cryptohub.json and the TLS material for this endpoint — the connection, authentication, and TLS settings the module uses to reach and authenticate to your CryptoHub instance. Keep this download secure: it is a credential.
To change the authentication credential for an endpoint, go to the Identity and Access menu, select the Applications & Partitions tab, find the application you deployed, and in the Manage section select Authentication.
The CryptoHub Client Library authenticates over the REST API. Confirm that the endpoint’s role has the REST API port enabled. Roles deployed by a service template ship with the Excrypt port only, so if the module reports an authentication failure, add the REST API port to the role under Identity and Access.

​
Step 2: Install the provider library

The module ships inside the endpoint download — you do not need to obtain or install a separate package. Transfer the endpoint zip to the application host and extract it. The zip contains the provider library, the pkcs11-manager utility, the fxchl command-line client, supporting tools, the pre-filled cryptohub.json, and the TLS material for your instance. On Linux, the endpoint zip provides:
  • libcryptohub-pkcs11.so — the PKCS#11 module. This is the module path you point your application at.
  • pkcs11-manager — interactive utility for testing the configuration and exercising PKCS#11 operations.
  • fxchl — the CryptoHub command-line client, used here to verify connectivity and authentication.
  • config-translator, unit-tests — supporting tools.
  • cryptohub.json — your deployment configuration for this endpoint, pre-filled with the connection, authentication, and TLS settings.
  • TLS material — the CA and client TLS files the module uses to establish, and for mutual TLS to authenticate, the connection to CryptoHub.
On Windows, the endpoint zip provides both client modules — cryptohub-pkcs11.dll (PKCS#11) and cryptohub-cng.dll (the CNG Key Storage Provider used by the CNG variant of this integration) — along with pkcs11-manager.exe, fxchl.exe, config-translator.exe, and the CNG tools (cng-install.exe, cng-uninstall.exe, cng-manager.exe), plus the pre-filled cryptohub.json and TLS material. Move the provider library to a location your application’s loader can reach:
PlatformProvider libraryTypical location
Windowscryptohub-pkcs11.dllC:\Program Files\Futurex
Linux and other POSIX systemslibcryptohub-pkcs11.so/usr/local/lib/
macOS (including ARM64)libcryptohub-pkcs11.dylib/usr/local/lib/
Record the absolute path to the installed library. You supply this path to any PKCS#11-consuming application as its module path.
Use the library build that matches both your CPU architecture and your application’s OpenSSL major version. On macOS ARM64, use the ARM64 build. Select the corresponding endpoint platform in Step 1 so the download carries the correct build.
Confirm the CLI runs:

​
Step 3: Place the configuration file

The endpoint download ships a pre-filled cryptohub.json for your instance. Start from that file — it already contains the connection, authentication, and TLS settings for the endpoint you created. Copy it to a runtime location the module searches, or point to it with the CHLIBS_CONFIG environment variable. The runtime file must be named cryptohub.json unless you point to it with CHLIBS_CONFIG. The module searches for its configuration in this order and uses the first file it finds:
  1. The path in the CHLIBS_CONFIG environment variable.
  2. cryptohub.json in the current working directory of the calling process.
  3. ../config/cryptohub.json relative to the current working directory.
  4. A platform-specific static path:
    • Windows: C:\Program Files\Futurex\cryptohub.json, then C:\Program Files\Futurex\config\cryptohub.json, then C:\Futurex\cryptohub.json, then C:\Futurex\config\cryptohub.json.
    • POSIX: /etc/cryptohub.json.
For system-wide POSIX installs, place the configuration at /etc/cryptohub.json. For machine-wide Windows installs, use C:\Program Files\Futurex\cryptohub.json or C:\Program Files\Futurex\config\cryptohub.json. If your application runs from a service account or a custom working directory, setting CHLIBS_CONFIG is often the simplest option:
Set the configuration path (POSIX)
Set the configuration path (Windows)
Set CHLIBS_CONFIG in the environment of the process that loads the module, and restart the consuming service after you set it so the new value takes effect.
You normally do not need to edit the endpoint-provided file. If you configure cryptohub.json by hand, or need to understand any field, see Configuration for the full schema.

​
Step 4: Verify the installation

Use the packaged pkcs11-manager utility to confirm the module loads, reads its configuration, authenticates to CryptoHub, and can see the token before you connect a production application. This is the primary verification tool and is included in the endpoint download. Run it and use its menu to:
  1. Initialize the module.
  2. Log in with the credential from cryptohub.json.
  3. List slots and mechanisms.
  4. Enumerate objects, and optionally generate a key and run a supported cryptographic operation.
pkcs11-manager
Confirm the following:
  • Library info reports the manufacturer as Futurex, the description as CryptoHub PKCS11, and Cryptoki version 3.2.
  • Slot list shows a slot for each PRODUCTION CryptoHub destination in your configuration.
  • List mechanisms returns the mechanisms your CryptoHub service and key store support.
A successful login and slot listing confirms that the module, configuration, credential, and TLS trust are all correct. You can also use the fxchl CLI for a focused connectivity and authentication check:
A successful fxchl status reports the session as authenticated and the server as reachable.
On CryptoHub 7.3.0.x, fxchl service list returns NOT_FOUND. Select the service by UUID instead — the UUID is the global.service_uuid from your cryptohub.json — with fxchl service use --uuid <service-uuid>, then confirm it with fxchl service show.
Where your operating system provides the OpenSC pkcs11-tool utility and it is compatible with the PKCS#11 v3.2 mechanism definitions, you can run the same checks against the installed library. pkcs11-tool is an external tool installed separately (for example, from the opensc package) and is not part of the CryptoHub Client Library:
The authoritative mechanism list is the list the installed library returns for the selected slot. The mechanisms and key sizes in Appendix A can vary by CryptoHub release; policy and key metadata can further restrict operations. Always verify against your own installation.

​
Next steps