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