PQC Today is an educational and demonstration platform, not a production system. Nothing it produces — keys, certificates, configurations, reports, or test results — is fit to protect real data, and none of it may be deployed or relied upon in production.

PKCS#11 HSM Playground

Engine:C++RustDual ParityDual

What this means for you

Executive / Business Leader: A banner at the top says this is a hands-on engineering workbench and points you to Command Center, Compliance landscape and Migration framework; for your role the engine stays Rust and the test suites are not shown.
GRC / Risk & Compliance: The same engineering-workbench banner appears for your role; if you stay, Inspect › Log lists every call with Function, Arguments and Return Value, and "Beginner" adds a "Plain English" column.
Developer / Engineer: Build › Standard is a pipeline builder with Builder and Code views, Run (⌘/Ctrl+Enter) and "Export .py"; Build also carries Validation and Conformance suites, and the Engine switch offers C++, Rust or Dual Parity.
Security Architect: Operate walks "1. Initialize HSM", "2. Create Token", "3. Open Session & Login", then a Primitives rail — KEM, Symmetric Encrypt, Key Wrap / Unwrap, Hashing, Sign & Verify, Key Agreement, KDF; Inspect › Keys lists what the token holds.
Researcher / Academic: Build › Validation is the "Cryptographic Validation Workbench": NIST ACVP-Server reference samples, standard KATs, oracle and functional tests, each row tagged with its evidence tier; Build › Conformance is a "PKCS#11 v3.2 Conformance Runner"; the WIP badge opens the methodology.
Certification & Validation Engineer: Build › Validation is the "Cryptographic Validation Workbench" — NIST ACVP-Server reference samples, standard KATs, oracle and functional tests, each row tagged with its evidence tier; Build › Conformance replays PKCS#11 v3.2 profile cases.
IT Ops / DevOps: The Learn lessons "The Cryptoki model — slots, tokens, sessions, login" and "Mechanism discovery" cover token setup; Inspect › Mechanisms' "Query Slot" enumerates what the token supports, and the Log filters by origin.
Curious Explorer: Open the Learn tab, pick a lesson and press "Run all" to watch each step run; the "New to PKCS#11?" strip explains the terms on hover, and the engine is preset to Rust.

New to PKCS#11?Hover a term:CKA_EXTRACTABLECKA_SENSITIVEC_WrapKeyCKM_AES_KWC_EncapsulateKey

Core

The Cryptoki model — slots, tokens, sessions, login

Every PKCS#11 call happens through a session, opened against a token, that lives in a slot. This walkthrough boots the real engine and shows what each layer actually is — then deliberately breaks one to show what an honest failure looks like.

PKCS#11 (Cryptoki) separates "what device" (slot → token) from "how you talk to it" (session → login). Get this model straight and every later operation — key generation, signing, wrapping — is just "which session, which handle."

Steps

C_Initialize / C_InitToken / C_OpenSession
1. Boot the library, format a token, and open an authenticated session
C_GetTokenInfo
2. Read back the token's identity
C_GetSessionInfo
3. Read back this session's own state
C_GetSessionInfo (unopened handle)
4. Try the same call on a session handle nobody ever opened

No HSM keys generated yet.

Use the KEM or Sign tabs to generate key pairs.

Glossary

C_CloseSessionCloses one session handle. C_CloseAllSessions closes every session on a slot at once.
C_CreateObjectCreates a token or session object directly from a caller-supplied attribute template, rather than generating one.
C_DecapsulateKeyThe KEM's other half — takes a private key and the ciphertext C_EncapsulateKey produced, returns a secret-key object holding the SAME shared secret. No plaintext shared-secret bytes need ever leave the token.
C_DestroyObjectDeletes an object and, for sensitive key material, the underlying bytes.
C_EncapsulateKeyPKCS#11 v3.2's KEM entry point — takes a public key, returns a ciphertext AND (as a new, usually session-only) secret-key object holding the shared secret. No classical PKCS#11 call has this two-output shape.
C_FinalizeShuts the library down, invalidating every open session and handle. The mirror image of C_Initialize.
C_FindObjectsInitBegins a search for objects matching an attribute template — paired with C_FindObjects and C_FindObjectsFinal.
C_GenerateKeyGenerates one symmetric key (or other single-key object) inside the token from a mechanism + attribute template.
C_GenerateKeyPairGenerates a public/private key pair inside the token, returning two handles.
C_GetAttributeValueReads one or more attributes off an object — the only way to inspect a key's metadata (or, for extractable keys, its value).
C_GetMechanismInfoFor one mechanism, returns its supported key-size range and capability flags (CKF_SIGN, CKF_ENCRYPT, CKF_GENERATE_KEY_PAIR, …).
C_GetMechanismListEnumerates every mechanism (algorithm+mode combination) the token's currently-selected slot supports.
C_GetSessionInfoReads back a session's slot ID, state (e.g. "R/W User Functions"), and flags — how a lesson step proves login actually took effect.
C_GetSlotListEnumerates the slots (physical or virtual token sockets) the library knows about — the first thing you call to find a token to work with.
C_GetTokenInfoReads a token's identity — label, manufacturer, model, serial number, session/memory limits — independent of any open session.
C_InitializeThe first call any PKCS#11 application makes — loads the Cryptoki library and readies it for use. Calling it twice without an intervening C_Finalize fails with CKR_CRYPTOKI_ALREADY_INITIALIZED.
C_InitTokenFormats a token in a slot with a fresh Security Officer PIN and a label — the token-level equivalent of C_Initialize. Destroys any objects already on the token.
C_LoginAuthenticates a session as a user role (typically CKU_USER) with a PIN — required before most cryptographic and private-object operations. Logging in twice on the same session returns CKR_USER_ALREADY_LOGGED_IN.
C_LogoutDrops the authenticated role on a session, without closing it.
C_OpenSessionOpens a session against a slot's token — the handle every later call (C_Login, C_GenerateKey, C_Sign, …) operates through.
C_SetAttributeValueChanges a writable attribute on an existing object (most are fixed at creation).
CK_SIGN_ADDITIONAL_CONTEXTMechanism-parameter structure carrying an ML-DSA/SLH-DSA signature's optional context string and hedge preference — where CKH_HEDGE_* selects between randomized and deterministic signing.
CKA_ALLOWED_MECHANISMS0x40000600v3.2 §4.8 Table 13 — an array attribute pinning a key to a specific allow-list of mechanisms. Any call naming a mechanism outside the list fails CKR_MECHANISM_INVALID, even if the mechanism itself is otherwise valid for that key type — the enforcement happens per-key, not just per-token.
CKA_CLASS0x00000000Every object has one — which of the object classes (CKO_PUBLIC_KEY, CKO_SECRET_KEY, CKO_PROFILE, …) this is.
CKA_DECAPSULATEA private key's KEM capability flag — this key may be used with C_DecapsulateKey to recover the shared secret.
CKA_ENCAPSULATEA public key's KEM capability flag — this key may be used as the target of C_EncapsulateKey.
CKA_EXTRACTABLETrue = this key MAY leave the token, wrapped, via C_WrapKey. Once created false, PKCS#11 guarantees it can never be flipped true later (see CKA_NEVER_EXTRACTABLE).
CKA_KEY_TYPE0x00000100Which key algorithm family this key object holds — CKK_AES, CKK_RSA, CKK_ML_DSA, …
CKA_PARAMETER_SETWhich named parameter set a PQC key uses — e.g. one of SLH-DSA's 12 CKP_SLH_DSA_* sets, distinct from the generic CKA_KEY_TYPE/CKA_KEY_TYPE algorithm family.
CKA_PROFILE_ID0x00000601The single attribute on a CKO_PROFILE object — which conformance profile it names (e.g. CKP_BASELINE_PROVIDER). Read-only, fixed at creation.
CKA_SENSITIVETrue = this key's value can never be read back via C_GetAttributeValue, even by an authenticated session — CKR_ATTRIBUTE_SENSITIVE is the honest, permanent answer, not a bug.
CKA_TOKENTrue = the object survives session close (persisted on the token); false = a session object, gone when the session closes.
CKA_TRUSTED0x00000086v3.2 §4.2 Table 13 footnote 10 — "Can only be set to CK_TRUE by the SO user." This engine enforces that more strictly than the footnote alone implies: silently dropped from C_GenerateKey templates (no error — the key is created, just without the flag), and permanently read-only via C_SetAttributeValue for every caller, SO included, once an object exists. The only live path to CKA_TRUSTED=TRUE is C_CreateObject (raw key import) on an SO session.
CKA_WRAP_WITH_TRUSTED0x00000210v3.2 §4.8/§4.10 — pins a key so it can only be wrapped by a wrapping key whose own CKA_TRUSTED=TRUE. Unlike CKA_TRUSTED itself, this one is ordinary client-settable — no SO gate.
CKM_AES_GCM0x00001087AES in Galois/Counter Mode — authenticated encryption; requires a CK_GCM_PARAMS structure (IV, AAD, tag length) as the mechanism parameter.
CKM_AES_KEY_GEN0x00001080Mechanism for C_GenerateKey to produce a fresh AES key of the requested length.
CKM_AES_KWRFC 3394 AES Key Wrap — the classic mechanism for C_WrapKey/C_UnwrapKey to move key material off/onto a token without ever exposing it in the clear.
CKM_ML_DSAPKCS#11 v3.2 §6.67 mechanism family for ML-DSA (FIPS 204) key generation, C_Sign, and C_Verify.
CKM_ML_KEMPKCS#11 v3.2 §6.68 mechanism family for ML-KEM (FIPS 203) key generation and C_EncapsulateKey/C_DecapsulateKey.
CKM_SLH_DSAPKCS#11 v3.2 §6.69 mechanism family for SLH-DSA (FIPS 205) — the stateless hash-based signature scheme, 12 named parameter sets.
CKO_PRIVATE_KEY0x00000003CKA_CLASS value for a private-key object (sign, decrypt, unwrap, decapsulate).
CKO_PROFILE0x00000009New object class introduced by PKCS#11 Profiles v3.2 §3: a token exposes one CKO_PROFILE object per conformance profile it claims — discoverable by any application via a plain C_FindObjects, no vendor-specific query needed.
CKO_PUBLIC_KEY0x00000002CKA_CLASS value for a public-key object (verify, encrypt, wrap — the non-secret half of a keypair).
CKO_SECRET_KEY0x00000004CKA_CLASS value for a symmetric-key object (AES, HMAC, ChaCha20, …) — usable for both directions of an operation pair.
CKR_ARGUMENTS_BAD0x00000007A call's arguments are malformed for the operation being attempted — e.g. a mechanism that requires parameters (like AES-GCM's IV) was called with none.
CKR_ATTRIBUTE_READ_ONLY0x00000010Returned when a template tries to change an attribute this token treats as fixed — CKA_TRUSTED, always, for any caller, is the example this curriculum uses.
CKR_ATTRIBUTE_SENSITIVEReturned by C_GetAttributeValue when the requested attribute exists but is marked CKA_SENSITIVE (or the key is CKA_EXTRACTABLE=false) — the value genuinely cannot leave the token, by design, not by bug.
CKR_KEY_NOT_WRAPPABLE0x00000069Returned by C_WrapKey when the target key's CKA_WRAP_WITH_TRUSTED=TRUE policy isn't satisfied — the wrapping key's own CKA_TRUSTED attribute is FALSE.
CKR_MECHANISM_INVALID0x00000070Returned when the mechanism named in a call isn't one the token supports for that operation — including when a key's own CKA_ALLOWED_MECHANISMS pins it to a different mechanism than the one requested.
CKR_OK0x00000000The universal PKCS#11 success code — every function returns this, and only this, on success.
CKR_SESSION_HANDLE_INVALID0x000000B3Returned when a call names a session handle the library doesn't recognize — e.g. one that was never opened, or was already closed. The honest failure a lesson can trigger on demand, with no side effects, just by passing a handle nobody opened.
CKR_USER_ANOTHER_ALREADY_LOGGED_IN0x00000104PKCS#11 login is per-token, not per-session — attempting to log in as SO while a USER session is active on the same token (or vice versa) gets this, not a silent role switch. C_Logout first.
CKR_USER_NOT_LOGGED_IN0x00000101Returned by operations that require an authenticated session (most private-key and secret-key operations) when C_Login was never called on it.

Attribute templateAn array of (type, value) pairs describing an object to create/generate, or the attributes to fetch/search on — the same CK_ATTRIBUTE[] shape used by C_CreateObject, C_GenerateKey, C_GetAttributeValue, and C_FindObjectsInit alike.
Baseline Provider profilePKCS#11 Profiles v3.2's minimum conformance profile (CKP_BASELINE_PROVIDER) — a fixed, spec-defined list of functions and mechanisms every claiming token must support, discoverable via a CKO_PROFILE object rather than vendor documentation.
CryptokiThe formal name of the PKCS#11 API itself ("Cryptographic Token Interface") — "PKCS#11" names the standard document, "Cryptoki" names the C API it defines.
Object classEvery PKCS#11 object (CKA_CLASS) is exactly one of a fixed set: public key, private key, secret key, certificate, data, domain parameters, and (new in v3.2) profile.
Sensitive vs. extractableTwo independent attributes that are easy to conflate: CKA_SENSITIVE blocks reading a key's value directly; CKA_EXTRACTABLE blocks wrapping it out at all. A key can be extractable-but-sensitive: it can leave (wrapped) but never be read in the clear on this token.
Session stateA session is Public or User (authenticated via C_Login) crossed with Read-Only or Read/Write — four states in total, e.g. "R/W User Functions" — visible via C_GetSessionInfo.
Slot vs. tokenA slot is a socket (physical or virtual) that may or may not currently hold a token; the token is the actual cryptographic device/store plugged into it. SoftHSM presents both as software.
Trust objects (CKO_TRUST / CKT_TRUST_ANCHOR)v3.2 §4.7 — a separate object class binding trusted usages (server auth, code signing, …) to a specific certificate, used to build certificate trust chains. CKT_TRUST_ANCHOR marks a certificate trusted as a root for chain validation. Not the same mechanism as CKA_TRUSTED/CKA_WRAP_WITH_TRUSTED (§4.2/§4.8, this lesson) — a different §4.7 concept this engine does not implement at all.
Validation objects (CKO_VALIDATION)v3.2 §4.15 — describes which third-party validation (e.g. NIST CMVP) a module conforms to. Session-level validation flags (§4.15.3.1, C_GetSessionValidationFlags) ARE implemented here — honestly, always empty, since this build has no such validation. Key-object-level flags (§4.15.3.2, CKA_OBJECT_VALIDATION_FLAGS) and CKO_VALIDATION objects themselves are not implemented at all — a distinct gap from trust objects above.

FIPS 203 / 204 / 205NIST's finalized PQC standards (Aug 2024): FIPS 203 = ML-KEM (key establishment), FIPS 204 = ML-DSA (signatures), FIPS 205 = SLH-DSA (hash-based signatures) — the three algorithm families PKCS#11 v3.2 adds native mechanisms for.
Grover's algorithmA quantum algorithm giving only a quadratic speedup at unstructured search — halves a symmetric key's effective strength. AES-256 loses headroom it already had to spare.
Hash-based signatureSecurity rests on nothing but the hash function's own security — the most conservative assumption class available. SLH-DSA is hash-based: tiny keys, large signatures, 12 parameter sets trading speed against size.
Hedged signingMixing fresh randomness into an otherwise-deterministic signature scheme as a defense against certain fault and side-channel attacks. PKCS#11 v3.2 exposes this as an explicit per-call choice (CKH_HEDGE_PREFERRED / CKH_HEDGE_REQUIRED / CKH_DETERMINISTIC_REQUIRED) rather than a fixed engine behavior.
KEM (Key Encapsulation Mechanism)A primitive shaped as Encapsulate (recipient's public key → ciphertext + shared secret) / Decapsulate (ciphertext + private key → the same shared secret) — the shape C_EncapsulateKey/C_DecapsulateKey add to PKCS#11 v3.2. Classical Diffie-Hellman (C_DeriveKey) is a different shape entirely.
Lattice-based cryptographySecurity rests on the hardness of geometry problems in high-dimensional lattices (e.g. Learning With Errors) — believed hard even for a quantum computer. ML-KEM and ML-DSA are lattice-based.
Shor's algorithmA quantum algorithm giving an exponential speedup at integer factorization and discrete logarithms — breaks RSA, ECDSA, ECDH outright once a large enough quantum computer exists. The reason asymmetric crypto must migrate.

Next step

Learn HSMs and PQC

The module behind this lab: how hardware security modules take on post-quantum keys.

PKCS#11 HSM PlaygroundWIP

The Cryptoki model — slots, tokens, sessions, login

Related content

PKCS#11 HSM Playground