Craton HSM ships as a shared library (craton_hsm.dll on Windows, libcraton_hsm.so on Linux, libcraton_hsm.dylib on macOS) that exports the PKCS#11 v3.0 C ABI. Any PKCS#11 v2.40 consumer will work; the v3.0 additions that are implemented are listed at the bottom of this page.
All entry points are declared #[no_mangle] extern "C". The function pointer table is returned from C_GetFunctionList and follows the CK_FUNCTION_LIST layout in the OASIS specification.
| Function | Purpose |
|---|
C_Initialize | Initialise the Cryptoki library. Runs Power-On Self-Tests (17 tests: integrity plus 16 KATs). On POST failure, leaves the module in an error state until a subsequent C_Initialize succeeds. |
C_Finalize | Release resources allocated by C_Initialize. Closes all sessions and unloads token state. |
C_GetInfo | Return library version, manufacturer ID (Craton Software), Cryptoki version (3.0), and library description. |
C_GetFunctionList | Return the function pointer table. |
| Function | Purpose |
|---|
C_GetSlotList | Enumerate slots. Craton HSM presents a single slot per token configured in craton_hsm.toml. |
C_GetSlotInfo | Report slot flags (CKF_TOKEN_PRESENT, CKF_REMOVABLE_DEVICE = 0, CKF_HW_SLOT = 0), manufacturer, and firmware version. |
C_GetTokenInfo | Report label, manufacturer, model, serial number, flags, PIN length bounds, session limits, and free memory counters. |
C_GetMechanismList | Return the supported mechanisms filtered by algorithm policy. In default mode this is 41 entries; in FIPS approved mode the PQC mechanisms, Ed25519, and SHA-1 are suppressed. |
C_GetMechanismInfo | Return min/max key size and permitted operations for a specific mechanism. |
C_InitToken | Initialise a token with an SO PIN and a label. Wipes existing key material on a re-initialised token. |
C_WaitForSlotEvent | Unsupported. Returns CKR_FUNCTION_NOT_SUPPORTED — Craton HSM has no removable-slot concept. |
| Function | Purpose |
|---|
C_InitPIN | Security Officer initialises the User PIN after C_InitToken. Requires an R/W SO session. |
C_SetPIN | Change the PIN of whichever role is currently logged in (or the User PIN if not logged in, matching the PKCS#11 v3.0 semantics). PIN hashing uses PBKDF2-HMAC-SHA256 (600 000 iterations by default). |
| Function | Purpose |
|---|
C_OpenSession | Open a read-only or read-write session on a slot. Sessions are tracked in a DashMap for safe concurrent access. |
C_CloseSession | Close a single session. Active cryptographic operations on that session are cancelled and their intermediate state zeroised. |
C_CloseAllSessions | Close all sessions on a slot. |
C_GetSessionInfo | Return session state (CKS_RO_PUBLIC_SESSION, CKS_RW_USER_FUNCTIONS, etc.), slot ID, and flags. |
C_Login | Authenticate as CKU_USER or CKU_SO. CKU_CONTEXT_SPECIFIC is honoured for CKA_ALWAYS_AUTHENTICATE keys. PIN comparison is constant-time (subtle::ConstantTimeEq). |
C_Logout | End the authenticated state for the session's token. |
C_GetOperationState | Serialise the active operation with an HMAC-authenticated envelope. Supported for digest and multi-part sign/verify streams. |
C_SetOperationState | Restore a serialised operation. The HMAC is validated before any state is applied. |
| Function | Purpose |
|---|
C_CreateObject | Create an object from a template. Used for importing keys, certificates, and data objects. |
C_DestroyObject | Delete an object. Enforces CKA_DESTROYABLE. Zeroises key material on removal. |
C_CopyObject | Duplicate an object with template overrides. |
C_GetObjectSize | Return the approximate in-memory size of an object. |
C_GetAttributeValue | Read one or more attributes. Sensitive attributes (CKA_VALUE on secret keys, private key components) are never returned if CKA_SENSITIVE = CK_TRUE or CKA_EXTRACTABLE = CK_FALSE. |
C_SetAttributeValue | Modify attributes subject to CKA_MODIFIABLE. Sensitivity transitions are one-way: once CKA_SENSITIVE = CK_TRUE, it cannot be cleared. |
C_FindObjectsInit | Start a search filtered by an attribute template. Results are confined to the current session's view (public objects on any session, private objects only when logged in). |
C_FindObjects | Iterate search results. |
C_FindObjectsFinal | End the search and free its iterator state. |
| Function | Purpose |
|---|
C_EncryptInit | Initialise encryption with the given mechanism and key. Rejects all-zero IVs for AES-CBC / CBC-PAD / CTR. Enforces lifecycle state and CKA_ENCRYPT. |
C_Encrypt | Single-part encrypt. |
C_EncryptUpdate | Multi-part encrypt. Supported for CKM_AES_CBC, CKM_AES_CBC_PAD, CKM_AES_CTR. Not supported for CKM_AES_GCM or CKM_RSA_PKCS_OAEP. |
C_EncryptFinal | Finalise a multi-part encrypt. |
| Function | Purpose |
|---|
C_DecryptInit | Initialise decryption. Enforces lifecycle state (deactivated keys may decrypt) and CKA_DECRYPT. |
C_Decrypt | Single-part decrypt. |
C_DecryptUpdate | Multi-part decrypt. Same mechanism set as C_EncryptUpdate. |
C_DecryptFinal | Finalise a multi-part decrypt. |
| Function | Purpose |
|---|
C_DigestInit | Initialise a digest. SHA-1 is permitted for digest-only operations outside FIPS approved mode. |
C_Digest | Single-part digest. |
C_DigestUpdate | Multi-part digest. |
C_DigestKey | Include a key's raw value in the running digest. |
C_DigestFinal | Finalise and return the digest. |
| Function | Purpose |
|---|
C_SignInit | Initialise signing. Enforces lifecycle state and CKA_SIGN. |
C_Sign | Single-part sign. |
C_SignUpdate | Multi-part sign. Supported for CKM_SHA*_RSA_PKCS, CKM_SHA*_RSA_PKCS_PSS, CKM_ECDSA_SHA*. |
C_SignFinal | Finalise a multi-part sign. |
C_SignRecoverInit | Unsupported. Returns CKR_FUNCTION_NOT_SUPPORTED. |
C_SignRecover | Unsupported. |
C_VerifyInit | Initialise verification. Permitted on deactivated keys. |
C_Verify | Single-part verify. |
C_VerifyUpdate | Multi-part verify. |
C_VerifyFinal | Finalise a multi-part verify. |
C_VerifyRecoverInit | Unsupported. |
C_VerifyRecover | Unsupported. |
Craton HSM exports these stubs for ABI completeness but does not implement the combined operations. Each returns CKR_FUNCTION_NOT_SUPPORTED.
| Function | Status |
|---|
C_DigestEncryptUpdate | Unsupported |
C_DecryptDigestUpdate | Unsupported |
C_SignEncryptUpdate | Unsupported |
C_DecryptVerifyUpdate | Unsupported |
Consumers that need these combinations should drive the component operations on parallel sessions.
| Function | Purpose |
|---|
C_GenerateKey | Generate a symmetric key (CKM_AES_KEY_GEN). All generation routes through the DRBG. |
C_GenerateKeyPair | Generate an asymmetric key pair (RSA, EC, Ed25519, ML-KEM, ML-DSA, SLH-DSA). Each pair is followed by a pairwise consistency test (sign/verify or encap/decap roundtrip); failure aborts the generation and enters the error state. |
C_WrapKey | Wrap a key under another key. CKM_AES_KEY_WRAP (RFC 3394) and CKM_AES_KEY_WRAP_KWP (RFC 5649) are supported. The source key must have CKA_EXTRACTABLE = CK_TRUE. |
C_UnwrapKey | Import a wrapped key. Resulting keys default to CKA_EXTRACTABLE = CK_FALSE unless the template says otherwise. |
C_DeriveKey | Derive a key via ECDH (CKM_ECDH1_DERIVE, CKM_ECDH1_COFACTOR_DERIVE) with an internal HKDF-SHA256 per SP 800-56C, or via a PQC KEM (CKM_ML_KEM_*, CKM_HYBRID_X25519_ML_KEM_768). |
| Function | Purpose |
|---|
C_GenerateRandom | Draw bytes from the SP 800-90A HMAC_DRBG. See DRBG. |
C_SeedRandom | Mix caller-supplied entropy into the DRBG as additional input. Never replaces OS entropy. |
Parallel functions are legacy PKCS#11 v1 holdovers. Craton HSM returns CKR_FUNCTION_NOT_PARALLEL / CKR_FUNCTION_NOT_SUPPORTED.
| Function | Status |
|---|
C_GetFunctionStatus | Returns CKR_FUNCTION_NOT_PARALLEL |
C_CancelFunction | Returns CKR_FUNCTION_NOT_PARALLEL |
Session notification callbacks passed to C_OpenSession are accepted but never invoked — Craton HSM has no asynchronous events to deliver. The callback pointer is stored and discarded on C_CloseSession.
| Feature | Status |
|---|
C_GetInterfaceList / C_GetInterface | Not yet implemented. Consumers that require v3.0 interface negotiation must load through C_GetFunctionList and treat the library as v2.40-compatible. |
C_LoginUser (variant with pUsername) | Not yet implemented. |
C_SessionCancel | Not yet implemented. |
C_MessageEncryptInit / C_EncryptMessage / C_MessageEncryptFinal (message-based API) | Not yet implemented. |
New v3.0 mechanisms (CKM_EDDSA, AES-GCM message API) | CKM_EDDSA as a mechanism is implemented; the message-based variant is not. |
These are tracked as gaps and will be addressed before 1.0. Consumers depending on a specific v3.0 addition should check the changelog or raise an issue.
C_InitPIN requires an R/W SO session — the spec allows implementations to reject this, and Craton HSM does.C_SetAttributeValue cannot clear CKA_SENSITIVE once set, matching PKCS#11 v3.0 §5.7.CKA_ALWAYS_AUTHENTICATE keys demand a CKU_CONTEXT_SPECIFIC login between every use.- All-zero IVs are rejected at
C_EncryptInit for AES-CBC and AES-CTR (a conservative extension of the spec, closing a known misuse pattern).
- Pairwise consistency tests run after every key pair generation; failure triggers POST-failed state (§9.6 of FIPS 140-3 IG).
# OpenSC pkcs11-tool
pkcs11-tool --module /opt/craton_hsm/libcraton_hsm.so --list-slots
# p11-kit
p11-kit list-modules
See Integrations for OpenSSL, Java, NSS, Vault, and Kubernetes examples.