Architecture Overview
How the DuoKey PKCS#11 library bridges Oracle Database TDE with the DuoKey Cockpit cloud HSM platform.
The DuoKey PKCS#11 library is a software implementation of the PKCS#11 (Cryptoki) standard that connects Oracle Database TDE to the DuoKey Cockpit platform. It presents a standard Cryptoki surface to Oracle and, for each master-key operation, forwards the request over HTTPS to Cockpit, which performs the operation against the tenant keystore. The design is organized into clean layers that each own a specific responsibility.
Oracle uses the library for the TDE master-key path only — opening the keystore, SET KEY, and wrapping / unwrapping the tablespace and table keys under the master key. Bulk tablespace data encryption stays local on the database host, hardware-accelerated by AES-NI. Only the small master-key operations cross the network.
High-Level Architecture
Oracle Database issues standard PKCS#11 calls; the library forwards the master-key operations over HTTPS to DuoKey Cockpit, which performs them against the tenant keystore. In production this keystore is backed by a Securosys HSM; a DuoKey software keystore is used in development. Master-key material never leaves the platform.
Architecture
High-level architecture
The library on the database host reads pkcs11.toml and forwards master-key operations over HTTPS, with the access_token bearer credential, to Cockpit and its tenant keystore.
Each layer is independent and replaceable — Oracle compatibility, Cockpit communication, and key management are cleanly separated, so a change in one layer never ripples into the others.
Key Components
PKCS#11 Interface Layer
Presents the standard PKCS#11 (Cryptoki) surface to Oracle — session management, object handles, mechanism handling, and attribute handling.
DuoKey SDK Layer
Carries each Cryptoki operation to DuoKey Cockpit over HTTPS, authenticated by an access_token bearer credential, with serialization, retries, and error translation.
Object Handle Mapping
Bridges PKCS#11 integer object handles with DuoKey's key identifiers, maintaining per-session mapping tables for dynamic lookup.
Cryptographic Mechanisms
The Cryptoki mechanisms Oracle TDE exercises — AES key generation and the length-preserving AES-CBC / AES-CBC-PAD wrap path.
Configuration System
A pkcs11.toml file (server URL + access_token) with optional DKE_PKCS11_* environment-variable overrides — container-friendly and simple to deploy.
Communication Flow
Request/response handling with error translation, retry logic, and connection reuse.
Data Flow
A typical open-keystore → provision master key → wrap tablespace key sequence flows through every layer, from Oracle down to the backend keystore and back. Note that only the master-key operations travel to Cockpit — the tablespace bulk data is encrypted locally under the (unwrapped) tablespace key.
Sequence
Initialize and provision the master key
The library initializes against Cockpit with its bearer credential, then Cockpit generates the AES-256 master key in the keystore and Oracle receives a handle.
Sequence
Wrap a tablespace key
Only the master-key operations travel to Cockpit; tablespace bulk data is encrypted locally under the unwrapped tablespace key.
Benefits of This Architecture
Separation of Concerns
Each layer owns one responsibility: the PKCS#11 layer handles Oracle compatibility, the SDK layer handles Cockpit communication, and Cockpit handles key management.
Scalability
Supports multiple concurrent Oracle sessions, multiple database instances, and high-throughput operations — bulk data crypto stays local, so only master-key calls cross the network.
Security
Master-key material never leaves the keystore, transport is TLS-encrypted, access is bearer-token authenticated, and every operation is audit-logged in the Cockpit.
Flexibility
A Securosys HSM or DuoKey software keystore behind the same interface, simple file-plus-env configuration, and container-based deployment.
Across every layer, the TDE master key is generated, stored, and used inside the DuoKey Cockpit keystore (a Securosys HSM in production). The library only ever exchanges object handles and wrapped keys — never raw master-key material.