DuoKey PKCS#11 Library

Applies to:

PKCS#11 (Cryptoki) 3.2Oracle TDEOracle Key VaultDuoKey Cockpit

Introduction

The DuoKey PKCS#11 library is a native shared library that implements the PKCS#11 (Cryptoki) 3.2 standard. Applications such as Oracle Database TDE and Oracle Key Vault load it like any HSM provider and call the standard C_* functions. The library performs no cryptography locally — every operation is sent over HTTPS to the DuoKey Cockpit, which executes it against the tenant vault or backing HSM. Key material never resides on the application host.

Packaging

Property	Value
Artifact	Linux `libdke_pkcs11.so` · Windows `dke_pkcs11.dll`
Standard	PKCS#11 (Cryptoki) 3.2
Exported symbol	`C_GetFunctionList` — the only symbol a PKCS#11 provider must export; it returns the full function table
Local cryptography	None — all operations are proxied to the DuoKey Cockpit
Manufacturer id	DuoKey

Architecture

An application never talks to the Cockpit directly. It loads the library, which turns each Cryptoki call into a single request to a Cockpit proxy endpoint; the Cockpit performs the operation and returns the result.

PKCS#11 library architecture

PKCS#11 consumerOracle TDE · Oracle Key Vault

C_* calls

libdke_pkcs11.so / dke_pkcs11.dllCryptoki 3.2 C-ABI

HTTPS clientone request per operation

Authorization: Bearer (access token)

DuoKey Cockpit proxy endpoint

Tenant vaultsoftware keystore (dev) · backend HSM (prod)

A PKCS#11 consumer loads the library, which turns each Cryptoki call into a single authenticated HTTPS request to a Cockpit proxy endpoint that performs the operation against the tenant vault.

Design points

No local crypto

The library holds no keys and runs no cryptography. It only encodes payloads and forwards them; the backend does the work.

Single exported symbol

Only C_GetFunctionList is exported; every other function is reached through the returned table.

Serial sessions

All library state is serialized behind a single lock, and only serial sessions are supported; parallel sessions are rejected with CKR_SESSION_PARALLEL_NOT_SUPPORTED.

Object-handle mapping

PKCS#11 integer handles map to server-side object identifiers; descriptors are cached and de-duplicated so the same object always returns the same handle.

Token authentication, no PIN

C_Login transmits no PIN — it just moves the session to the user state. Authentication is a per-request bearer token from the configuration.

Function coverage

The library implements the subset of Cryptoki required to manage and use keys through the Cockpit — single-part operations only. The full per-function table is on the Function Coverage page; the summary:

Category	Implemented functions
General purpose	`C_GetFunctionList`, `C_Initialize`, `C_Finalize`, `C_GetInfo`
Slot & token	`C_GetSlotList`, `C_GetSlotInfo`, `C_GetTokenInfo`, `C_GetMechanismList`, `C_GetMechanismInfo`
Session	`C_OpenSession`, `C_CloseSession`, `C_CloseAllSessions`, `C_GetSessionInfo`, `C_Login`, `C_Logout`
Objects	`C_FindObjectsInit` / `C_FindObjects` / `C_FindObjectsFinal`, `C_GetAttributeValue`, `C_DestroyObject`
Encrypt / Decrypt	`C_EncryptInit` / `C_Encrypt`, `C_DecryptInit` / `C_Decrypt` (single-part)
Sign / Verify / Digest	`C_Sign`, `C_Verify`, `C_Digest` (single-part)
Key management	`C_GenerateKey`, `C_GenerateKeyPair`, `C_WrapKey`, `C_UnwrapKey`
Random	`C_GenerateRandom` (`C_SeedRandom` is accepted and ignored)

Not supported (single-part by design)

Multi-part / streaming operations (*_Update / *_Final), dual-function crypto, C_DeriveKey, object create/copy/set-attribute (C_CreateObject, C_CopyObject, C_SetAttributeValue), and token/PIN administration (C_InitToken, C_InitPIN, C_SetPIN) return CKR_FUNCTION_NOT_SUPPORTED. C_GetFunctionStatus and C_CancelFunction return CKR_FUNCTION_NOT_PARALLEL. Master-key operations are single-part by construction, so these are intentionally omitted.

Mechanisms

C_GetMechanismList advertises the following families (C_GetMechanismInfo also sets CKF_HW). See Function Coverage for the exact list and key-size ranges.

Family	Mechanisms	Operations
AES	`CKM_AES_KEY_GEN`, `CKM_AES_CBC/CBC_PAD`, `CKM_AES_GCM`, `CKM_AES_KEY_WRAP(_PAD)`	generate, encrypt/decrypt, wrap/unwrap
RSA	`CKM_RSA_PKCS_KEY_PAIR_GEN`, `CKM_RSA_PKCS`, `CKM_RSA_PKCS_OAEP`, `CKM_RSA_PKCS_PSS`, `CKM_SHAn_RSA_PKCS`	generate, encrypt/decrypt, sign/verify, wrap/unwrap
EC	`CKM_EC_KEY_PAIR_GEN`, `CKM_ECDSA`, `CKM_ECDSA_SHA256/384`	generate, sign/verify
Digest	`CKM_SHA_1`, `CKM_SHA256/384/512`	digest (SHA-256/384/512 at the backend)
HMAC	`CKM_SHA256/384/512_HMAC`	sign/verify
Post-quantum	`CKM_ML_DSA_KEY_PAIR_GEN`, `CKM_ML_DSA`, `CKM_SLH_DSA_KEY_PAIR_GEN`, `CKM_SLH_DSA`, `CKM_ML_KEM_KEY_PAIR_GEN`	generate key pair, sign/verify (ML-KEM: key-pair generation only, no encapsulation yet)

Mechanisms used depend on the consumer

This is a general-purpose Cryptoki provider, so it advertises AES, RSA, EC, SHA and HMAC. Each application uses only what it needs. For example, Oracle TDE uses AES only — its master key is AES256 and it never uses RSA or EC (see Oracle TDE → Cockpit v2). Other integrations may use RSA or EC.

Objects & attributes

Object classes: CKO_DATA, CKO_CERTIFICATE, CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, CKO_SECRET_KEY, CKO_DOMAIN_PARAMETERS.
Key types: CKK_AES, CKK_RSA, CKK_EC, CKK_GENERIC_SECRET, CKK_DSA, CKK_DH, CKK_SHA256/384/512_HMAC, CKK_ML_DSA, CKK_SLH_DSA, CKK_ML_KEM. Post-quantum key generation also takes a CKA_PARAMETER_SET attribute selecting the concrete algorithm (e.g. ML-DSA-65, SLH-DSA-128s).
Keys are addressed by CKA_LABEL and CKA_ID; C_GetAttributeValue answers from a cached descriptor.
CKA_VALUE is never returned — it reports CKR_ATTRIBUTE_SENSITIVE, because raw key material lives only in the backend. Returned keys are marked non-extractable and sensitive.

Configuration

The library reads a TOML file whose path is given by DKE_PKCS11_CONF (Oracle / OKV set it in the wallet environment). Environment variables override the file.

pkcs11.tomlTOML

[http_config]
server_url = "https://<cockpit-host>/api/apps/<app_id>/tde/pkcs11/<access_guid>"
access_token = "<access_guid>" # sent as the bearer token
timeout_secs = 30
verify_tls = true

[pkcs11]
slot_id = 0
logging_level = "info"
logging_folder = "/var/log/dke-pkcs11"

Environment variable	Overrides
`DKE_PKCS11_CONF`	Path to the TOML file (if unset, config is built from the variables below)
`DKE_PKCS11_SERVER_URL`	`http_config.server_url`
`DKE_PKCS11_ACCESS_TOKEN`	`http_config.access_token`
`DKE_PKCS11_VERIFY_TLS`	`http_config.verify_tls`
`DKE_PKCS11_SLOT_ID`	`pkcs11.slot_id`
`DKE_PKCS11_LOGGING_LEVEL`	`pkcs11.logging_level`
`DKE_PKCS11_LOGGING_FOLDER`	`pkcs11.logging_folder`

Keep verification on

verify_tls defaults to true. Set it to false only for testing against self-signed certificates — it disables TLS certificate validation.

Consumers

Oracle Database TDE

Loads the library from /opt/oracle/extapi/64/pkcs11/ to store the TDE master key in DuoKey.

Oracle Key Vault (OKV)

HSM mode — the library is referenced from okv_hsm.conf as the generic PKCS#11 provider.

Not this library

Microsoft SQL Server EKM uses a separate provider (a CNG Key Storage Provider DLL), not the DuoKey PKCS#11 library. See the SQL EKM guide.

Introduction​

Packaging​

Architecture​

Design points​