p11ex --- PKCS#11 bindings for Elixir

p11ex is an Elixir library that provides access to the PKCS#11 interface for cryptographic tokens such as Hardware Security Modules and smartcards. The library exposes most PKCS#11 functionality to Elixir, though it is not yet feature complete. Available functions include:

• C_GetSlotList: List tokens
• C_GetTokenInfo: Retrieve information about a token
• C_OpenSession: Open a new PKCS#11 session
• C_CloseSession: Close a PKCS#11 session
• C_CloseAllSessions: Close all open sessions for a token
• C_GetSessionInfo: Retrieve status information about a session
• C_GetInfo: Retrieve general information about the loaded PKCS#11 module
• C_Login: Authenticate an open session
• C_Logout: Deauthenticate an open session
• C_GenerateKey: Generate a symmetric key
• C_FindObjects: Search for objects stored in the token
• C_GetAttributeValue: Retrieve attributes of an object
• C_EncryptInit, C_Encrypt, C_EncryptUpdate, and C_EncryptFinal: Encryption in chunks and as a complete block
• C_DecryptInit, C_Decrypt, C_DecryptUpdate, and C_DecryptFinal: Decryption in chunks and as a complete block
• C_GenerateRandom: Generate random bytes using the token
• C_SeedRandom: Mix additional seed material into the token's RNG
• C_DestroyObject: Delete objects in the token or session
• C_GetMechanismList: List cryptographic mechanisms supported by token
• C_GetMechanismInfo: Retrieve information about a mechanism
• C_SignInit, C_Sign, C_SignUpdate, C_SignFinal: Sign data in chunks and as a complete block
• C_VerifyInit, C_Verify: Verify a signature
• C_DigestInit, C_Digest, C_DigestUpdate, C_DigestFinal: Compute a hash digest in the token
• C_GenerateKeyPair: Generate asymmetric key pair
• C_WrapKey: Encrypt an extractable key and make it exportable
• C_UnwrapKey: Decrypt an exported key into the token
• C_DeriveKey: Derive a key from a base key (e.g. ECDH)

Some PKCS#11 functions require mechanism parameters as arguments. Common parameter types are supported and documented in the Elixir documentation.

Not Yet Supported

The following are not (yet) available. If you need one of them, please open an issue.

• Object creation and modification: C_CreateObject, C_SetAttributeValue, C_CopyObject. Key material and certificates can only enter a token via generation or C_UnwrapKey, and attributes cannot be changed after an object is created.
• Multi-part verification: C_VerifyUpdate and C_VerifyFinal. Signatures over large inputs must be verified with C_Verify in one call.
• Token administration: C_InitToken, C_InitPIN, C_SetPIN. Use softhsm2-util or pkcs11-tool to initialize tokens and manage PINs.
• Mechanism parameters for mechanisms other than AES-GCM, AES-CBC/CBC-PAD/OFB, AES-CTR, AES-CCM, AES-CMAC-GENERAL, RSA-PSS (CKM_RSA_PKCS_PSS only, see below), RSA-OAEP, EdDSA and ECDH1-DERIVE. Notably, the CFB/CTS/XTS modes, CKM_RSA_AES_KEY_WRAP and the HKDF and SP800-108 key derivation mechanisms cannot be used yet. Mechanisms that take no parameters work regardless of whether they are named in the library.
• RSA-PSS mechanisms that digest on the token: CKM_SHA1_RSA_PKCS_PSS, CKM_SHA224_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS and CKM_SHA512_RSA_PKCS_PSS. These take CK_RSA_PKCS_PSS_PARAMS as well, but the parameters are only wired up for CKM_RSA_PKCS_PSS. Use CKM_RSA_PKCS_PSS instead and digest the data before signing.
• PKCS#11 3.0 additions: the module is loaded via C_GetFunctionList, so the 3.0 function set is unavailable. This includes the message-based API (C_EncryptMessage and friends), C_LoginUser and C_SessionCancel.
• Miscellaneous: C_WaitForSlotEvent, C_GetObjectSize, C_DigestKey, the operation-state functions and the legacy recovery and dual-function operations.

Tested PKCS#11 Modules

The test suite runs automatically against three software tokens:

kryoptic and NSS each provide a single token, so the tests that need two tokens run on SoftHSM only. Tests that depend on one module's behaviour are tagged in the suite (@tag :<module>_only, @tag unsupported_on: :<module>).

Additional tests are available for the Yubikey PKCS#11 module, though these do not run automatically as part of the build.

Concurrency and Schedulers

All PKCS#11 NIFs in p11ex run on the dirty I/O scheduler pool to prevent blocking the normal schedulers when calling slow HSM operations (network round-trips, USB transactions). This ensures the Erlang VM remains responsive even during long-running cryptographic operations.

For high-concurrency applications using network-attached HSMs, you may need to increase the dirty I/O scheduler pool size using the +SDio emulator flag (default is 10 threads). Example:

ERL_FLAGS="+SDio 20" mix test

Telemetry

p11ex emits :telemetry events for every operation that reaches the PKCS#11 module, plus session, token and module lifecycle events. This lets a host application track per-operation latency and error rates by PKCS#11 return code, which is what you need when the token is a network HSM. No reporter or metrics backend is bundled; attach your own handlers.

:telemetry.attach("p11ex-latency", [:p11ex, :session, :operation, :stop], fn _event, measurements, metadata, _config ->
  duration = System.convert_time_unit(measurements.duration, :native, :microsecond)
  IO.puts("#{metadata.operation} took #{duration}us (#{metadata.result})")
end, nil)

See the Telemetry guide for the full event reference, including which values are deliberately never emitted.

p11ex_cli --- CLI program to use PKCS#11 tokens

The project also includes a CLI program named p11ex_cli for working with cryptographic tokens. This program provides access to key p11ex functions.

Available Commands

• list-slots: List available PKCS#11 slots/tokens
• list-objects: List objects (keys, certificates) on a token
• key-gen-aes: Generate AES symmetric keys
• export-pubk: Export public keys (RSA, EC, EdDSA)
• sign: Sign data with RSA, EC, or EdDSA algorithms
• key-wrap / key-unwrap: Wrap/unwrap keys for secure transport
• kcv-gen: Compute Key Check Value (fingerprint) of secret keys
• bench-aes-encrypt-block: Benchmark AES encryption performance

For detailed documentation on each command, run p11ex_cli <command> --help.

EdDSA Support

p11ex_cli supports EdDSA signatures (Ed25519, Ed448). Use the sign command with the eddsa mechanism and digest none, since EdDSA signs the full message:

p11ex_cli sign --module /path/to/pkcs11-module.so --token-label my-token --pin-file pin.txt \
  eddsa none label:my-ed25519-key input.txt output.sig

Release Process

Releases are made with manually triggered Forgejo Actions workflows on Codeberg: the library goes to Hex.pm, followed by optional Codeberg release notes and p11ex_cli binaries. See RELEASE.md for the checklist, the required secrets and troubleshooting.