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

PKCS#11 interface layer

Oracle Database

Oracle TDEPKCS#11 calls

Cryptoki calls

PKCS#11 Interface Layer

Cryptoki functionsC_Initialize, C_OpenSession, C_GenerateKey, C_Encrypt, ...

Session managementstate and isolation

Object-handle managementhandle to key-id mapping

DuoKey SDK Layer

Carries operations to Cockpit

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:

Session lifecycle

Uninitialized

C_Initialize()

Initialized

C_OpenSession()

Session open

C_Login()

Session logged inCan perform operations:find master key, wrap / unwrap keys

Forward transitions shown. In reverse: C_Logout returns to session open, C_CloseSession returns to initialized, 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.

Handle mapping

Oracle usesinteger object handle (e.g. 0x12345)

library maps to

DuoKey key identifier

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:

Condition	PKCS#11 code
Cockpit unreachable / backend error	CKR_DEVICE_ERROR
Authentication failure	CKR_PIN_INCORRECT
Unknown object handle	CKR_OBJECT_HANDLE_INVALID
Invalid parameter	CKR_ARGUMENTS_BAD
Unsupported mechanism	CKR_MECHANISM_INVALID
Sensitive attribute requested	CKR_ATTRIBUTE_SENSITIVE

Next Steps

• DuoKey SDK Layer → - How operations reach DuoKey Cockpit
• Object Handle Mapping → - Understand handle translation
• Communication Flow → - See how operations flow through the system