Overview
DuoKey integrates with Oracle Transparent Data Encryption (TDE) through the standard PKCS#11 interface, so Oracle stores and uses its TDE master encryption key in DuoKey rather than in a local wallet file on the database server. To Oracle, DuoKey presents an external HSM keystore — the master key lives in a hardened boundary and never resides on the database host.
This overview describes the current Cockpit v2 integration. For the hands-on procedure, see Getting Started; for the configuration reference, see PKCS#11 Provider Configuration (pkcs11.toml).
What is Oracle TDE?
Oracle Transparent Data Encryption encrypts sensitive data at rest in Oracle Database tables and tablespaces. It helps address privacy and security mandates such as PCI DSS, HIPAA, and GDPR.
Key Capabilities
- Transparent encryption: encrypts data at rest with no application changes
- Column encryption: encrypts specific sensitive columns
- Tablespace encryption: encrypts entire tablespaces transparently
- Backup protection: encrypted backups via RMAN
The TDE key-management challenge
Traditional approach: local wallet storage
By default, Oracle TDE keeps the master encryption key in a wallet file on the database server. If an attacker gains privileged access to the host, the wallet — and therefore the master key — is exposed. Backup, rotation, and audit are also manual and per-server.
Modern approach: an external HSM keystore
Oracle can instead store the TDE master key in an external HSM keystore reached over PKCS#11. With DuoKey you get:
- Physical key separation — the master key never sits on the database server
- Operations inside a secure boundary — wrap/unwrap happens in DuoKey; key bytes are never exported
- Centralized key management across many databases
- Complete audit trail of every key operation in the Cockpit
- Online key rotation and lifecycle management
How the master key is protected
The Oracle keystore type is HSM. Behind DuoKey Cockpit, the master key is held in the tenant vault / HSM. DuoKey's root of trust is a Multi-Party Computation (MPC) KMS, and for hardware custody DuoKey partners with Securosys HSM — our Swiss partner, FIPS 140-2 Level 3 certified. From Oracle's point of view this is simply an HSM keystore (WRL_TYPE = HSM); the MPC and HSM details are handled entirely on the DuoKey side.
DuoKey's hardware key custody is provided by Securosys HSM.
The integration chain
Oracle never talks to the Cockpit directly. It loads the DuoKey PKCS#11 provider (libdke_pkcs11.so on Linux, dke_pkcs11.dll on Windows), which turns each master-key operation into a single HTTPS call to a Cockpit v2 proxy endpoint. The proxy performs the operation against the tenant vault / HSM.
Oracle never talks to the Cockpit directly; the provider turns each master-key operation into one HTTPS call.
DuoKey is only on the master-key path — opening the keystore, SET KEY, and wrapping/unwrapping the tablespace keys. Oracle performs all bulk table and tablespace AES encryption itself, in hardware (AES-NI), so throughput for normal workloads is unaffected.
TDE key hierarchy
TDE Master Encryption Key (KEK)
Stored in DuoKey KMS
Stored encrypted in Oracle Database
Stored encrypted in Oracle Database
Application Data
Encrypted data at rest in database files
TDE master encryption key (MEK)
- An AES-256 key held in DuoKey's HSM keystore
- Used to wrap/unwrap the table and tablespace keys
- Managed by security administrators, never exported in plaintext
Table & tablespace keys (DEK)
- Stored encrypted in the database, one per encrypted table or tablespace
- Automatically managed by Oracle
- Wrapped/unwrapped by the MEK held in DuoKey
Authentication model
Cockpit v2 authenticates the provider with an access_token bearer credential, carried in the pkcs11.toml file and sent as Authorization: Bearer on every request. The access_guid embedded in the proxy server_url is a separate, non-secret routing identifier — the tenant is resolved server-side from the (app_id, access_guid) pair, and the request is separately authenticated by the access_token. There is no OAuth2, no client ID/secret, no username/password, and no tenant header. See PKCS#11 Provider Configuration (pkcs11.toml).
Key features
Secure key storage
- Master key held in DuoKey's HSM keystore, backed by Securosys HSM in production
- Master-key bytes never leave the backend;
CKA_VALUEis refused to Oracle - Tamper-evident key operations
Transparent operation
- No application changes
- Compatible with Oracle Database features, including RAC, Data Guard, and RMAN
Centralized management
- Manage keys for many databases from a single Cockpit
- Automated key lifecycle and rotation
- Complete audit trail per app
Master key lifecycle
The master key is created when the Oracle TDE app is provisioned in the Cockpit (an initial AES-256 active key). Rotation makes a new key active and deactivates but keeps the previous key, so tablespace keys wrapped under the old master key remain decryptable.
Create master key
Periodic rotation
Wallet backup
Benefits
For security teams
- Separation of duties: DBAs manage the database, security admins manage keys
- Regulatory compliance: helps meet PCI DSS, HIPAA, and GDPR requirements
- Centralized control and reduced risk — keys never sit on the database host
For database administrators
- Compatibility with Oracle RAC, Data Guard, and RMAN
- Performance: bulk encryption stays local on AES-NI; only the master-key path calls DuoKey
- Simplified operations with Cockpit-generated deployment bundles
For organizations
- Cost efficiency through centralized management
- Scalability: add new databases as separate apps
- Future-proof: a standards-based PKCS#11 interface
Supported Oracle versions
For Oracle 11g R2, ensure patch 18948524 is applied. Without it, Oracle never even attempts to load a PKCS#11 library — see the version-differences table below.
Version differences that actually matter
Every release speaks HSM/PKCS#11 in principle, but three things change underneath depending on which release and platform you're on — get any of these wrong and you see a generic-looking ORA-28353/ORA-28376/ORA-28407 with no obvious cause. Keystore config mechanism is the big one: WALLET_ROOT (an instance parameter, SPFILE-scoped, needs a bounce) versus the older sqlnet.ora ENCRYPTION_WALLET_LOCATION stanza — these are not interchangeable, and using the wrong one for your release fails silently or with an unrelated-looking error.
Keystore configuration and SQL grammar by release
| Release | Multitenant (CDB/PDB) | Keystore config | Master-key SQL |
|---|---|---|---|
| 11g R2 (11.2.0.x) | No | sqlnet.ora ENCRYPTION_WALLET_LOCATION | ALTER SYSTEM SET ENCRYPTION WALLET/KEY (pre-ADMINISTER KEY MANAGEMENT grammar) |
| 12.1.0.x | Yes | sqlnet.ora ENCRYPTION_WALLET_LOCATION (WALLET_ROOT not yet introduced) | ADMINISTER KEY MANAGEMENT — but CREATE TABLESPACE ... ENCRYPTION needs DEFAULT STORAGE(ENCRYPT), not the later ... ENCRYPT shorthand |
| 12.2.0.1.0 (base release) | Yes | sqlnet.ora ENCRYPTION_WALLET_LOCATION — WALLET_ROOT and TDE_CONFIGURATION do not exist yet (ORA-02065 on either, confirmed absent from v$parameter) | ADMINISTER KEY MANAGEMENT |
| 12.2 (later Release Update) / 18c | Yes | WALLET_ROOT (SPFILE-scoped, requires an instance bounce) | ADMINISTER KEY MANAGEMENT |
| 19c | Yes | WALLET_ROOT | ADMINISTER KEY MANAGEMENT (CONTAINER=ALL at the root opens every PDB's keystore in one call) |
| 21c | Yes | WALLET_ROOT | ADMINISTER KEY MANAGEMENT |
| 23ai and later | Yes | WALLET_ROOT | ADMINISTER KEY MANAGEMENT |
Live-testing status by release and platform
This is a live record of what DuoKey has actually run end to end versus what's inferred from Oracle's own documentation — not a compatibility promise. "Confirmed" means a real SET KEY + encrypted-tablespace round trip succeeded against that exact release; "Blocked" means it was tried and fails for a known, understood reason; "Not tested" means exactly that, no more and no less.
| Release | Windows | Linux |
|---|---|---|
| 11g R2, unpatched (11.2.0.1 / 11.2.0.2) | ⛔ Blocked, confirmed — ORA-28376, missing patch 18948524; Oracle never attempts PKCS#11 discovery at all. Reproduced on a genuine 11.2.0.1.0 Enterprise Edition install (real Oracle installer media, not a community image) with the library correctly staged, DKE_PKCS11_CONF confirmed visible in-instance, and the service account (LocalSystem on this release — not the later per-service virtual account) ruling out permissions | ⛔ Blocked, confirmed — same signature, reproduced on gvenzl/oracle-xe:11-slim (11.2.0.2). Oracle XE cannot be individually patched (no opatch), so this is a permanent dead end on XE specifically |
| 11g R2, patched (11.2.0.4 + patch 18948524, or a patched EE/SE install) | ❔ Not tested — no patched installer media available at time of writing | ❔ Not tested — same reason |
| 12.1.0.x | ❔ Not tested | ✅ Confirmed end-to-end — Oracle's own official 12.1.0.2 Enterprise Edition container image; also the run that proved the fixed /opt/oracle/extapi/... path (real ORACLE_BASE on this image is /u01/app/oracle) — see Getting Started |
| 12.2.0.1.0 (base release) | ❔ Not tested | ✅ Confirmed end-to-end — genuine Enterprise Edition built from real installer media (not a community image); keystore open, SET KEY at CDB root + PDB, encrypted tablespace + data round trip |
| 12.2 (later RU) / 18c | ❔ Not tested | ❔ Not tested |
| 19c | ⚠️ Attempted, not clean — hit a rare, non-deterministic Oracle-side crash (ORA-07445 [kzthsminit_discover_load_pkcs_lib], see the note below); not re-run to a clean pass | ✅ Confirmed end-to-end — Oracle's own official 19.3.0.0 Enterprise Edition container image (Oracle Linux 7.9 / glibc 2.17) |
| 21c | ✅ Confirmed end-to-end — Oracle 21.3.0.0.0 Enterprise Edition | ✅ Confirmed end-to-end — Oracle XE 21c |
| 23ai and later | ❔ Not tested | ❔ Not tested |
Reproduced independently against multiple PKCS#11 libraries (including a genuine third-party HSM vendor's binary) with no pattern tied to any specific library — it is not a DuoKey configuration problem. The exact same configuration that crashes once has been observed completing normally on retry. Also seen on Linux (Oracle 12.1.0.2), through a different kernel function (kzekmsmk, during the HSM heartbeat check) than the Windows occurrences (kzthsminit_*) — confirming this is a broad characteristic of Oracle's own PKCS#11 kernel integration, not one localized bug. See Troubleshooting for the full incident-trace analysis.
A second, orthogonal thing that changes per host, not per Oracle version: the libdke_pkcs11.so build must match your database host's actual glibc (ldd --version) — don't infer it from the Oracle release. Oracle's own official 19.3.0.0 Enterprise Edition image runs Oracle Linux 7.9 (glibc 2.17), for example, even though 19c is a "newer" release. See System requirements and Troubleshooting.
A third thing that changes only on Windows: the fixed PKCS#11 library discovery path (C:\oracle\extapi\64\hsm\...) and the Oracle service account's file permissions on pkcs11.toml — see Getting Started on Windows.
DuoKey's own engineering runbooks are actively validated against Oracle Database 12.2 and later, or Oracle Key Vault — see the live-testing table above for exactly what's confirmed versus inferred at each release and platform. If you are integrating 11g R2 or 12.1, confirm current compatibility with your DuoKey contact before deployment.
Deployment scenarios
Enterprise database consolidation
Centrally manage TDE keys for many Oracle databases with unified policies and automated rotation.
Cloud migration
Keep control of the encryption keys when moving databases to cloud providers using BYOK approaches.
Regulatory compliance
Meet stringent compliance requirements with an external HSM keystore and comprehensive audit trails.
Encryption options
Selective encryption
- Specific columns only
- SALT/NO SALT options
- 5-15% overhead
- Index limitations
Recommended approach
- Entire tablespace
- Better performance
- 2-5% overhead
- No index impact
Encrypted backups
- Automatic encryption
- Transparent restore
- Key required
- No performance hit
Performance characteristics
The numbers below are indicative targets that depend on your hardware, workload, network, and topology. Benchmark against your own environment before relying on them for capacity planning.
- Bulk encryption: performed locally by Oracle using AES-NI; the master-key path to DuoKey is not in the row-level data path
- Column encryption: 5–15% overhead for encrypted columns
- Tablespace encryption: 2–5% overhead for most workloads
- Master-key operations: keystore open,
SET KEY, and rotation only touch DuoKey
System requirements
Oracle Database
- Supported Oracle Database version (11g R2 through 23ai)
- Oracle Advanced Security option licensed
- Network connectivity to the DuoKey Cockpit host (HTTPS)
DuoKey
- Access to DuoKey Cockpit v2
- The DuoKey PKCS#11 provider library, built to match your database host's glibc (confirm with
ldd --version, don't assume from the Oracle version) - An Oracle TDE app and its deployment bundle
Operating system
- Linux: confirm the exact OS/glibc of your database host with DuoKey before requesting a build — for example, Oracle's own official 19.3.0.0 Enterprise Edition image runs Oracle Linux 7.9 / glibc 2.17, not OL8
- The provider library must match the platform's glibc; see Getting Started
Getting started
Ready to integrate Oracle TDE with DuoKey? Follow Getting Started — the single step-by-step quick-start, from creating the app in Cockpit through verifying encrypted data. It links out to the PKCS#11 Provider Configuration reference and to Troubleshooting where relevant.
Security considerations
Key protection
- Master keys never leave DuoKey in plaintext
- Backed by Securosys HSM in production
- Secure key generation
Access control
- Role-based access control (RBAC) in the Cockpit
- Separation of duties between DBAs and security admins
- An
access_tokenbearer credential per app; theaccess_guid(a non-secret routing id in the proxy URL) is resolved to a tenant server-side
Network security
- TLS for all communications (
verify_tls = trueby default) - Firewall rules for HTTPS to the Cockpit host
Support
- Email: [email protected]
- Documentation: DuoKey Support
- Status: status.duokey.com