Skip to main content
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:
pkcs11-manager
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:
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.

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

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

​
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 parameter-set or template mismatch

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

​
Where to look next

  • Confirm the field values you are debugging against the Configuration reference.
  • Confirm which operations are local and which require CryptoHub in Architecture.
  • Confirm the mechanisms and parameter sets your build advertises in Appendix A.