Configuration - Futurex Documentation

The CryptoHub Client Library CNG provider reads its settings from a single JSON file, cryptohub.json — the same file the PKCS#11 module uses. The provider reads its own cng block along with the shared global, cryptohubs, authentication, and logging blocks. This page describes the settings that matter for the CNG provider.

The endpoint download you generate during Installation ships a pre-filled cryptohub.json for your endpoint, already carrying the CryptoHub host, service reference, authentication material, and TLS trust settings. Start from that file and confirm the settings below rather than writing the file from scratch.cryptohub.json is shared with the PKCS#11 module. The PKCS#11 Configuration reference documents the full schema — discovery order, variable substitution, and every global, cryptohubs, authentication, and logging field. This page covers only what is specific to the CNG provider.

Configuration file location

The CNG provider searches these locations, in order, and uses the first one it finds:

C:\Program Files\Futurex\cryptohub.json
C:\Program Files\Futurex\config\cryptohub.json
C:\Futurex\cryptohub.json
C:\Futurex\config\cryptohub.json
The path in the CHLIBS_CONFIG environment variable.

This order places the static paths before CHLIBS_CONFIG, which is the reverse of the PKCS#11 module’s discovery order. A stray cryptohub.json under C:\Program Files\Futurex takes precedence over the path in CHLIBS_CONFIG.

The `cng` block

The cng block configures the Key Storage Provider.

Field	Type	Description
`provider_name`	string	The name the KSP registers under and that applications open. Must match the name registered at install time. The default is `Futurex CryptoHub Key Storage Provider`.
`default_usages`	object	Default allowed usages applied to keys the provider creates when the caller passes no usage flags. Contains `symmetric` and `asymmetric` arrays.

The default_usages sub-object sets the allowed usages when the caller 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`.

A code-signing deployment, whose keys only sign, ships a narrow default:

"cng": {
  "provider_name": "Futurex CryptoHub Key Storage Provider",
  "default_usages": {
    "asymmetric": ["Sign", "Verify"]
  }
}

An application that needs an RSA key to both encrypt and sign — for example, one that wraps a key and then signs the wrapped blob — needs a broader usage list. See Multi-usage RSA keys below.

Key protection

The global.key_protection value determines how CryptoHub protects the keys the provider uses.

Value	Description
`TRUSTED`	Normal HSM trusted encryption keys. Under `TRUSTED`, CryptoHub refuses to create an RSA key that carries more than one usage class.
`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. Required for a single RSA key that carries more than one usage class.

Multi-usage RSA keys: key protection and usages

Some applications need one RSA key that carries more than one usage class — for example, an application that must both unwrap a key and sign a blob with the same RSA key. Two settings together control whether CryptoHub permits such a key:

global.key_protection must be PROTECTED.
cng.default_usages.asymmetric must list every usage the key needs, for example Encrypt, Decrypt, Sign, and Verify.

"global": {
  "key_protection": "PROTECTED"
},
"cng": {
  "provider_name": "Futurex CryptoHub Key Storage Provider",
  "default_usages": {
    "symmetric":  ["Encrypt", "Decrypt"],
    "asymmetric": ["Encrypt", "Decrypt", "Sign", "Verify"]
  }
}

Under key_protection: TRUSTED, CryptoHub refuses to create an RSA key with more than one usage class, and multi-usage workflows fail at key creation. Services whose keys only sign, such as the code-signing services, ship the narrower TRUSTED plus Sign/Verify defaults on purpose. If your application needs a multi-usage RSA key, set key_protection to PROTECTED and widen the asymmetric usage list before you create any keys.

Remove the `tls.client_file` stanza for username/password endpoints

When the endpoint authenticates with a username and password, no client PKI file (client.p12) ships in the endpoint download. If the generated cryptohub.json still contains a client_file block under tls that references a client.p12, the provider fails to load because it cannot open the file the stanza references.

"client_file": {
  "file": "...\\client.p12",
  "password": "..."
}

For a username/password endpoint, delete the entire client_file block from the tls settings. Leave it in place only when the endpoint authenticates with mutual TLS and the referenced PKI file ships in the download.

TLS and authentication

The CNG provider uses the shared cryptohubs[].tls and authentication blocks, documented in full in the PKCS#11 Configuration reference. For production deployments, keep TLS verification enabled and trust CryptoHub’s certificate through its CA. Anonymous TLS — accepting the server certificate without verification — is only appropriate for a self-signed lab appliance that your client does not yet trust.

Example configuration

The following configuration targets a single CryptoHub service over verified TLS, authenticates with a username and password, protects keys with PROTECTED, and allows multi-usage RSA keys.

{
  "logging": { "console": false, "async_logging": false },
  "global": {
    "service_uuid": "01000001-d808-0001-0000-000000000001",
    "key_store_name": "chlibs",
    "key_protection": "PROTECTED"
  },
  "cryptohubs": [
    {
      "slot": 0,
      "label": "CryptoHub",
      "base_uri": "https://cryptohub.internal.example.com",
      "tls": { "verify": true, "verify_hostname": true, "authorities": ["C:\\Program Files\\Futurex\\ca-chain.pem"] },
      "role": "PRODUCTION"
    }
  ],
  "authentication": { "users": [{ "username": "cng-endpoint", "password": "${env:CHLIBS_PASSWORD}" }] },
  "cng": {
    "provider_name": "Futurex CryptoHub Key Storage Provider",
    "default_usages": {
      "symmetric":  ["Encrypt", "Decrypt"],
      "asymmetric": ["Encrypt", "Decrypt", "Sign", "Verify"]
    }
  }
}

Futurex recommends that you supply secrets such as passwords through environment variables with ${env:...} rather than hard-coding them in the file.

​Configuration file location

​The cng block

​Key protection

​Multi-usage RSA keys: key protection and usages

​Remove the tls.client_file stanza for username/password endpoints

​TLS and authentication

​Example configuration

Configuration file location

The `cng` block

Key protection

Multi-usage RSA keys: key protection and usages

Remove the `tls.client_file` stanza for username/password endpoints

TLS and authentication

Example configuration