Skip to main content

​
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
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
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