> ## 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 configuration, connectivity, authentication, service lookup, protection-model, and PKCS#11 v3.2 compatibility problems with the CryptoHub-backed PKCS#11 module.

Because the CryptoHub-backed PKCS#11 module services operations over a REST/TLS connection to CryptoHub, most problems trace back to configuration, connectivity, authentication, or service and key-store selection rather than to the PKCS#11 call itself. This page describes how to isolate each class of problem.

## Start with pkcs11-manager and logging

Reproduce the problem with the packaged `pkcs11-manager` utility before you debug it inside your application. The utility isolates whether the module loads, reads its configuration, reaches CryptoHub, and authenticates:

```text title="pkcs11-manager" theme={null}
Info -> Get library info
Info -> Get slot list
Info -> List mechanisms
```

Raise log verbosity while you diagnose. In the `logging` block of `cryptohub.json`, set `mode` to `DEBUG` and enable `trace_logging`. Send output to the console or a file so you can read it:

```json theme={null}
"logging": {
  "mode": "DEBUG",
  "trace_logging": true,
  "console": true,
  "file": { "path": "${tmp}/cryptohub-pkcs11.log" }
}
```

<Warning>
  `DEBUG` and trace logging are diagnostic settings. Return `mode` to `INFO` or `ERROR` and disable `trace_logging` in production to control log size and avoid recording sensitive detail.
</Warning>

## Configuration file not found or not parsed

If the module behaves as though it has no configuration, confirm it is reading the file you expect.

* **Wrong file loaded.** The module uses the first file it finds in the discovery order: `CHLIBS_CONFIG`, then `cryptohub.json` in the current working directory, then `../config/cryptohub.json`, then the platform static paths. A stray `cryptohub.json` in the working directory overrides the system-wide file. Set `CHLIBS_CONFIG` to an absolute path to remove ambiguity.
* **Service account or custom working directory.** When your application runs under a service account, its working directory may not be what you expect. Set `CHLIBS_CONFIG` rather than relying on a relative path.
* **JSON parse errors.** A malformed file prevents the module from initializing. Validate the file as JSON, and check that variable substitutions (`${env:...}`, `${conf}`, `${reg:...}`) resolve — an unset environment variable can leave a field empty.

## CryptoHub REST unreachable

If initialization fails at the connection stage, verify network reachability to each destination's `base_uri`.

* Confirm the host can reach every `cryptohubs[].base_uri` over HTTPS, and that firewalls and any HTTP `proxy` setting permit the connection.
* Check that the URI scheme, host, and port are correct and that the CryptoHub REST service is running.
* If some destinations are unreachable, remember that `PRODUCTION` entries load-balance and `BACKUP` entries are tried only after all production entries fail. A destination with `role` set to `NONE` is never used.

## TLS chain or hostname validation failures

TLS problems surface as handshake or verification errors during initialization.

* When `tls.verify` is `true`, the server certificate chain must validate against the CA files listed in `tls.authorities`. Confirm those files exist and contain the correct issuing CAs.
* When `tls.verify_hostname` is `true`, the certificate must match the hostname in `base_uri`. A certificate issued to an IP address or a different name fails this check.
* If you restrict `tls.protocol_min` and `tls.protocol_max` or the `tls.ciphers` list, make sure CryptoHub supports the negotiated protocol and cipher.
* For mutual TLS, confirm the `tls.client_file` (or Windows `tls.windows`) certificate and its password are correct.

## Authentication failures

Authentication applies globally to all CryptoHub destinations and is configured in the `authentication` block. It is optional when you authenticate with client (mutual) TLS.

* **Credentials.** Confirm exactly one authentication method is configured and correct: `users` (username/password), `api_key`, or PKI (`pki_key`/`pki_auth` with `pki_cert`). Secrets supplied through `${env:...}` fail silently if the environment variable is unset.
* **PKI nonce-signature.** For PKI authentication, confirm the client PKI certificate and password are correct and that CryptoHub trusts the certificate.
* **Backend cluster authentication.** If your deployment uses a backend balancing cluster, the `cluster_authentication` block governs cluster login. For an anchor HSM cluster the module uses your authentication credentials by default; for a non-anchor cluster it uses the system users by default. Configure `cluster_authentication` explicitly if the defaults do not apply.

## Service or key-store lookup problems

If the module authenticates but exposes no keys, or the wrong keys, check the `global` service and key-store settings.

* Confirm `service_uuid` identifies the intended CryptoHub service and `key_store_name` names a key store within it. Only keys in that key store are used.
* Confirm the key store's protection model matches `key_protection`. The module uses the key store whose protection model and service match.
* If keys you just created do not appear, set `reload_on_cache_miss` to `true` so the module reloads the cache after a lookup miss, or reinitialize the module.
* If a certificate does not match its private key, review `cert_id_mode`. `Default` derives `CKA_ID` from CryptoHub checksums so matching keys and certificates share an ID; `Metadata` and `KeyUuid` derive it differently. See [Architecture](./Architecture#object-identity-and-matching).

## Protection-model mismatch

An operation can fail because the key's protection model does not permit it. For example, wrapping techniques that do not require an HSM login are available under `PROTECTED` but not under `TRUSTED` or `STORED`. Confirm that `key_protection` matches both the key store you target and the operations you intend to perform.

## Operation rejected even though the mechanism is advertised

A mechanism appearing in `C_GetMechanismList` does not guarantee an operation succeeds.

* **CryptoHub policy and key metadata.** CryptoHub enforces per-key usage and service policy. An operation the mechanism supports can still be rejected by policy. Confirm the key's CryptoHub usage permits the operation.
* **Module usage configuration.** The `pkcs11.forced_usages`, `pkcs11.forced_usages.by_label`, and `pkcs11.default_usages` settings can constrain usage for AES, DES, RSA, and ECC keys. `forced_usages` overrides everything, so a forced usage that omits your operation blocks it regardless of the template. See [Configuration](./Configuration#key-usage-policy-and-precedence).

## PKCS#11 v3.2 consumer compatibility

Some consumers do not understand the PKCS#11 v3.2 interface this module implements.

* A consumer built against an older Cryptoki header may not recognize the v3.2 KEM functions (`C_EncapsulateKey`, `C_DecapsulateKey`) or the post-quantum mechanisms and attributes.
* Java's SunPKCS11 provider and the JDK may lag the module's v3.2 post-quantum and KEM features. The native provider can expose mechanisms the SunPKCS11 layer cannot name or invoke. For post-quantum operations, prefer the native C interface, or confirm your JDK and SunPKCS11 build support the mechanisms. See [Post-quantum cryptography](./Post_quantum_cryptography#java-and-sunpkcs11-limitations).

## Post-quantum parameter-set or template mismatch

When post-quantum operations fail, check the return value:

| Return value                      | Likely cause and fix                                                                                                                                                       |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CKR_PARAMETER_SET_NOT_SUPPORTED` | The requested `CKA_PARAMETER_SET` is not available on this module or backend. Choose a supported ML-DSA or ML-KEM parameter set.                                           |
| `CKR_TEMPLATE_INCONSISTENT`       | The key template conflicts with the mechanism or parameter set — for example, requesting encapsulation usage on an ML-DSA key. Align the template usage with the key type. |
| `CKR_MECHANISM_INVALID`           | The mechanism is not advertised for the selected slot. Re-check with `C_GetMechanismList`.                                                                                 |

## Where to look next

* Confirm the field values you are debugging against the [Configuration](./Configuration) reference.
* Confirm which operations are local and which require CryptoHub in [Architecture](./Architecture#local-versus-cryptohub-backed-operations).
* Confirm the mechanisms and parameter sets your build advertises in [Appendix A](./Appendices/Appendix_A_Supported_mechanisms).