Skip to main content
The CryptoHub-backed PKCS#11 module presents CryptoHub-managed keys through the standard PKCS#11 object model. Unlike the legacy fxpkcs11 module, which connects directly to an HSM and exposes keys stored in an HSM token, this module connects to CryptoHub over REST/TLS and exposes the keys in a CryptoHub service and key store. This page explains how CryptoHub concepts map onto PKCS#11 slots, tokens, and objects, so you can predict which keys an application sees and which operations succeed.

​
From application call to CryptoHub

When an application initializes the module, the module reads cryptohub.json, applies logging and request settings, establishes TLS connections to the configured CryptoHub destinations, and authenticates. Cryptographic calls are then serviced by CryptoHub against the selected service and key store, rather than by a locally attached HSM.

​
Slots and tokens

Each entry in the cryptohubs array maps to a PKCS#11 slot. The entry’s slot field is the numeric slot identifier, and its label provides a friendly name. The token exposed on that slot represents the CryptoHub service and key store the module is configured to target. Because PRODUCTION destinations participate in round-robin load balancing and BACKUP destinations take over only when production destinations fail, a slot represents a logical CryptoHub target rather than a single physical appliance. Set a destination’s role to NONE to exclude it from load balancing and failover.

​
Services, key stores, and the exposed key estate

Three global settings determine which keys a token exposes:
  • service_uuid selects the CryptoHub service to target.
  • key_store_name selects the key store within that service. Only keys in this key store are used.
  • key_protection selects the protection model. The module uses the key store whose protection model and service match this value.
Together these settings scope the key estate the application sees. If a key store with a matching protection model and service is not found when the module generates a key, CryptoHub can create one automatically.

​
Protection models

The key_protection value controls how CryptoHub protects the keys the module uses. Choose the model that matches your security and performance requirements.
The PROTECTED model allows keys to be pulled client-side and supports wrapping techniques that do not require an HSM login. Use it only when your threat model accepts client-side key material and unauthenticated wrapping. For the strongest protection, keep keys in the HSM with TRUSTED or STORED.

​
Object identity and matching

The module represents CryptoHub keys and certificates as PKCS#11 objects with the usual attributes, such as CKA_CLASS, CKA_LABEL, and CKA_ID. How the module assigns CKA_ID — and therefore how a certificate is matched to its private key — is controlled by the global.cert_id_mode setting. Choose Default unless your application requires object identities that come only from metadata (Metadata) or that are keyed on CryptoHub trusted-key UUIDs (KeyUuid).

​
Caching and cache misses

The module caches keys and certificates it resolves from CryptoHub. When global.reload_on_cache_miss is true, the module reloads the key and certificate cache after a lookup fails, so newly created CryptoHub objects become visible without reinitializing the module. When it is false, a lookup that misses the cache does not trigger a reload.

​
Usage policy overrides mechanism availability

A mechanism appearing in C_GetMechanismList does not by itself guarantee an operation succeeds. Two layers can restrict what a key can do:
  • CryptoHub policy and key metadata. CryptoHub enforces the usage and policy attached to each key. An operation that a mechanism supports can still be rejected if the key’s CryptoHub metadata or the service’s policy does not permit it.
  • Module usage configuration. The pkcs11.default_usages, pkcs11.forced_usages, and pkcs11.forced_usages.by_label settings determine the usages the module applies to symmetric (AES, DES) and asymmetric (RSA, ECC) keys. forced_usages takes precedence over by_label, which takes precedence over default_usages. See Configuration.

​
Local versus CryptoHub-backed operations

Some PKCS#11 calls are handled entirely within the module, while others require a round trip to CryptoHub:
  • Local: module initialization and configuration parsing, slot and token enumeration, mechanism list reporting, and cache lookups that hit.
  • CryptoHub-backed: authentication, key generation, key and certificate lookup on a cache miss, signing, verification, encryption, decryption, wrapping, unwrapping, derivation, and key encapsulation and decapsulation.
Because CryptoHub-backed operations depend on network reachability, authentication, and the selected service and key store, most operational problems trace back to configuration or connectivity rather than to the PKCS#11 call itself. See Troubleshooting.