Skip to main content

Key Management

This guide covers master key operations for Oracle TDE with DuoKey KMS, including key rotation, migration scenarios, and key lifecycle management.

Deleting or Destroying a Master Key — Blast Radius​

Deleting a key is not a single, uniform action — what actually happens depends on where you delete it, and the consequences can range from "nothing happens" to "every database using that key becomes permanently unreadable."

Deleting the key from the Cockpit Keys UI/API does not break TDE​

Removing a key via the general-purpose Keys screen (or DELETE /api/keys/{id}) only soft-deletes that key's row and best-effort clears the shared vault's copy. The Oracle TDE master key keeps its own, independent, sealed copy of the key material tied to the TDE app registration. The PKCS#11 provider transparently re-imports from that sealed copy the next time Oracle calls it — encryption and decryption keep working even though the key shows as deleted in the Keys UI. Do not use this action as a "does TDE really depend on the key" test; it will not demonstrate anything.

Destroying the master key from the Oracle TDE app is permanent and irrecoverable​

The TDE-specific destroy action (via the Oracle TDE app's key management, or the destroy_object PKCS#11 operation) marks the master key destroyed and wipes its sealed key material. There is no fallback copy left to re-import, and there is no undelete/restore path for an individual key or master key (unlike tenants or snapshots, which do have a restore mechanism). Once destroyed:

  • Any tablespace, table, or column encrypted under that master key becomes permanently unreadable the moment Oracle needs to re-derive a table/tablespace key through it (a fresh SET KEYSTORE OPEN, an uncached data block, or a database restart).
  • This is the intended security behavior of TDE with an external KMS — losing the master key is supposed to make the data cryptographically inaccessible (it is also the mechanism behind crypto-shredding, see Best Practices → GDPR Compliance). There is no "recovery" step to offer here; treat it as equivalent to physically destroying an HSM key.

Shared-server blast radius: one master key can protect more than you think​

Oracle's TDE master key is scoped per CDB (a CONTAINER=ALL command applies to every PDB inside that one CDB, not to other, separate Oracle instances). In principle, destroying the master key used by a test database should not affect a completely different production database on the same physical/virtual server — as long as each database instance has its own, independent PKCS#11 configuration pointing at its own Oracle TDE app in Cockpit.

The failure mode to watch for: the PKCS#11 library path (/opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so) is conventionally installed under the shared ORACLE_BASE, not under a per-ORACLE_HOME/per-SID path. If several Oracle instances on the same host share the same ORACLE_BASE and were set up (by mistake, or by copy-pasting the same pkcs11.toml) to use the same access_guid/app, they are all using the same master key under the hood — destroying it breaks every database that shares it, test or production.

Before running any destructive key test on a shared server, verify isolation:

# On EACH Oracle instance/SID present on the host, as the oracle OS user:
echo "SID=$ORACLE_SID  DKE_PKCS11_CONF=$DKE_PKCS11_CONF"
grep -E 'server_url|access_token' "$DKE_PKCS11_CONF"

Confirm every instance's server_url embeds a different access_guid (and ideally a different app_id) before assuming a destructive test on one database is isolated from the others. If two instances show the same access_guid, they share a master key and a destructive test on either one will affect both.

Key Rotation​

Periodic key rotation is a critical security best practice. DuoKey KMS makes it simple to rotate TDE master encryption keys.

Why Rotate Keys?​

  • Security Compliance: Meet regulatory requirements (typically 6-12 months)
  • Limit Exposure: Reduce risk if a key is compromised
  • Best Practice: Industry standard for cryptographic key management

Rotation Frequency​

Recommended Schedule:

  • Production Databases: Every 6-12 months
  • High-Security Environments: Every 3-6 months
  • Compliance Requirements: As mandated by regulations

Rotating Master Keys​

Without Auto-Login Wallet​

For Container Database (CDB):

-- Rotate master key for all containers
ADMINISTER KEY MANAGEMENT SET KEY 
  IDENTIFIED BY "<keystore_pin>" 
  CONTAINER = ALL;

For Non-Container Database:

-- Rotate master key
ADMINISTER KEY MANAGEMENT SET KEY 
  IDENTIFIED BY "<keystore_pin>";

With Auto-Login Wallet​

For Container Database (CDB):

-- Rotate master key with auto-login
ADMINISTER KEY MANAGEMENT SET KEY 
  FORCE KEYSTORE 
  IDENTIFIED BY "<keystore_pin>" 
  CONTAINER = ALL;
Pluggable Databases

In some database versions, you may need to rotate keys individually within each pluggable database (PDB).

For Non-Container Database:

-- Rotate master key with auto-login
ADMINISTER KEY MANAGEMENT SET KEY 
  FORCE KEYSTORE 
  IDENTIFIED BY "<keystore_pin>";

Verify Key Rotation​

-- Check master key history
SELECT key_id, creation_time, activation_time 
FROM v$encryption_keys 
ORDER BY creation_time DESC;

-- Verify current key
SELECT * FROM v$encryption_wallet;

Post-Rotation Considerations​

Database Restart

After key rotation, the older master key may be accessed by the database Gen0 process for heartbeat operations. The new key will be used after the next database restart.

Restart the database to use the new key:

SHUTDOWN IMMEDIATE;
STARTUP;

Migrating from Local Wallet to DuoKey KMS​

If you have existing TDE databases using local wallets, you can migrate to DuoKey KMS.

Prerequisites​

  • Existing Oracle Database with TDE configured
  • Local TDE wallet (ewallet.p12)
  • DuoKey KMS configured per Getting Started guide
  • PKCS#11 library installed and configured

Migration Steps​

Step 1: Backup Current Wallet​

# Backup existing wallet
cp $ORACLE_BASE/admin/$ORACLE_SID/wallet/tde/ewallet.p12 \
  $ORACLE_BASE/admin/$ORACLE_SID/wallet/tde/ewallet.p12.backup

Step 2: Move Auto-Login Wallet (if exists)​

# Rename auto-login wallet
cd $ORACLE_BASE/admin/$ORACLE_SID/wallet/tde
mv cwallet.sso cwallet.sso_backup

Step 3: Change Local Wallet Password​

Set a new local wallet password (any non-empty value — see note below):

-- Change wallet password
ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD 
  IDENTIFIED BY "<old_wallet_password>" 
  SET "<keystore_pin>" 
  WITH BACKUP;

For Oracle 11g R2:

# Use orapki utility
orapki wallet change_pwd \
  -wallet $ORACLE_BASE/admin/$ORACLE_SID/wallet/tde \
  -oldpwd old_password \
  -newpwd new_keystore_pin
This PIN is advisory, not the DuoKey credential

Oracle requires a non-empty, literal quoted PIN/password value by syntax, but it does not authenticate you to Cockpit v2 and does not need to match anything in DuoKey (IDENTIFIED BY EXTERNAL STORE raises ORA-00988 against this provider — always use a literal string). The real credential is the app's access_guid, carried as the bearer token in the access_token field of pkcs11.toml — every request to Cockpit v2 is authenticated with it, and C_Login does not inspect the PIN at all.

Step 4: Configure Wallet Method​

For Oracle 18c and earlier:

-- Set wallet method to both FILE and HSM
ALTER SYSTEM SET ENCRYPTION_WALLET_LOCATION=
  '(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=<wallet_location>)))'
  SCOPE=SPFILE;

-- Restart database
SHUTDOWN IMMEDIATE;
STARTUP;

For Oracle 19c and later:

-- Set TDE configuration for HSM and FILE
ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM|FILE'
  SCOPE=BOTH;

Step 5: Open Both Wallets​

-- Open both HSM and local wallets
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN
  IDENTIFIED BY "<keystore_pin>";

-- Verify both wallets are open
SELECT * FROM V$ENCRYPTION_WALLET;

Expected output: Both FILE and HSM should show status OPEN.

Step 6: Migrate Keys to DuoKey KMS​

-- Migrate master key from local wallet to DuoKey KMS
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY 
  IDENTIFIED BY "<keystore_pin>" 
  MIGRATE USING "<keystore_pin>" 
  WITH BACKUP USING 'LocalWalletMigration';

For Oracle 11g R2:

-- Migrate key
ALTER SYSTEM SET ENCRYPTION KEY 
  IDENTIFIED BY "<keystore_pin>" 
  MIGRATE USING "<keystore_pin>";

Step 7: Verify Migration​

-- Check that keys are in DuoKey KMS
SELECT key_id, creation_time, activation_time 
FROM v$encryption_keys 
ORDER BY creation_time DESC;

Check DuoKey Cockpit audit logs for key migration events.

Step 8: Configure Auto-Login (Optional)​

Follow the auto-login configuration steps from the Getting Started guide.

Reverse Migration: DuoKey KMS to Local Wallet​

If you need to reverse migrate from DuoKey KMS back to a local wallet:

Oracle 11g R2 Limitation

Oracle 11g R2 does not support reverse migration. Reverse migration is only available when upgrading from 11g R2 to 12c or higher.

Prerequisites​

  • Oracle Database 12c or higher
  • TDE configured with DuoKey KMS
  • Access to both HSM and local wallets

Reverse Migration Steps​

Step 1: Move Auto-Login Wallet​

# Backup auto-login wallet
cd $ORACLE_BASE/admin/$ORACLE_SID/wallet/tde
mv cwallet.sso cwallet.sso_backup

Step 2: Open Both Wallets​

-- Open both HSM and local wallets manually
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
  IDENTIFIED BY "<keystore_pin>" 
  CONTAINER=ALL;

-- Verify both are open
SELECT * FROM V$ENCRYPTION_WALLET;

Step 3: Change to FILE Method​

For Oracle 18c and earlier:

-- Change to FILE method only
ALTER SYSTEM SET ENCRYPTION_WALLET_LOCATION=
  '(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=<wallet_location>)))' 
  SCOPE=SPFILE;

-- Restart database
SHUTDOWN IMMEDIATE;
STARTUP;

For Oracle 19c and later:

-- Change to FILE method
ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=FILE' 
  SCOPE=BOTH;

Step 4: Reverse Migrate Keys​

-- Reverse migrate from HSM to local wallet
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY 
  IDENTIFIED BY "<keystore_pin>" 
  REVERSE MIGRATE USING "<keystore_pin>" 
  WITH BACKUP USING 'ReverseMigration';

Step 5: Verify Reverse Migration​

-- Verify wallet status
SELECT * FROM V$ENCRYPTION_WALLET;

-- Should show FILE wallet only

Oracle Data Guard Integration​

For Oracle Data Guard environments, follow these steps to integrate standby databases with DuoKey KMS.

Prerequisites​

  • Primary database integrated with DuoKey KMS
  • Standby database configured in Data Guard
  • PKCS#11 library installed on standby server

Integration Steps​

Step 1: Copy Wallet Files​

Copy wallet files from primary to standby:

# On primary server
cd $ORACLE_BASE/admin/$ORACLE_SID/wallet/tde

# Copy to standby server
scp cwallet.sso standby_server:$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde/
scp ewallet.p12 standby_server:$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde/

Step 2: Install PKCS#11 on Standby​

On the standby server:

# Copy PKCS#11 library
sudo mkdir -p /opt/oracle/extapi/64/hsm/DuoKey/1.0
sudo cp /path/to/libdke_pkcs11.so \
  /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so

# Set permissions
sudo chown -R oracle:oinstall /opt/oracle
sudo chmod -R 775 /opt/oracle

Step 3: Copy PKCS#11 Configuration​

# Copy pkcs11.toml from primary to standby
scp /etc/duokey/pkcs11.toml \
  standby_server:/etc/duokey/pkcs11.toml

# On standby, set permissions
sudo chown oracle:oinstall /etc/duokey/pkcs11.toml
sudo chmod 600 /etc/duokey/pkcs11.toml

Step 4: Configure Standby Database​

On the standby database:

-- Point to both HSM and FILE
ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM|FILE'
  SCOPE=BOTH;

Step 5: Verify Auto-Login​

The auto-login wallet should automatically open the wallet on standby.

-- Check wallet status on standby
SELECT * FROM V$ENCRYPTION_WALLET;

Expected output:

  • WRL_TYPE: HSM
  • STATUS: OPEN (with auto-login)
  • WALLET_TYPE: AUTO_LOGIN

Backup and Recovery​

TDE Backup Considerations​

When backing up TDE-encrypted databases:

Tablespace Encryption:

  • Backups are encrypted by default
  • RMAN backups maintain encryption

Column Encryption:

  • Backups are not encrypted by default
  • Data in export dumps (expdp) is unencrypted

Encrypted RMAN Backups​

# RMAN backups of encrypted tablespaces are encrypted automatically
rman target /

RMAN> BACKUP DATABASE;

Encrypted Export (Data Pump)​

For column encryption, explicitly enable encryption in exports:

# Encrypted export
expdp hr DIRECTORY=dpump_dir1 \
  DUMPFILE=hr_enc.dmp \
  ENCRYPTION=all \
  ENCRYPTION_ALGORITHM=AES256 \
  ENCRYPTION_MODE=TRANSPARENT

Restoring TDE Databases​

To restore TDE databases on a target system:

Prerequisites​

  • DuoKey KMS configured on target system
  • Same wallet files or access to same DuoKey application
  • PKCS#11 library installed

Restoration Steps​

  1. Copy Wallet Files (if not using same DuoKey app):
# Copy from source to target
scp cwallet.sso target_server:$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde/
scp ewallet.p12 target_server:$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde/
  1. Install PKCS#11 Configuration:
# Copy pkcs11.toml
scp /etc/duokey/pkcs11.toml target_server:/etc/duokey/
  1. Configure Target Database:
-- Set TDE configuration
ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM|FILE' 
  SCOPE=BOTH;
  1. Restore Database:
# RMAN restore
rman target /

RMAN> RESTORE DATABASE;
RMAN> RECOVER DATABASE;
RMAN> ALTER DATABASE OPEN;
  1. Verify Wallet Status:
-- Check wallet is open
SELECT * FROM V$ENCRYPTION_WALLET;

Pluggable Database Cloning​

You can clone pluggable databases (PDBs) with TDE encryption keys stored in DuoKey KMS.

Prerequisites​

  • Source and target databases integrated with DuoKey KMS
  • Both databases use applications in the same DuoKey group
  • Master keys accessible by both databases

Hot Clone from Source PDB​

On Source Database​

  1. Create Hot Clone:
-- Connect as SYSDBA
sqlplus / as sysdba

-- Create hot clone of encrypted PDB
CREATE PLUGGABLE DATABASE PDB2_CLONE 
  FROM PDB2 
  FILE_NAME_CONVERT = (
    '/u01/app/oracle/oradata/ORCLDB/pdb2',
    '/u01/app/oracle/oradata/ORCLDB/pdb2_clone'
  )
  KEYSTORE IDENTIFIED BY "<keystore_pin>";
  1. Verify Wallet Status:
-- Check wallet status for all PDBs
SELECT con_id, wrl_type, status, wallet_type 
FROM v$encryption_wallet;
  1. Verify Encrypted Data:
-- Switch to source PDB
ALTER SESSION SET CONTAINER=PDB2;

-- Check encrypted columns
SELECT * FROM dba_encrypted_columns;

-- Verify data is accessible
SELECT * FROM schema.encrypted_table;
  1. Unplug Cloned PDB:
-- Connect as SYSDBA
conn / as sysdba

-- Unplug the cloned PDB
ALTER PLUGGABLE DATABASE PDB2_CLONE UNPLUG INTO 
  '/u01/app/oracle/pdb2_clone.pdb';

On Target Database​

  1. Copy PDB File:
# Copy .pdb file to target server
scp /u01/app/oracle/pdb2_clone.pdb \
  target_server:/u01/app/oracle/oradata/ORCLDB/
Prerequisites

The target database must:

  • Be encrypted and integrated with DuoKey KMS
  • Have access to the same DuoKey group with the source PDB's keys
  • Have a master key set in the root container (CDB)
  1. Plug In PDB:
-- Connect to target database as SYSDBA
sqlplus / as sysdba

-- Create PDB from .pdb file
CREATE PLUGGABLE DATABASE PDB2 USING 
  '/u01/app/oracle/oradata/ORCLDB/pdb2_clone.pdb' 
  COPY FILE_NAME_CONVERT=(
    '/u01/app/oracle/oradata/ORCLDB/pdb2_clone',
    '/u01/app/oracle/oradata/ORCLDB/pdb2'
  )
  KEYSTORE IDENTIFIED BY "<keystore_pin>";
  1. Open PDB and Wallet:
-- Switch to new PDB
ALTER SESSION SET CONTAINER=PDB2;

-- Check wallet status
SELECT * FROM V$ENCRYPTION_WALLET;

-- Open wallet if needed (external keystore; the PIN is advisory but must
-- be a literal quoted string — the access_token bearer credential in
-- pkcs11.toml authenticates the request)
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
  IDENTIFIED BY "<keystore_pin>";
  1. Verify Data Access:
-- Verify encrypted columns
SELECT * FROM dba_encrypted_columns;

-- Test data access
SELECT * FROM schema.encrypted_table;

Upgrading PKCS#11 Library​

Regular updates to the PKCS#11 library provide new features and security enhancements.

Downtime Required

Upgrading the PKCS#11 library requires database downtime.

Upgrade Steps​

Step 1: Obtain New Library​

Obtain the latest DuoKey PKCS#11 library (libdke_pkcs11.so) from DuoKey support and copy it to the database host.

Step 2: Backup Current Library​

# Backup current library
cd /opt/oracle/extapi/64/hsm/DuoKey/1.0
cp libdke_pkcs11.so libdke_pkcs11.so.backup

Step 3: Shutdown Database​

-- Shutdown database
sqlplus / as sysdba

SHUTDOWN IMMEDIATE;

Step 4: Replace Library​

# Copy the new library into place (overwriting the backed-up copy)
sudo cp libdke_pkcs11.so \
  /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so

# Set permissions
sudo chown -R oracle:oinstall \
  /opt/oracle/extapi/64/hsm/DuoKey/1.0
sudo chmod -R 775 \
  /opt/oracle/extapi/64/hsm/DuoKey/1.0

Step 5: Start Database​

-- Start database
sqlplus / as sysdba

STARTUP;

Step 6: Verify Operations​

# Check PKCS#11 logs
tail -f /var/log/dke-pkcs11/*.log

Look for:

  • Successful connection to DuoKey KMS
  • Key access operations

Rollback Procedure​

If issues occur after upgrade:

# Shutdown database
sqlplus / as sysdba
SHUTDOWN IMMEDIATE;
exit

# Restore previous version
cd /opt/oracle/extapi/64/hsm/DuoKey/1.0
mv libdke_pkcs11.so.backup libdke_pkcs11.so

# Restart database
sqlplus / as sysdba
STARTUP;
Support

For upgrade assistance or issues, contact DuoKey support at [email protected].

Best Practices Summary​

Key Rotation​

  • Rotate keys every 6-12 months
  • Document rotation schedule
  • Test rotation in non-production first
  • Restart database after rotation

Backup Strategy​

  • Regular RMAN backups of encrypted databases
  • Backup wallet files separately
  • Test restore procedures
  • Document recovery procedures

High Availability​

  • Use auto-login wallets
  • Distribute wallet files in RAC/Data Guard
  • Monitor DuoKey KMS availability
  • Configure retry timeouts appropriately

Security​

  • Separate duties: DBAs and security admins
  • Restrict access to pkcs11.toml
  • Monitor audit logs in DuoKey Cockpit
  • Use unique apps per database

Operations​

  • Document all configurations
  • Test upgrades in non-production
  • Monitor PKCS#11 logs
  • Maintain current PKCS#11 version

Support​

For assistance with key management operations: