Configuration - Futurex Documentation

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

The path in the CHLIBS_CONFIG environment variable.
cryptohub.json in the current working directory.
../config/cryptohub.json relative to the current working directory.
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 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:

forced_usages — Always applied, and evaluated before by_label and default_usages.
by_label — Applied when a matching label is found and no forced usage is configured.
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.

{
  "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.

​Configuration file location

​Variable substitution

​Root fields

​Logging

​Global settings

​CryptoHub destinations

​Proxy

​Authentication

​Cluster authentication

​PKCS#11 module settings

​Key usage policy and precedence

​Example configuration

Configuration file location

Variable substitution

Root fields

Logging

Global settings

CryptoHub destinations

Proxy

Authentication

Cluster authentication

PKCS#11 module settings

Key usage policy and precedence

Example configuration