> ## 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 and configure the CryptoHub Client Library > Install the CryptoHub Client Library PKCS ## Install the CryptoHub Client Library The CryptoHub Client Library ships inside the endpoint download you generated above; you do not need to obtain or install a separate package. Extract the endpoint zip. It contains the CryptoHub Client Library module and its supporting tools together with a pre-filled `cryptohub.json` and the TLS material for your instance. On **Linux**, the endpoint zip provides: * `libcryptohub-pkcs11.so` -> The CryptoHub PKCS #11 module. This is the module path you point your application at. Move it to a location your application's loader can reach; a common choice is `/usr/local/lib/libcryptohub-pkcs11.so`. * `pkcs11-manager` -> Interactive menu-driven utility for initializing the module, logging in, listing slots and objects, and generating test keys. * `cryptohub.json` -> Your deployment configuration for this endpoint, pre-filled with the connection, authentication, and TLS settings. * TLS material -> The CA files, CA chain, and any endpoint certificate material used to authenticate 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). It also provides `cng-install.exe`, `cng-uninstall.exe`, `cng-manager.exe`, and `pkcs11-manager.exe`, plus the pre-filled `cryptohub.json` and TLS material. ## Configure the connection (`cryptohub.json`) The CryptoHub Client Library reads its connection and authentication settings from a `cryptohub.json` file. Deploying the client endpoint above ships a **pre-filled `cryptohub.json` and the TLS material** for your instance inside the endpoint download. Start from that endpoint-provided `cryptohub.json`: it already contains the connection, UserPass authentication, and TLS settings for the endpoint you created. Keep every CA and client PKCS #12 file referenced by the configuration beside it, preserving the downloaded filenames. If any referenced file is missing, generate a new endpoint download; do not remove the client-certificate setting. Keep TLS verification enabled and trust CryptoHub through the shipped CA files. A full `cryptohub.json` configuration reference is available in the CryptoHub Client Library documentation; consult it only if you are configuring the connection by hand. If you configure `cryptohub.json` by hand, set at minimum: * `global.service_uuid` -> The UUID of the CryptoHub service this integration targets (the service you deployed this template into). * `global.key_store_name` -> The key store used for CryptoHub operations (the sample uses `chlibs`). If a matching key store does not exist, one is created on first key generation. * `global.key_protection` -> Set this to `PROTECTED` for Oracle TDE. Oracle requests Encrypt, Decrypt, Wrap, and Unwrap usages on its AES master key; CryptoHub rejects that multi-usage key under `TRUSTED` protection. * `cryptohubs[].base_uri` -> The CryptoHub base URI, including scheme and host (for example, `https://cryptohub.example.com`). CryptoHub serves the REST API on port `443`. * `cryptohubs[].label` -> A friendly label for the CryptoHub entry. This is the PKCS #11 **token label** your application references in a `pkcs11:` URI (for example, `token=CryptoHub`). * `cryptohubs[].tls.*` -> TLS settings: `verify` and `verify_hostname` for certificate and hostname validation, `authorities` for the CA file(s) that trust CryptoHub's REST certificate, and (for mutual TLS) `client_file` with the PKI file and password. * `authentication.users[]` -> The UserPass username and password generated for the Oracle TDE endpoint. Keep the populated configuration secret. The annotated sample ships with `logging.async_logging` set to `true`. Set it to `false` when you need deterministic, in-order log output while verifying operations. (This template's embedded configuration already pins `async_logging` to `false` and `logging.console` to `false`.) Keep TLS verification enabled (`cryptohubs[].tls.verify: true`) and trust CryptoHub's certificate through its CA (`cryptohubs[].tls.authorities`). ### Where the library looks for `cryptohub.json` The library reads the path in the `CHLIBS_CONFIG` environment variable first. If `CHLIBS_CONFIG` is unset, it falls back to a fixed list of static locations. Setting `CHLIBS_CONFIG` in the environment of the process that loads the module is the most reliable option, especially for applications that run from a service account or a custom working directory. ```shell expandable lines wrap title="Shell" theme={null} export CHLIBS_CONFIG=/etc/cryptohub.json ``` On **POSIX** platforms the search order is: 1. The path in `CHLIBS_CONFIG`. 2. `cryptohub.json` in the current working directory. 3. `../config/cryptohub.json` relative to the current working directory. 4. `/etc/cryptohub.json`. On **Windows**, the PKCS #11 module search order is: 1. The path in `CHLIBS_CONFIG`. 2. `cryptohub.json` in the current working directory. 3. `..\config\cryptohub.json` relative to the current working directory. 4. `C:\Program Files\Futurex\cryptohub.json`. 5. `C:\Program Files\Futurex\config\cryptohub.json`. 6. `C:\Futurex\cryptohub.json`. 7. `C:\Futurex\config\cryptohub.json`. Configuration string values support variable substitution: `${tmp}` (the OS temporary directory), `${conf}` (the directory containing `cryptohub.json`), `${env:VAR}` (an environment variable), and, on Windows, `${reg:HKLM\...}` (a registry value). This lets you keep secrets out of the file. For example, set the UserPass password to `${env:CHLIBS_PASSWORD}`. The service and its key store must exist in CryptoHub before the `service_uuid` in `cryptohub.json` can resolve. You deployed this service earlier in this guide, so it already exists. ## Verify connectivity and the PKCS #11 module Use the bundled `pkcs11-manager` to confirm the module loads, reads `cryptohub.json`, authenticates to CryptoHub, and can see the token before configuring your application. It is an interactive menu utility, not an automatic connectivity probe, and its first argument is the configuration path. 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. ```shell expandable lines wrap title="Shell" theme={null} pkcs11-manager /etc/cryptohub.json ``` `pkcs11-manager` loads `libcryptohub-pkcs11.so` and reads the same `cryptohub.json` resolved through the search order above, so a successful login and slot listing here confirms the module, configuration, credential, and TLS trust are all correct. Optionally, confirm the module through OpenSC's `pkcs11-tool`, an **external** tool installed separately (for example, from the `opensc` package), not part of the CryptoHub Client Library. List the token slots and confirm the CryptoHub token label appears: ```shell expandable lines wrap title="Shell" theme={null} pkcs11-tool --module /usr/local/lib/libcryptohub-pkcs11.so --list-token-slots ```