> ## 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 cng block and shared cryptohub.json settings used by the CryptoHub Client Library CNG provider, including provider name, default usages, key protection, and the TRUSTED-versus-PROTECTED distinction.
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](./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](../CryptoHub_PKCS11_developer_guide/Configuration) 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:
1. `C:\Program Files\Futurex\cryptohub.json`
2. `C:\Program Files\Futurex\config\cryptohub.json`
3. `C:\Futurex\cryptohub.json`
4. `C:\Futurex\config\cryptohub.json`
5. 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:
```json theme={null}
"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](#multi-usage-rsa-keys-key-protection-and-usages) 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`.
```json theme={null}
"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.
```json theme={null}
"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](../CryptoHub_PKCS11_developer_guide/Configuration#authentication). 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.
```json theme={null}
{
"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.