> ## 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. # Architecture > How the CryptoHub-backed PKCS#11 module maps CryptoHub destinations, services, key stores, and protection models onto PKCS#11 slots, tokens, and objects. 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. ```mermaid expandable lines wrap title="Mermaid" theme={null} %%{init: {'theme': 'neutral', 'sequence': {'showSequenceNumbers': true} }}%% sequenceDiagram box Local Components participant App as Client Application participant Lib as libcryptohub-pkcs11 participant Cfg as cryptohub.json end box Remote participant CH as CryptoHub (REST/TLS) end App ->> Lib: C_Initialize() activate Lib Lib ->> Cfg: Read configuration Cfg -->> Lib: Return settings (logging, global, cryptohubs, auth, pkcs11) rect rgba(0, 255, 0, 0.1) Lib ->> CH: Open TLS to each cryptohubs[] base_uri CH -->> Lib: TLS established Lib ->> CH: Authenticate (user / API key / PKI / mTLS) CH -->> Lib: Session authorized end Lib -->> App: Initialization complete deactivate Lib App ->> Lib: C_FindObjects / C_Sign / C_GenerateKeyPair activate Lib Lib ->> CH: Resolve service_uuid + key_store_name, run operation CH -->> Lib: Keys, certificates, or operation result Lib -->> App: PKCS#11 objects and return values deactivate Lib ``` ## 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. | Value | Behavior | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `TRUSTED` | Normal HSM trusted encryption keys. | | `STORED` (aliases `HSM_STORED`, `HSMSTORED`) | Keys are stored inside the HSM key table. | | `PROTECTED` | Keys are protected by the HSM but can be pulled client-side for speed. This model supports unsafe wrapping techniques without requiring an HSM login. | 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. | `cert_id_mode` | How `CKA_ID` is derived | Certificate/key matching | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `Default` | From CryptoHub checksums: `certInfo.keyChecksum` for certificates and `relatedInfo.currentChecksum` for private keys, both hex-decoded. Explicit `CKA_ID` metadata always wins. | CryptoHub computes both checksums the same way, so a matching key and certificate share the same `CKA_ID`. | | `Metadata` | Never derived; only the object's own metadata supplies `CKA_ID`. | Matching relies entirely on metadata. | | `KeyUuid` | From the trusted-key UUID bytes: `cert.keyUuid` for certificates and `key.objInfo.uuid` for private keys. | Matching is by trusted-key UUID. | 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](./Configuration#key-usage-policy-and-precedence). ## 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](./Troubleshooting).