> ## 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.

# Troubleshooting

> Diagnose registration, configuration, connectivity, authentication, and key-protection problems with the CryptoHub Client Library CNG Key Storage Provider.

Because the CryptoHub Client Library CNG provider services operations over a REST/TLS connection to CryptoHub, most problems trace back to registration, configuration, connectivity, authentication, or key protection rather than to the CNG call itself. This page describes how to isolate each class of problem.

## Verify the backend, not only registration

The most common mistake is confirming only that Windows registered the provider. Registration succeeds even when every call to CryptoHub is failing.

```powershell theme={null}
certutil -key -csp "Futurex CryptoHub Key Storage Provider"
```

`certutil -key -csp` enumerates the keys the provider can see in CryptoHub. On a new deployment the key list is empty, but the command completes without error — that confirms the provider loaded its configuration and authenticated to CryptoHub.

<Warning>
  Do not use `certutil -csplist` as your verification step. It lists registered providers and succeeds even when the provider cannot reach or authenticate to CryptoHub. Always confirm the backend with `certutil -key -csp`.
</Warning>

If `certutil -key -csp` fails, work through the sections below.

## Raise log verbosity

Turn up logging in the `logging` block of `cryptohub.json` while you diagnose:

```json theme={null}
"logging": {
  "mode": "DEBUG",
  "trace_logging": true,
  "file": { "path": "C:\\ProgramData\\Futurex\\cryptohub-cng.log" }
}
```

<Warning>
  The provider runs inside the process that loaded it, often a service under a restricted account such as a SQL Server or web-server service account. Set `logging.file.path` to a directory that account can write to (for example, under `C:\ProgramData`). If the account cannot write to the configured log path, the provider produces no log output. Return `mode` to `INFO` or `ERROR` and disable `trace_logging` in production.
</Warning>

## Provider not found or not registered

* If applications cannot open the provider, confirm it is registered under the name they request. `certutil -csplist` shows the registered provider names.
* The `cng.provider_name` value in `cryptohub.json` must match the name registered at install time. The default is `Futurex CryptoHub Key Storage Provider`. A mismatch between the registered name and `provider_name` prevents the provider from resolving keys.
* To repair a broken registration, re-run `cng-install.exe -overwrite` from an administrator command prompt.

## Configuration file not found or not parsed

* The provider searches, in order: `C:\Program Files\Futurex\cryptohub.json`, `C:\Program Files\Futurex\config\cryptohub.json`, `C:\Futurex\cryptohub.json`, `C:\Futurex\config\cryptohub.json`, then the path in `CHLIBS_CONFIG`. A stray file under `C:\Program Files\Futurex` takes precedence over `CHLIBS_CONFIG`.
* After you set the machine-level `CHLIBS_CONFIG` environment variable, **restart the consuming service** so it picks up the new value. A service that is already running holds the old environment.
* Validate the file as JSON, and confirm any `${env:...}` substitutions resolve — an unset environment variable can leave a field empty.

## The `client_file` stanza breaks loading

When the endpoint authenticates with a username and password, no `client.p12` ships in the 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 that file. Delete the entire `client_file` block for username/password endpoints. See [Configuration](./Configuration#remove-the-tlsclient_file-stanza-for-usernamepassword-endpoints).

## Connectivity, TLS, and authentication failures

* **Connectivity.** Confirm the Windows host can reach `cryptohubs[].base_uri` over HTTPS on port 443, and that firewalls and any TLS-inspection proxy permit the connection. Exempt the CryptoHub FQDN from TLS inspection.
* **TLS trust.** When `tls.verify` is `true`, the server certificate chain must validate against the CA files in `tls.authorities`. When `tls.verify_hostname` is `true`, the certificate must match the host in `base_uri`.
* **Authentication.** Confirm the credential in the `authentication` block matches the endpoint. Secrets supplied through `${env:...}` fail silently when the environment variable is unset.
* **REST API port on the role.** The provider authenticates over the REST API. Roles deployed by a service template ship with the **Excrypt** port only. If the provider reports an authentication failure, add the **REST API** port to the endpoint's role under **Identity and Access**.

## Key creation fails under `TRUSTED`

An application that needs one RSA key carrying more than one usage class — for example, a key that both unwraps a key and signs a blob — fails at key creation when `global.key_protection` is `TRUSTED`. Creating the key fails with an error like:

```none theme={null}
HTTP 502 - Setting key state 'Create' for '<key>' to failed:
Failed to create HSM trusted asymmetric key: [CY] VALUE OUT OF RANGE
(CommandError, generate_asymkey)
```

Under `TRUSTED`, CryptoHub refuses to create an RSA key with more than one usage class. Set `key_protection` to `PROTECTED` and list every needed usage in `cng.default_usages.asymmetric` before you create any keys. See [Configuration](./Configuration#multi-usage-rsa-keys-key-protection-and-usages).

If key creation succeeds but a later wrap or unwrap step fails, confirm the asymmetric usage list includes `Encrypt` and `Decrypt`, not only `Sign` and `Verify`.

## Where to look next

* Confirm the field values you are debugging against the [Configuration](./Configuration) reference.
* Confirm the algorithms your deployment supports in [Appendix A](./Appendices/Appendix_A_Supported_algorithms).
* For the shared `cryptohub.json` schema, see the [PKCS#11 Configuration reference](../CryptoHub_PKCS11_developer_guide/Configuration).