Oracle TDE Integration with Cockpit v2
How Oracle Transparent Data Encryption connects to Cockpit v2 through the DuoKey PKCS#11 provider.
This page describes how Oracle Transparent Data Encryption connects to Cockpit v2. For the legacy Cockpit v1 path, see the Installation & Setup section of this guide.
A short demo video of the end-to-end Oracle TDE ↔ Cockpit v2 flow will be added here.
The integration chain
Oracle never talks to Cockpit v2 directly. It loads the DuoKey PKCS#11 provider (a native library), which turns each Cryptoki call into a single HTTPS request to a Cockpit v2 proxy endpoint. The proxy performs the actual cryptographic operation against the tenant vault / HSM.
Oracle never talks to Cockpit v2 directly; the provider turns each Cryptoki call into one HTTPS request.
Two properties are important to understand:
No local cryptography
The PKCS#11 library holds no keys and performs no crypto locally. Every operation is marshalled to the Cockpit v2 proxy. The TDE master key material never resides on the database host.
Single exported symbol
Oracle loads the library through the standard C_GetFunctionList entry point, which returns the full Cryptoki function table.
The Oracle TDE master encryption key is AES256. Per Oracle's documentation, "Master encryption keys always are AES256" (they encrypt the table / tablespace keys in CBC mode). Oracle TDE does not use RSA or elliptic-curve keys for the master key. The DuoKey PKCS#11 library is a general-purpose Cryptoki provider that also advertises RSA and EC mechanisms for other DuoKey integrations — but Oracle TDE exercises only the AES key-generation and encrypt/decrypt (wrap/unwrap) path.
PKCS#11 operations Oracle TDE uses
Oracle drives only the subset below. For the library's complete function table, mechanisms and attribute model, see the standalone PKCS#11 Library section — that is where the provider is documented in full.
| Cryptoki operation | Role in Oracle TDE |
|---|---|
C_Initialize / C_Finalize | Load the pkcs11.toml configuration and initialize / tear down the library. |
C_OpenSession / C_Login | Open a serial session and enter the user state. Oracle still supplies a PIN string by syntax (SET KEYSTORE OPEN IDENTIFIED BY "…") but it is advisory only — the per-request access_token bearer credential authenticates. The PIN must be a literal quoted string; IDENTIFIED BY EXTERNAL STORE raises ORA-00988 against this provider. |
C_FindObjectsInit / C_FindObjects | Locate the AES master key by CKA_LABEL / CKA_ID. |
C_GenerateKey | Create the AES256 TDE master key. |
C_Encrypt / C_Decrypt | Wrap / unwrap the table & tablespace keys under the master key. |
C_GetAttributeValue | Read key attributes; CKA_VALUE is refused (CKR_ATTRIBUTE_SENSITIVE) — master-key bytes never leave the backend. |
C_DestroyObject | Retire a master key. |
Cryptographic model
- For Oracle TDE the proxy wraps and unwraps the tablespace (table) keys under the master key using a length-preserving AES-CBC / AES-CBC-PAD mechanism. This is required: Oracle's
SET KEYexpects the unwrapped key to be exactly the size it wrapped, so an expanding AES-GCM envelope (which appends an IV and auth tag) corrupts the stored key blob and triggersORA-00600 [kcbtse_populate_tbskey_1]. The authenticated AES-GCM envelope mode is offered only as a fallback for non-TDE callers that store opaque blobs; it must not be selected on the Oracle TDE wrap path. - Master-key bytes are sensitive:
C_GetAttributeValuerefusesCKA_VALUE. With a real HSM backend, the key material never exists outside the HSM.
Master Encryption Key (MEK) lifecycle
Each master key is tracked by the Cockpit with its label (CKA_LABEL), identifier (CKA_ID), algorithm and key size, a reference to the backing vault/HSM key, and a lifecycle state.
Create
When an Oracle TDE app is created in Cockpit v2, an initial active master key is auto-provisioned (label TDE-MASTER-<date>). Additional keys can be created from the Cockpit or from the library via a key-generation call. The default algorithm is AES-256.
Open / use
Oracle opens the keystore with ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<pin>" (a literal quoted PIN — EXTERNAL STORE raises ORA-00988 against this provider) and locates the MEK through C_FindObjects. Tablespace (table) keys are protected by encrypt / decrypt under the MEK. In the software-keystore deployment mode, sealed key material is lazily re-imported into the vault after a Cockpit restart; with an HSM backend the key stays in the HSM.
Rotate
Rotating a key from the Cockpit deactivates the current key, creates a new active MEK, and returns the Oracle rotation SQL (ADMINISTER KEY MANAGEMENT SET KEY … WITH BACKUP). Old keys remain deactivated so that previously-wrapped tablespace keys stay decryptable.
State machine
Transitions are enforced server-side: only a pre_active key can be activated, and a key must be deactivated or revoked before it can be destroyed.
Transitions are enforced server-side (only a pre_active key can be activated; a key must be deactivated or revoked before it can be destroyed).
Authentication of the management vs. proxy operations
- The PKCS#11 proxy endpoint is authenticated by the
access_tokenbearer credential; theaccess_guidin the URL is only used to route the request to the right app/tenant server-side. - The management operations (create / rotate / activate / … ) require a Cockpit user session with the appropriate role-based permission, and are additionally subject to access-policy enforcement.
Continue to PKCS#11 Provider Configuration (pkcs11.toml) to configure the provider.