> ## 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.
# Configuration
> Reference for the cryptohub.json configuration file used by the CryptoHub-backed PKCS#11 module, including discovery order, connection, authentication, TLS, and key usage policy.
The CryptoHub-backed PKCS#11 module reads its settings from a single JSON file, `cryptohub.json`. This file tells the module which CryptoHub service to target, how to connect and authenticate, how to handle TLS, how to log, and how to apply key usage policy. This page describes the configuration file's discovery order, variable substitution, and every field the module reads.
The endpoint download you generate during [Installation](./Installation) ships a **pre-filled `cryptohub.json`** for your endpoint, already carrying the connection, authentication, and TLS settings for your instance. Start from that file. Use this page as the reference when you edit the file by hand or need to understand a specific field.
This page covers the CryptoHub-backed PKCS#11 module (`libcryptohub-pkcs11.*`), which reads `cryptohub.json`. It is separate from the legacy Futurex PKCS#11 module (`fxpkcs11`), which uses the XML-based `fxpkcs11.cfg` file. The two modules do not share configuration. For an introduction to the CryptoHub-backed module, see the Overview.
## Configuration file location
The module locates its configuration file by checking the following sources in order and using the first one it finds:
1. The path in the `CHLIBS_CONFIG` environment variable.
2. `cryptohub.json` in the current working directory.
3. `../config/cryptohub.json` relative to the current working directory.
4. A platform-specific static path.
On Windows, the module checks these static paths in order:
* `C:\Program Files\Futurex\cryptohub.json`
* `C:\Program Files\Futurex\config\cryptohub.json`
* `C:\Futurex\cryptohub.json`
* `C:\Futurex\config\cryptohub.json`
On POSIX systems, the module checks this static path:
* `/etc/cryptohub.json`
The runtime configuration file must be named `cryptohub.json` unless you point to it explicitly with the `CHLIBS_CONFIG` environment variable. When you set `CHLIBS_CONFIG`, the file can have any name.
## Variable substitution
You can use variable substitution in any string field. The module expands the following tokens when it reads the file:
| Token | Expands to |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `${tmp}` | The operating system temporary directory. |
| `${conf}` | The directory that contains the configuration file. |
| `${env:MY_ENV_VAR}` | The value of the named environment variable. |
| `${reg:HKEY_LOCAL_MACHINE\SOFTWARE\Futurex\MyConfig}` | A Windows registry value under `HKEY_LOCAL_MACHINE` (HKLM) or `HKEY_CURRENT_USER` (HKCU). |
Futurex recommends that you keep secrets such as API keys and passwords out of the file itself and supply them through environment variables with `${env:...}`.
## Root fields
The configuration file has the following root fields:
* `logging` — Log verbosity, destinations, and file rotation.
* `global` — The CryptoHub service to target, key protection, request behavior, and object identity.
* `cryptohubs` — An array of CryptoHub destinations for load balancing and failover.
* `proxy` — An optional HTTP proxy for all CryptoHub requests.
* `authentication` — Credentials the module presents to CryptoHub destinations.
* `cluster_authentication` — Credentials for the backend balancing cluster.
* `pkcs11` — PKCS#11 module behavior and key usage policy.
A `cng` block also exists. It is read by the Windows CNG Key Storage Provider, which shares this same `cryptohub.json` file. See the [CryptoHub CNG developer guide](../CryptoHub_CNG_developer_guide/Configuration) for the `cng` block.
## Logging
The `logging` block controls log verbosity, destinations, and file rotation.
| Field | Type | Description |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | string | Log verbosity. One of `ERROR`, `INFO`, or `DEBUG`. |
| `trace_logging` | boolean | Enables detailed trace logging. |
| `async_logging` | boolean | Writes log entries asynchronously, which reduces request latency. |
| `syslog` | boolean | Sends log output to the system log. |
| `console` | boolean | Sends log output to the console. |
| `file.path` | string | Path to the main log file. |
| `file.trace_file` | string | Optional dedicated file for trace logs. When set, trace logs go only to this file — not to the console, syslog, or the main log path. |
| `file.rotate.max_size` | number | Maximum size of a log file in bytes before the module rotates it. |
| `file.rotate.max_files` | number | Maximum number of rotated log files to retain. |
| `file.rotate.compress` | boolean | Compresses rotated log files. |
| `file.timezone` | string | Timestamp time zone. One of `LOCAL`, `UTC`, or `OFFSET`. |
The `file.timezone` value determines how the module renders log timestamps:
| Value | Example timestamp |
| -------- | --------------------------- |
| `LOCAL` | `2026-02-03 14:05:09.123` |
| `UTC` | `2026-02-03 19:05:09.123` |
| `OFFSET` | `2026-02-03T14:05:09-05:00` |
## Global settings
The `global` block defines the CryptoHub service to target, key protection, request behavior, and how the module derives object identities.
| Field | Type | Description |
| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `service_uuid` | string (UUID) | UUID identifying the CryptoHub service to target. |
| `key_store_name` | string | Key store name used for CryptoHub operations. |
| `key_protection` | string | How keys are protected. One of `TRUSTED`, `STORED`, `HSM_STORED`, `HSMSTORED`, or `PROTECTED`. See the table below. |
| `signing_policy_uuid` | string (UUID) | Optional UUID of the PkiSigning approval policy to use when submitting signing requests. When set to a non-null value, the module uses it directly and skips the per-sign policy lookup API call. Set to the all-zeros UUID (`00000000-0000-0000-0000-000000000000`) or omit the field to auto-discover the policy at sign time (the default). Relevant only when `service_uuid` points to a Raw PkiSigning service. |
| `request_timeout_ms` | number | Request timeout in milliseconds. |
| `request_retries` | number | Number of times to retry a failed request. |
| `request_retry_delay_ms` | number | Delay in milliseconds between retries. |
| `reload_on_cache_miss` | boolean | Reloads the key and certificate cache after a lookup failure. |
| `cert_id_mode` | string | Controls how the module derives `CKA_ID` for certificate and private-key objects. One of `Default`, `Metadata`, or `KeyUuid`. See the table below. |
| `disable_sigpipe` | boolean | Disables `SIGPIPE` handling. |
| `cleanup_openssl` | boolean | Runs OpenSSL cleanup routines when the module unloads. |
| `cleanup_curl` | boolean | Runs libcurl cleanup routines when the module unloads. |
The `key_protection` value determines how CryptoHub protects the keys the module uses:
| Value | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRUSTED` | Normal HSM trusted encryption keys. |
| `STORED` | Keys stored inside the HSM key table. |
| `HSM_STORED`, `HSMSTORED` | Aliases of `STORED`. |
| `PROTECTED` | Keys protected by the HSM that can be pulled client-side for speed. This mode supports unsafe wrapping techniques without requiring an HSM login. |
The `cert_id_mode` value controls how the module derives `CKA_ID` for certificate and private-key objects:
| Value | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Default` | Derives `CKA_ID` from CryptoHub checksums: `certInfo.keyChecksum` (hex-decoded) for certificates and `relatedInfo.currentChecksum` (hex-decoded) for private keys. CryptoHub computes both checksums the same way, so a matching key and certificate share the same `CKA_ID`. Explicit `CKA_ID` metadata always takes precedence. This is the default. |
| `Metadata` | Never derives `CKA_ID`; uses only what the object's metadata supplies. |
| `KeyUuid` | Sets `CKA_ID` to the trusted-key UUID bytes: `cert.keyUuid` for certificates and `key.objInfo.uuid` for private keys. |
## CryptoHub destinations
The `cryptohubs` block is an array of CryptoHub destinations. The module uses the array for load balancing and failover across destinations.
| Field | Type | Description |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `slot` | number | Numeric slot id for the destination. |
| `label` | string | Friendly label for the destination. |
| `base_uri` | string | Base URI of the CryptoHub service, for example `https://cryptohub.internal.example.com`. |
| `role` | string | Role in load balancing and failover. One of `PRODUCTION`, `BACKUP`, or `NONE`. Defaults to `PRODUCTION`. See the table below. |
| `tls` | object | TLS settings for the destination. See the table below. |
The `role` value determines when the module uses a destination:
| Value | Description |
| ------------ | --------------------------------------------------------------------------------- |
| `PRODUCTION` | Used first, with round-robin across production destinations. This is the default. |
| `BACKUP` | Tried only after all production destinations fail. |
| `NONE` | Excluded from load balancing and failover. |
The `tls` sub-object configures transport security for the destination:
| Field | Type | Description |
| ---------------------- | ------- | ---------------------------------------------------------------------- |
| `verify` | boolean | Enables certificate chain validation. |
| `verify_hostname` | boolean | Verifies the server hostname against the certificate. |
| `ciphers` | array | List of allowed ciphers. |
| `protocol_min` | string | Minimum TLS protocol version, for example `TLSv1.1`. |
| `protocol_max` | string | Maximum TLS protocol version, for example `TLSv1.3`. |
| `authorities` | array | CA certificate files used to validate the server. |
| `client_file.file` | string | Path to the client PKI file for mutual TLS, for example a `.p12` file. |
| `client_file.password` | string | Password for the client PKI file. |
| `windows.store` | string | Windows certificate store used for mutual TLS. |
| `windows.certificate` | string | Certificate within the Windows store used for mutual TLS. |
## Proxy
| Field | Type | Description |
| ------- | ------ | ------------------------------------------------------------------------------------- |
| `proxy` | string | HTTP proxy URI applied to all CryptoHub requests. Set to `null` to disable the proxy. |
## Authentication
The `authentication` block defines the credentials the module presents to CryptoHub destinations. It applies globally to all destinations, and it is optional when you use client TLS or mutual TLS.
| Field | Type | Description |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users` | array | List of `{username, password}` objects. |
| `api_key` | string | API key credential. |
| `pki_key` | boolean | Enables PKI key-based (nonce-signature) authentication. |
| `pki_auth` | boolean | Alias of `pki_key`; enables PKI key-based (nonce-signature) authentication. |
| `pki_cert` | object | Client PKI certificate. Either `{file, password}` or `{windows: {store, certificate}}`, where `store` is a value such as `My` or `CurrentUser\My`. |
| `pki_cert_file` | string | Alternate flat field for the PKI certificate file path. |
| `pki_cert_password` | string | Alternate flat field for the PKI certificate password. |
## Cluster authentication
The `cluster_authentication` block defines the credentials for the backend balancing cluster. It is optional and uses the same shape as the `authentication` block.
If you use the anchor HSM cluster, the module uses your authentication credentials by default. If you use a non-anchor HSM cluster, the module uses the system users by default.
## PKCS#11 module settings
The `pkcs11` block controls PKCS#11 module behavior and key usage policy.
| Field | Type | Description |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `check_already_initialized` | boolean | Skips initialization when the module is already initialized. |
| `check_already_logged_in` | boolean | Returns `CKR_USER_ALREADY_LOGGED_IN` for login calls when the session is already authorized. |
| `check_already_active` | boolean | Returns `CKR_OPERATION_ACTIVE` when a cryptographic operation is already in progress. |
| `default_usages` | object | Default allowed usages applied when a template passes no usage flags. Contains `symmetric` and `asymmetric` arrays. |
| `forced_usages` | object | Usages always applied, ignoring template usage flags. Contains `symmetric` and `asymmetric` arrays and a `by_label` array. |
The `default_usages` sub-object sets the allowed usages when a template passes no usage flags:
| Field | Type | Description |
| ------------ | ----- | ----------------------------------------------------------------------- |
| `symmetric` | array | Default usages for symmetric keys, for example `Encrypt` and `Decrypt`. |
| `asymmetric` | array | Default usages for asymmetric keys, for example `Sign` and `Verify`. |
The `forced_usages` sub-object sets usages the module always applies, regardless of the template's usage flags:
| Field | Type | Description |
| ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `symmetric` | array | Forced usages for symmetric keys. |
| `asymmetric` | array | Forced usages for asymmetric keys. |
| `by_label` | array | List of `{label, usage}` objects. `label` is a substring matched inside `CKA_LABEL`. If multiple labels match, the longest matching substring wins. A `by_label` entry applies when a matching label is found and no forced usage is configured. |
### Key usage policy and precedence
The module resolves key usage from three sources, in the following order of precedence:
1. `forced_usages` — Always applied, and evaluated before `by_label` and `default_usages`.
2. `by_label` — Applied when a matching label is found and no forced usage is configured.
3. `default_usages` — Applied when a template passes no usage flags.
Usage configuration applies only to symmetric keys (AES and DES) and asymmetric keys (RSA and ECC).
## Example configuration
The following minimal configuration targets a single CryptoHub service, validates the server's TLS certificate against a system CA bundle, authenticates with an API key supplied through an environment variable, and sets default key usages.
```json theme={null}
{
"logging": { "mode": "INFO", "async_logging": true, "file": { "path": "${tmp}/log.txt" } },
"global": {
"service_uuid": "01000001-d808-0001-0000-000000000001",
"key_store_name": "chlibs",
"key_protection": "TRUSTED",
"request_timeout_ms": 30000,
"request_retries": 3,
"request_retry_delay_ms": 1000
},
"cryptohubs": [
{
"slot": 0,
"label": "Futurex",
"base_uri": "https://cryptohub.internal.example.com",
"tls": { "verify": true, "verify_hostname": true, "protocol_min": "TLSv1.2", "protocol_max": "TLSv1.3", "authorities": ["/etc/ssl/certs/ca-certificates.crt"] },
"role": "PRODUCTION"
}
],
"proxy": null,
"authentication": { "api_key": "${env:CHLIBS_API_KEY}" },
"pkcs11": {
"check_already_initialized": true,
"default_usages": { "symmetric": ["Encrypt","Decrypt"], "asymmetric": ["Sign","Verify"] }
}
}
```
In this example, the `api_key` is read from the `CHLIBS_API_KEY` environment variable through `${env:...}`. Futurex recommends that you supply secrets such as API keys and passwords through environment variables rather than hard-coding them in the file.