Skip to main content

PKCS#11 Interface Layer

The PKCS#11 Interface Layer is the topmost component that Oracle Database talks to. It presents the standard PKCS#11 (Cryptoki) C surface that Oracle expects, and translates each call into a request that the lower layers carry to DuoKey Cockpit.

Overview​

Architecture

PKCS#11 interface layer

The PKCS#11 interface layerOracle's Cryptoki calls enter the interface layer, which manages sessions and object handles before handing each operation to the DuoKey SDK layer.ORACLE DATABASEPKCS#11 INTERFACE LAYERDUOKEY SDK LAYERCRYPTOKIOPERATIONOracle TDEPKCS#11 callsSession managementstate · isolationObject-handle mgmthandle to key idCryptoki functionsC_Initialize · C_OpenSession · C_GenerateKey · C_Encrypt …DuoKey SDKcarries ops to CockpitLEGENDCryptoki surface Oracle callsLayer componentOracleCall

Oracle's Cryptoki calls enter the interface layer, which manages sessions and object handles before handing operations to the SDK layer.

Responsibilities​

Cryptoki function surface​

The layer implements the standard PKCS#11 (Cryptoki) functions that Oracle TDE drives. Oracle loads the library through the standard C_GetFunctionList entry point and uses a focused subset:

  • Initialization: C_Initialize, C_Finalize
  • Slot / token: C_GetSlotList, C_GetTokenInfo
  • Session: C_OpenSession, C_CloseSession, C_Login, C_Logout
  • Object: C_FindObjectsInit, C_FindObjects, C_GetAttributeValue, C_DestroyObject
  • Key: C_GenerateKey
  • Cryptographic (wrap / unwrap): C_Encrypt, C_Decrypt (single-part only — the multi-part …Update / …Final forms are not implemented and return CKR_FUNCTION_NOT_SUPPORTED, which is not a limitation for Oracle TDE since its master-key operations are single-part by construction)

Session management​

The layer maintains session state and supports multiple concurrent sessions.

Session lifecycle:

State machine

Session lifecycle

PKCS#11 session lifecycleC_Initialize, C_OpenSession and C_Login move a session forward to the logged-in state; C_Logout, C_CloseSession and C_Finalize move it back.C_InitializeC_FinalizeC_OpenSessionC_CloseSessionC_LoginC_LogoutUninitializedInitializedSession openLogged infind · wrap · unwrapLEGENDTransition (Cryptoki call)Ready for master-key operations

C_Initialize, C_OpenSession and C_Login move a session forward; C_Logout, C_CloseSession and C_Finalize step it back, and C_Finalize tears down the library.

Features:

  • Multiple sessions: supports concurrent sessions per slot.
  • State tracking: tracks whether a session is open and in the user state.
  • Isolation: each session has its own object-handle mapping table.
  • Cleanup: releases resources when a session closes.
The PIN reaches Oracle's API, not Cockpit

C_Login enters the user state; Oracle still supplies a PIN by syntax (advisory only — it must be a literal quoted string, since IDENTIFIED BY EXTERNAL STORE raises ORA-00988 against this provider). Authentication to Cockpit is by the access_token bearer credential carried with each request, not the PIN (see the DuoKey SDK Layer).

Object-handle management​

Oracle references objects by integer handles, while DuoKey Cockpit references keys by durable identifiers. The interface layer maps between them per session — see Object Handle Mapping for the full model.

Architecture

Handle mapping

Object handle mappingA per-session mapping table translates Oracle's integer object handles to DuoKey's durable key identifiers and back.PKCS#11 · ORACLE SIDEMAPPING SYSTEMDUOKEY COCKPITLOOKUPRETURNTRANSLATEREVERSE LOOKUPORACLEInteger handlee.g. 0x12345LIBRARYMapping tableper sessionCOCKPITKey identifierdurable UUID stringLEGENDPer-session mapping tableForward: handle to identifierReverse

The library maps Oracle's integer object handle to DuoKey's key identifier, per session.

Mechanism handling​

The layer accepts the standard Cryptoki mechanisms Oracle TDE uses — CKM_AES_KEY_GEN for the master key and CKM_AES_CBC_PAD for wrapping the table and tablespace keys — and carries the operation and its parameters (IV, padding) to the lower layers. See Cryptographic Mechanisms for details, including why the length-preserving AES-CBC path is required for TDE.

Attribute handling​

The layer processes PKCS#11 attribute templates for object creation and search. Common attributes:

  • CKA_CLASS — object class (secret key, data object)
  • CKA_KEY_TYPE — key type (e.g. CKK_AES)
  • CKA_LABEL / CKA_ID — used to locate the master key
  • CKA_ENCRYPT / CKA_DECRYPT / CKA_WRAP / CKA_UNWRAP — capability flags

CKA_VALUE is sensitive: C_GetAttributeValue refuses it (CKR_ATTRIBUTE_SENSITIVE), so master-key bytes are never returned to the caller.

Key Functions​

C_Initialize​

Reads the pkcs11.toml configuration and establishes the connection to DuoKey Cockpit.

  • Reads the configuration file (or DKE_PKCS11_* environment overrides).
  • Prepares the HTTPS client with the access_token bearer credential.
  • Verifies connectivity to Cockpit.
  • Returns CKR_OK on success, or CKR_DEVICE_ERROR if Cockpit cannot be reached.

C_OpenSession​

Opens a session with the token, initializes session state, and creates the session's object-handle mapping table.

C_Login​

Enters the user state. No PIN is transmitted — the per-request bearer token is the credential — so this call validates readiness rather than performing an interactive login.

C_GenerateKey​

Provisions the AES-256 master key: validates the mechanism, parses the attribute template, requests key creation in Cockpit, maps the returned key identifier to a handle, and returns the handle to Oracle.

C_FindObjects​

Locates the master key by CKA_LABEL / CKA_ID, mapping each matching key to a session handle.

C_Encrypt / C_Decrypt​

Wraps / unwraps the table and tablespace keys under the master key. Only the single-part form is supported (the multi-part …Update / …Final forms return CKR_FUNCTION_NOT_SUPPORTED); the layer resolves the handle to a key identifier, carries the operation to Cockpit, and returns the result.

Error Handling​

The layer translates lower-layer and transport errors into standard Cryptoki return codes so Oracle sees consistent results:

ConditionPKCS#11 code
Cockpit unreachable / backend errorCKR_DEVICE_ERROR
Authentication failureCKR_PIN_INCORRECT
Unknown object handleCKR_OBJECT_HANDLE_INVALID
Invalid parameterCKR_ARGUMENTS_BAD
Unsupported mechanismCKR_MECHANISM_INVALID
Sensitive attribute requestedCKR_ATTRIBUTE_SENSITIVE

Next Steps​