Friday, August 29, 2025

Oracle Master Encryption Key Management: Wallets, OKV, and OCI KMS Explained

Data Encryption Keys (DEK) are used by encryption algorithms (typically AES256) to protect data at rest in tablespaces, backups and even datapump exports. Since DEKs are stored with the data, they need to be protected.  Master Encryption Keys (MEK) are stored outside the database in local wallets or in an external keystore, and MEKs are used to encrypt the DEK which provides a separation between the data that is encrypted and an external key.

DEKs are not only found on Tablespaces (TDE), but they are also found in RMAN encrypted backups, Space Efficient Encrypted backups to ZDLRA/Recovery Service and encrypted datapump exports.

The diagram below shows that relationship between MEKs and DEKs.




You can see in the diagram that MEKs are not only used to encrypt Tablespace Encryption Keys to support TDE, they are also used to encrypt RMAN backups to disk, Tape or ZDLRA/Recovery Service, along with Datapump encryption keys.  

NOTE: When implementing encryption you should make sure you meet ASO licensing restrictions
  • Creating encrypted tablespaces or encrypted columns in tables requires ASO, unless you are leveraging an OCI Cloud Database environment (including multicloud).
  • Creating RMAN encrypted disk backups requires licensing.
  • Creating RMAN encrypted tape backups is license included and only supported when writing to Oracle products.
    • OSB - Oracle Secure Backup is license included for creating encrypted backups.
    • OCI Object Storage - The OCI cloud library requires encryption and can only be leveraged for writing backups directly to OCI object storage in OCI, or writing backups from a ZDLRA to OCI object storage in cloud or on ZFSSA
    • ZDLRA - Creating Space Efficient Encrypted backups is license included on ZDLRA and will create encrypted backups on ZDLRA.
  • Creating Datapump Encrypted backups requires licensing. 


MEKs are commonly called "TDE keys", but they are much more, and I will refer to them as MEKs throughout this post.

MEK with a Wallet File

In this first section I am going to talk about how the Oracle Database manages an MEK when using a Wallet file.

Wallet settings

With wallet-based MEKs, the database stores and reads keys from a wallet file on disk (or +ASM or Exascale).

There are 2 parameters in the database (spfile) that help guide the database to the wallet file.

WALLET_ROOT - This replace the "ENCRYPTION_WALLET_LOCATION" parameter that was previous set in the sqlnet.ora file.  Having it set at the database level allows multiple databases to independently share the same $ORACLE_HOME. It even allows PDBs to have individual wallet files. When using a wallet file, the WALLET_ROOT points to top directory where the encryption keys will be kept.

TDE_CONFIGURATION - This tells the database what kind of MEK will be used. For wallets you would specify "TDE_CONFIGURATION=FILE".  This tells the database to use find the encryption keys in an encryption wallet.

Encryption key location

Within the WALLET_ROOT directory the encryption wallet containing the MEKs, the wallet must be stored in a subdirectory named "tde".

Within that directory you will find 2 wallet files

  • ewallet.p12 - The password-protected wallet (contains keys; required for updates).
  • ewallet.sso — the auto-login wallet (allowing no password prompt on open); The auto-login wallet can also be created as a “local” autologin wallet bound to a single host.

On startup (or when you open the keystore), the database retrieves the CDB/PDB MEKs from the wallet file and caches them in memory.

Database interaction with MEK

When using a wallet file, the auto-login wallet file is opened when the database is opened, and the database constantly interacts with this file.  If no auto-login wallet file is created, you must open the wallet manually providing the password.

Viewing V$ENCRYPTION_WALLET 

What you’ll typically see for FILE based wallets:

PDB_NAME        WALLET_TYPE  STATUS  WRL_PARAMETER                KEYSTORE
--------------  -----------  ------  ----------------------------  --------
CDB$ROOT        AUTOLOGIN    OPEN    {WALLET_ROOT}/tde             NONE
DB23AI_PDB      AUTOLOGIN    OPEN                                  UNITED

MEK with OKV/OCI KMS

When using an external keystore, the database communicates with the OKV/OCI KMS client libraries installed on the host in order to retrieve the MEKs.

OKV/OCI KMS settings

There are 2 parameters in the database (spfile) that help guide the database to the OKV/OCI KMS installation.

WALLET_ROOT -  When using OKV/OCI KMS, the WALLET_ROOT points to top directory of the client install of the OKV/OCI KMS software.

TDE_CONFIGURATION - For OKV/OCI KMS  specify "TDE_CONFIGURATION=OKV" or "TDE_CONFIGURATION=HSM".  It is possible to combine both wallets and  OKV/OCI KMS if there are older keys that are still stored a wallet file. In that case you would see "TDE_CONFIGURATION=OKV|FILE" for example, and the database would read older encryption keys from a wallet file along with reading the keys from OKV/OCI MKS.

Encryption key location

Within the WALLET_ROOT directory, the software to communicate with the HSM is typically installed in the "okv" or "hsm" subdirectory.  The keys themselves are stored externally, and could be securely cached locally depending on your configuration.

The credential used to access OKV/OCI KMS is typically stored under the /tde directory in an auto-login wallet. This allows the database to connect to OKV/OCI KMS at startup. The external password store entries (if used) live under /tde_seps which allows up to manage keys without entering a password.

Database interaction with MEK

The MEK is always permanently stored externally.  The database interacts with the external keystore through a library.  This library is named liborapkcs.so.  The library itself is vendor specific and is used by the database to interact with different vendors keystore,. Because there is a single library, you cannot use multiple external key store types on the same DB host.
When the database starts up, it reads the password for the external keystore out of the wallet, opens up a connection to the keystore (after authentication and encryption handshake) and caches the MEK.  The database periodically will communicate with the external keystore through that library.


OKV/OCI MKS in Practice: What You’ll See

When both FILE and OKV configurations exist (e.g., during migration), you may observe dual rows in V$ENCRYPTION_WALLET showing the FILE wallet (no active master key) and the active OKV keystore:

PDB_NAME        TYPE  STATUS             WALLET_TYPE  WRL_PARAMETER
--------------  ----  -----------------  -----------  ---------------------------
CDB$ROOT        FILE  OPEN_NO_MASTERKEY  AUTOLOGIN    {WALLET_ROOT}/tde
CDB$ROOT        OKV   OPEN               OKV
DB23AI_PDB      FILE  OPEN_NO_MASTERKEY  AUTOLOGIN
DB23AI_PDB      OKV   OPEN               OKV


Best Practices & Notes

  • Back up only the passworded wallet when using a wallet file. (ewallet.p12) and store it securely, separate from database backups.
  • Use local autologin wallets if you require host binding for additional security.
  • When migrating to OKV/OCI KMS, consider a staged approach (OKV|FILE) so you can fall back if needed.
  • Always test wallet/keystore open/close operations and RMAN/Data Pump encryption workflows in lower environments before production.
  • Keep client libraries (liborapkcs.so and OKV client) patched and consistent across RAC nodes.

Last updated: August 29, 2025

Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)