3 Configuring United Mode
United mode enables you to create a common keystore for the CDB and the PDBs for which the keystore is in united mode.
The keys for the CDB and the PDBs reside in the common keystore.
- About Configuring United Mode
In united mode (the default), the keystore is shared between the CDB root and all PDBs that are configured in united mode. Each united mode PDB has its own set of encryption keys in the shared keystore. - Operations That Are Allowed in United Mode
ManyADMINISTER KEY MANAGEMENT
operations performed in the CDB root apply to keystores and encryption keys in the united mode PDB. - Configuring the Keystore Location and Type for United Mode
For united mode, you can configure the keystore location and type by setting parameters and running theALTER SYSTEM
statement. - Configuring a TDE Wallet and TDE Master Encryption Key for United Mode
In united mode, the TDE wallet resides in the CDB root but the master keys from this wallet are available for the PDBs that have their TDE wallets in united mode. - Operations That Are Not Allowed in a United Mode PDB
ADMINISTER KEY MANAGEMENT
operations that are not allowed in a united mode PDB can be performed in the CDB root. - Configuring a Container Database with United Mode PDBs for Oracle Key Vault
The TDE master keys of all united mode PDBs and the CDB reside in the same virtual wallet in Oracle Key Vault.
3.1 About Configuring United Mode
In united mode (the default), the keystore is shared between the CDB root and all PDBs that are configured in united mode. Each united mode PDB has its own set of encryption keys in the shared keystore.
The keys for PDBs having keystore in united mode, can be created from CDB root or from the PDB.
This design enables you to have one keystore to manage the entire CDB environment, enabling the PDBs to share this keystore, but you can customize the behavior of this keystore in the individual united mode PDBs. For example, in a united mode PDB, you can configure a TDE master encryption key for the PDB in the united keystore that you created in the CDB root, open the keystore locally, and close the keystore locally. In order to perform these actions, the keystore in the CDB root must be open.
Before you configure your environment to use united mode or isolated mode, all the PDBs in the CDB environment are considered to be in united mode.
To use united mode, you must follow these general steps:
-
In the CDB root, configure the database to use united mode by setting the
WALLET_ROOT
andTDE_CONFIGURATION
parameters.The
WALLET_ROOT
parameter sets the location for the wallet directory and theTDE_CONFIGURATION
parameter sets the type of keystore to use. -
Restart the database after setting the static initialization parameter
WALLET_ROOT
, then set the dynamic initialization parameterTDE_CONFIGURATION
. -
In the CDB root, create the keystore, open the keystore, and then create the TDE master encryption key.
-
In each united mode PDB, perform TDE master encryption key tasks as needed, such as opening the keystore locally in the united mode PDB and creating the TDE master encryption key for the PDB. Remember that the keystore is managed by the CDB root, but must contain a TDE master encryption key that is specific to the PDB for the PDB to be able to use TDE.
When you run ADMINISTER KEY MANAGEMENT
statements in united mode from the CDB root, if the statement accepts the CONTAINER
clause, and if you set it to ALL
, then the statement applies only to the CDB root and its associated united mode PDBs. Any PDB that is in isolated mode is not affected.
Parent topic: Configuring United Mode
3.2 Operations That Are Allowed in United Mode
Many ADMINISTER KEY MANAGEMENT
operations performed in the CDB root apply to keystores and encryption keys in the united mode PDB.
Available United Mode-Related Operations in a CDB Root
Table 3-1 describes the ADMINISTER KEY MANAGEMENT
operations that you can perform in the CDB root.
Table 3-1 ADMINISTER KEY MANAGEMENT United Mode Operations in a CDB Root
Operation | Syntax | Notes |
---|---|---|
Creating a keystore |
ADMINISTER KEY MANAGEMENT
CREATE KEYSTORE
IDENTIFIED BY keystore_password; |
After you create the keystore in the CDB root, by default it is available in the united mode PDBs. Do not include the |
Opening a keystore |
ADMINISTER KEY MANAGEMENT
SET KEYSTORE OPEN
IDENTIFIED BY
[EXTERNAL STORE | keystore_password]
[CONTAINER = ALL | CURRENT]; |
In this operation, the |
Changing a keystore password |
ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD IDENTIFIED BY old_keystore_password SET new_keystore_password WITH BACKUP [USING 'backup_identifier']; |
Do not include the |
Backing up a keystore |
ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE [USING 'backup_identifier'] [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [TO 'keystore_location']; |
Do not include the |
Closing a keystore without force |
ADMINISTER KEY MANAGEMENT
SET KEYSTORE CLOSE
[IDENTIFIED BY [EXTERNAL STORE | keystore_password]]
[CONTAINER = ALL | CURRENT]; |
- |
Closing a keystore with force |
ADMINISTER KEY MANAGEMENT
FORCE KEYSTORE CLOSE
[IDENTIFIED BY [EXTERNAL STORE | keystore_password]]
[CONTAINER = ALL | CURRENT]; |
- |
Creating and activating a new TDE master encryption key (rekeying) |
ADMINISTER KEY MANAGEMENT SET [ENCRYPTION] KEY [FORCE KEYSTORE] [USING TAG 'tag_name'] IDENTIFIED BY [EXTERNAL STORE | keystore_password] WITH BACKUP [USING 'backup_identifier'] [CONTAINER = ALL | CURRENT] |
- |
Creating a user-defined TDE master encryption key for either now ( |
ADMINISTER KEY MANAGEMENT [SET | CREATE] [ENCRYPTION] KEY 'mkid:mk | mk' [USING ALGORITHM 'algorithm'] [FORCE KEYSTORE] [USING TAG 'tag_name'] IDENTIFIED BY [EXTERNAL STORE | keystore_password] [WITH BACKUP [USING 'backup_identifier']] [CONTAINER = CURRENT]; |
- |
Activating an existing TDE master encryption key |
ADMINISTER KEY MANAGEMENT USE [ENCRYPTION] KEY 'key_id' IDENTIFIED BY [EXTERNAL STORE | keystore_password] WITH BACKUP [USING 'backup_identifier']; |
Do not include the |
Tagging a TDE master encryption key |
ADMINISTER KEY MANAGEMENT SET TAG 'tag' FOR 'key_id' IDENTIFIED BY [EXTERNAL STORE | keystore_password ] WITH BACKUP [USING 'backup_identifier']; |
Do not include the |
Moving a TDE master encryption key to a new keystore |
ADMINISTER KEY MANAGEMENT MOVE [ENCRYPTION] KEYS TO NEW KEYSTORE 'keystore_location1' IDENTIFIED BY keystore1_password FROM [FORCE] KEYSTORE IDENTIFIED BY keystore_password [WITH IDENTIFIER IN { 'key_id' [, 'key_id' ]... | ( subquery ) } ] WITH BACKUP [USING 'backup_identifier']; |
You can only move the master encryption key to a keystore that is within the same container (for example, between keystores in the CDB root or between keystores in the same PDB). You cannot move the master encryption key from a keystore in the CDB root to a keystore in a PDB, and vice versa. Do not include the |
Available Operations in a United Mode PDB
Table 3-2 describes the ADMINISTER KEY MANAGEMENT
operations that you can perform in a united mode PDB.
Table 3-2 ADMINISTER KEY MANAGEMENT United Mode PDB Operations
Operation | Syntax | Notes |
---|---|---|
Opening a keystore |
ADMINISTER KEY MANAGEMENT
SET KEYSTORE CLOSE
[IDENTIFIED BY EXTERNAL STORE | keystore_password]
[CONTAINER = CURRENT]; |
In this operation, the |
Closing a keystore without force |
ADMINISTER KEY MANAGEMENT
SET KEYSTORE CLOSE
[EXTERNAL STORE | keystore_password]
[CONTAINER = CURRENT]; |
- |
Closing a keystore with force |
ADMINISTER KEY MANAGEMENT
FORCE KEYSTORE CLOSE
IDENTIFIED BY
[EXTERNAL STORE | keystore_password]
[CONTAINER = CURRENT]; |
- |
Creating and activating a new TDE master encryption key (rekeying or rotating) |
ADMINISTER KEY MANAGEMENT SET [ENCRYPTION] KEY [FORCE KEYSTORE] [USING TAG 'tag_name'] IDENTIFIED BY EXTERNAL STORE | keystore_password WITH BACKUP [USING 'backup_identifier'] [CONTAINER = CURRENT]; |
- |
Creating a user-defined TDE master encryption key for use either now ( |
ADMINISTER KEY MANAGEMENT SET | CREATE [ENCRYPTION] KEY 'mkid:mk | mk' [USING ALGORITHM 'algorithm'] [FORCE KEYSTORE] [USING TAG 'tag'] IDENTIFIED BY EXTERNAL STORE | keystore_password WITH BACKUP [USING 'backup_identifier'] [CONTAINER = CURRENT]; |
- |
Activating an existing TDE master encryption key |
ADMINISTER KEY MANAGEMENT USE [ENCRYPTION] KEY 'key_id' IDENTIFIED BY EXTERNAL STORE | keystore_password WITH BACKUP [USING 'backup_identifier']; |
Do not include the |
Tagging a TDE master encryption key |
ADMINISTER KEY MANAGEMENT SET TAG 'tag' FOR 'key_id' [FORCE KEYSTORE] IDENTIFIED BY EXTERNAL STORE | keystore_password WITH BACKUP [USING 'backup_identifier']; |
Do not include the |
Moving an encryption key to a new keystore |
ADMINISTER KEY MANAGEMENT MOVE [ENCRYPTION] KEYS TO NEW KEYSTORE 'new_keystore_location' IDENTIFIED BY new_keystore_password FROM [FORCE] KEYSTORE IDENTIFIED BY keystore_password [WITH IDENTIFIER IN { 'key_id' [, 'key_id' ]... | ( subquery ) } ] WITH BACKUP [USING 'backup_identifier']; |
Do not include the |
Moving a key from a united mode keystore in the CDB root to an isolated mode keystore in a PDB |
ADMINISTER KEY MANAGEMENT ISOLATE KEYSTORE IDENTIFIED BY isolated_keystore_password FROM ROOT KEYSTORE [FORCE KEYSTORE] IDENTIFIED BY EXTERNAL STORE | united_keystore_password WITH BACKUP [USING backup_id]; |
Do not include the |
Using the |
ADMINISTER KEY MANAGEMENT FORCE ISOLATE KEYSTORE IDENTIFIED BY isolated_keystore_password FROM ROOT KEYSTORE [FORCE KEYSTORE] IDENTIFIED BY [EXTERNAL STORE | united_keystore_password] [WITH BACKUP [USING backup_id]]; |
- |
Parent topic: Configuring United Mode
3.3 Configuring the Keystore Location and Type for United Mode
For united mode, you can configure the keystore location and type by setting parameters and running the ALTER SYSTEM
statement.
- About Configuring the Keystore Location and Type for United Mode
A keystore is a container that stores the TDE master encryption key. - Configuring United Mode with the Initialization Parameter File and ALTER SYSTEM
If your environment relies on server parameter files (spfile
), then you can setWALLET_ROOT
andTDE_CONFIGURATION
usingALTER SYSTEM SET
withSCOPE
. - Example: Configuring a TDE Wallet When Multiple Databases Share the Same Host
You can configure multiple databases to share the same host by setting theWALLET_ROOT
parameter. - Example: Configuring a TDE Wallet for an Oracle Automatic Storage Management Disk Group
In an Oracle Real Applications Clusters (Oracle RAC) environment, theWALLET_ROOT
parameter points to a shared directory in Oracle Automatic Storage Management (ASM) that is accessible from all Oracle RAC instances of that database.
Parent topic: Configuring United Mode
3.3.1 About Configuring the Keystore Location and Type for United Mode
A keystore is a container that stores the TDE master encryption key.
Before you can configure the keystore, you first must define a location for it by setting the static initialization parameter WALLET_ROOT
. Then, after a database restart, you must set the dynamic initialization parameter TDE_CONFIGURATION
to instruct the database to retrieve the master encryption key from a TDE wallet, Oracle Key Vault, or Oracle Cloud Interface (OCI) Key Management Service (KMS), according to their documentation. If this setting has not been created, then Oracle Database checks the sqlnet.ora
file. You can create other TDE wallets, such as copies of the wallet and export files that contain keys, depending on your needs. If you must remove or delete the wallet that you configured in the WALLET_ROOT
location, then you must do so only after you copied all wallets (including backups and auto-login wallets) in the old to the new location. Then you must reset WALLET_ROOT
to point to the new location of the TDE wallet.
After you configure the keystore location by using the WALLET_ROOT
and TDE_CONFIGURATION
parameters, you can log in to the CDB to create and open the TDE wallet, and then set the TDE master encryption key. After you complete these steps, you can begin to encrypt data.
3.3.2 Configuring United Mode with the Initialization Parameter File and ALTER SYSTEM
If your environment relies on server parameter files (spfile
), then you can set WALLET_ROOT
and TDE_CONFIGURATION
using ALTER SYSTEM SET
with SCOPE
.
3.3.3 Example: Configuring a TDE Wallet When Multiple Databases Share the Same Host
You can configure multiple databases to share the same host by setting the WALLET_ROOT
parameter.
Because the WALLET_ROOT
parameter is internal to an Oracle database, you only need to set the parameter to enable multiple databases to share the same host.
For example:
ALTER SYSTEM SET WALLET_ROOT = '/etc/ORACLE/KEYSTORES/${ORACLE_SID}' SCOPE = SPFILE;
To implement clean separation of individual TDE wallets for each database, add the ORACLE_SID
(or ORACLE_UNQNAME
in Oracle Real Application Clusters) into the WALLET_ROOT
parameter setting.
3.3.4 Example: Configuring a TDE Wallet for an Oracle Automatic Storage Management Disk Group
In an Oracle Real Applications Clusters (Oracle RAC) environment, the WALLET_ROOT
parameter points to a shared directory in Oracle Automatic Storage Management (ASM) that is accessible from all Oracle RAC instances of that database.
The following example shows you how to set WALLET_ROOT
and TDE_CONFIGURATION
for a TDE wallet in ASM:
ALTER SYSTEM SET WALLET_ROOT = '+DATA/unique_name_of_database' SCOPE = SPFILE SID = '*';
For example, if you set this value to +DATA/FINRAC
, then the /tde
directory is automatically generated when you create a TDE wallet.
Related Topics
3.4 Configuring a TDE Wallet and TDE Master Encryption Key for United Mode
In united mode, the TDE wallet resides in the CDB root but the master keys from this wallet are available for the PDBs that have their TDE wallets in united mode.
- About Configuring a TDE Wallet and TDE Master Encryption Key for United Mode
In united mode, the TDE wallet that you create in the CDB root will be accessible by the united mode PDBs. - Step 1: Create the TDE Wallet
After you have specified a directory location for the TDE wallet, you can create this wallet. - Step 2: Open the TDE Wallet
Depending on the type of TDE wallet you create, you must manually open the wallet before you can use it. - Step 3: Set the TDE Master Encryption Key in the TDE Wallet
Once the TDE wallet is open, you can set a TDE master encryption key for it. - Step 4: Encrypt Your Data in United Mode
Now that you have completed the configuration, you can begin to encrypt data.
Parent topic: Configuring United Mode
3.4.1 About Configuring a TDE Wallet and TDE Master Encryption Key for United Mode
In united mode, the TDE wallet that you create in the CDB root will be accessible by the united mode PDBs.
In general, to configure a united mode TDE wallet after you have enabled united mode, you create and open the TDE wallet in the CDB root, and then create a master encryption key for this TDE wallet. Afterward, you can begin to encrypt data for tables and tablespaces that will be accessible throughout the CDB environment.
The V$ENCRYPTION_WALLET
dynamic view describes the status and location of the TDE wallet. For example, the following query shows the open-closed status and the TDE wallet location of the CDB root TDE wallet (CON_ID 1
) and its associated united mode PDBs. The WRL_PARAMETER
column shows the CDB root TDE wallet location being in the WALLET_ROOT/tde
directory.
SELECT CON_ID, STATUS, WRL_PARAMETER FROM V$ENCRYPTION_WALLET; CON_ID STATUS WRL_PARAMETER ------ ------ ----------------------------- 1 OPEN /app/oracle/wallet/tde/ 2 CLOSED 3 OPEN 4 OPEN 5 OPEN
In this output, there is no keystore path listed for the other PDBs in this CDB because these PDBs use the keystore in the CDB root. If any of these PDBs are isolated and you create a keystore in the isolated mode PDB, then when you perform this query, the WRL_PARAMETER
column will show the keystore path for the isolated mode PDB.
You can hide the TDE wallet password in a secure external password store:
ADMINISTER KEY MANAGEMENT ADD SECRET 'TDE_wallet_password'
FOR CLIENT 'TDE_WALLET' INTO [LOCAL]
AUTO_LOGIN KEYSTORE 'WALLET_ROOT/tde_seps';
This feature enables you to hide the password from the operating system: it removes the need for storing clear-text keystore passwords in scripts or other tools that can access the database without user intervention, such as overnight batch scripts. The location for this wallet is wallet_root/tde_seps
. In a multitenant environment, different PDBs can access this external store location when you run the ADMINISTER KEY MANAGEMENT
statement using the IDENTIFIED BY EXTERNAL STORE
clause. This way, you can centrally locate the password and then update it only once in the external store.
3.4.2 Step 1: Create the TDE Wallet
After you have specified a directory location for the TDE wallet, you can create this wallet.
- About Creating TDE Wallets
There are three different types of TDE wallets. - Creating a Password-Protected TDE Wallet
A password-protected TDE wallet requires a password, which is used to protect the TDE master keys. In united mode, you must create the TDE wallet in the CDB root. - Creating an Auto-Login or a Local Auto-Login TDE Wallet
As an alternative to password-protected TDE wallets, you can create either an auto-login or local auto-login TDE wallet.
3.4.2.1 About Creating TDE Wallets
There are three different types of TDE wallets.
You can create password-protected TDE wallets, auto-login TDE wallets, and local auto-login TDE wallets.
Be aware that running the query SELECT * FROM V$ENCRYPTION_WALLET
will automatically open an auto-login TDE wallet. For example, suppose you have a password-protected TDE wallet and an auto-login TDE wallet. If the password-protected TDE wallet is open and you close the password-protected TDE wallet and then query the V$ENCRYPTION_WALLET
view, then the output will indicate that a TDE wallet is open. However, this is because V$ENCRYPTION_WALLET
opened up the auto-login TDE wallet and then displayed the status of the auto-login wallet.
Related Topics
Parent topic: Step 1: Create the TDE Wallet
3.4.2.2 Creating a Password-Protected TDE Wallet
A password-protected TDE wallet requires a password, which is used to protect the TDE master keys. In united mode, you must create the TDE wallet in the CDB root.
ADMINISTER KEY MANAGEMENT statement
.
ewallet.p12
file, which contains the TDE wallet, appears in the designated TDE wallet location. For example, if you had set the WALLET_ROOT
parameter to /etc/ORACLE/KEYSTORES/${ORACLE_SID}
and the TDE_CONFIGURATION
parameter to FILE
(for TDE, which creates a tde
directory in the wallet root location), then the TDE wallet will be created in the /etc/ORACLE/KEYSTORES/${ORACLE_SID}/tde
directory. The name of the TDE wallet is ewallet.p12
.
Related Topics
Parent topic: Step 1: Create the TDE Wallet
3.4.2.3 Creating an Auto-Login or a Local Auto-Login TDE Wallet
As an alternative to password-protected TDE wallets, you can create either an auto-login or local auto-login TDE wallet.
Follow these guidelines:
- Do not remove the
PKCS#12
wallet (ewallet.p12
file) after you create the auto-login TDE wallet (.sso
file). You must have thePKCS#12
wallet to regenerate or rekey the TDE master encryption key in the future. - Remember that Transparent Data Encryption uses an auto login TDE wallet only if it is available at the correct location (
WALLET_ROOT/tde
), and the SQL statement to open an encrypted TDE wallet has not already been run. If you have theENCRYPTION_WALLET_LOCATION
parameter set, then be aware this parameter is deprecated. Oracle recommends that you use theWALLET_ROOT
static initialization parameter andTDE_CONFIGURATION
dynamic initialization parameter instead.
Parent topic: Step 1: Create the TDE Wallet
3.4.3 Step 2: Open the TDE Wallet
Depending on the type of TDE wallet you create, you must manually open the wallet before you can use it.
- About Opening TDE Wallets
A password-protected TDE wallet must be open before any TDE master encryption keys can be created or accessed in the wallet. - Opening the TDE Wallet in a United Mode PDB
To open a TDE wallet in united mode, you must use theADMINISTER KEY MANAGEMENT
statement with theSET KEYSTORE OPEN
clause.
3.4.3.1 About Opening TDE Wallets
A password-protected TDE wallet must be open before any TDE master encryption keys can be created or accessed in the wallet.
Many Transparent Data Encryption operations require the TDE wallet to be open. There are two ways that you can open the TDE wallet:
-
Manually open the wallet by issuing the
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN
statement. Afterward, you can perform the operation. -
Include the
FORCE KEYSTORE
clause in theADMINISTER KEY MANAGEMENT
statement that is used to perform the operation.FORCE KEYSTORE
temporarily opens the TDE wallet for the duration of the operation, and when the operation completes, the TDE wallet is closed again.FORCE KEYSTORE
is useful for situations when the database is heavily loaded. In this scenario, because of concurrent access to encrypted objects in the database, the auto-login TDE wallet continues to open immediately after it has been closed but before a user has had chance to open the password-based TDE wallet.
TDE wallets can be in the following states: open, closed, open but with no master encryption key, open but with an unknown master encryption key, undefined, or not available (that is, not present in the WALLET_ROOT/tde
location).
After you manually open a TDE wallet, it remains open until you manually close it. Each time you restart a PDB or CDB, you must manually open the password TDE wallet to reenable encryption and decryption operations.
You can check the status of whether a TDE wallet is open or not by querying the STATUS
column of the V$ENCRYPTION_WALLET
view.
3.4.3.2 Opening the TDE Wallet in a United Mode PDB
To open a TDE wallet in united mode, you must use the ADMINISTER KEY MANAGEMENT
statement with the SET KEYSTORE OPEN
clause.
STATUS
column of the V$ENCRYPTION_WALLET
view reminds you with an OPEN_NO_MASTER_KEY
status.
Parent topic: Step 2: Open the TDE Wallet
3.4.4 Step 3: Set the TDE Master Encryption Key in the TDE Wallet
Once the TDE wallet is open, you can set a TDE master encryption key for it.
- About Setting the TDE Wallet TDE Master Encryption Key
The TDE master encryption key is stored in the TDE wallet. - Setting the TDE Master Encryption Key in the United Mode TDE Wallet
To set the TDE master encryption key in the TDE wallet when the PDB is configured in united mode, use theADMINISTER KEY MANAGEMENT
statement with theSET KEY
clause.
3.4.4.1 About Setting the TDE Wallet TDE Master Encryption Key
The TDE master encryption key is stored in the TDE wallet.
The TDE master encryption key protects the TDE table keys and tablespace encryption keys. By default, the TDE master encryption key is a key that TDE generates. You can find if a TDE wallet has no TDE master encryption key set or an unknown TDE master encryption key by querying the STATUS
column of the V$ENCRYPTION_WALLET
view.
You can import a master encryption key (bring your own key (BYOK)), that was created
outside of the database, into the TDE wallet. You can either set
a key for immediate use, using ADMINISTER KEY MANAGEMENT
SET
, or create a key using
ADMINISTER KEY MANAGEMENT CREATE
KEY
for later use, and activate it with the
ADMINISTER KEY MANAGEMENT USE KEY
statement.
3.5 Operations That Are Not Allowed in a United Mode PDB
ADMINISTER KEY MANAGEMENT
operations that are not allowed in a united mode PDB can be performed in the CDB root.
These operations are as follows:
-
Keystore operations:
-
Performing merge operations on keystores
-
Exporting a keystore
-
Importing a keystore
-
Migrating a keystore
-
Reverse-migrating a keystore
-
Moving the keys of a keystore that is in the CDB root into the keystores of a PDB
-
Moving the keys from a PDB into a united mode keystore that is in the CDB root
-
-
Encryption key operations:
-
Using the
CONTAINER = ALL
clause to create a new TDE master encryption key for later user in each pluggable database (PDB)
-
-
Client secret operations:
-
Adding client secrets
-
Updating client secrets
-
Deleting client secrets
-
Parent topic: Configuring United Mode
3.6 Configuring a Container Database with United Mode PDBs for Oracle Key Vault
The TDE master keys of all united mode PDBs and the CDB reside in the same virtual wallet in Oracle Key Vault.
- About Configuring a Container Database with United Mode PDBs for Oracle Key Vault
Oracle Key Vault is a fault-tolerant, scalable, and continuously available key and secrets management platform that was purpose-built for TDE master key management even for the largest, and most diverse, Oracle database deployments. - About Configuring a Container Database with United Mode PDBs for Oracle Key Vault
In united mode, you can configure Oracle Key Vault by setting theWALLET_ROOT
andTDE_CONFIGURATION
parameters in the container database (CDB). - Step 1: Configure Oracle Key Vault for United Mode
You can configure Oracle Key Vault for united mode PDBs by setting theWALLET_ROOT
andTDE_CONFIGURATION
parameters in the container database (CDB). - Step 2: Open the Connection to Oracle Key Vault
After you have configured the database to use Oracle Key Vault for TDE key management, you must open the connection to Oracle Key Vault before you can use it. - Step 3: Set the TDE Master Encryption Key in Oracle Key Vault
After you have opened the connection to Oracle Key Vault, you are ready to set the TDE master encryption key. - Step 4: Encrypt Your Data in United Mode
Now that you have completed the configuration for an external keystore or for an Oracle Key Vault keystore, you can begin to encrypt data.
Parent topic: Configuring United Mode
3.6.1 About Configuring a Container Database with United Mode PDBs for Oracle Key Vault
Oracle Key Vault is a fault-tolerant, scalable, and continuously available key and secrets management platform that was purpose-built for TDE master key management even for the largest, and most diverse, Oracle database deployments.
External keystores are external to an Oracle database. Oracle Database can interface with external keystores but cannot manipulate them outside of the Oracle interface. The Oracle database can request the external keystore to create a key but it cannot define how this key is stored in an external database. Examples of external keystores are Oracle Key Vault keystores. Supported external keystores are Oracle Key Vault and the Oracle Cloud Infrastructure Vault. (Conversely, for TDE wallets that are created using TDE, Oracle Database has full control: that is, you can use SQL statements to manipulate this type of keystore.)
To configure an external keystore, you must first define the keystore type in the TDE_CONFIGURATION
parameter setting, configure and open the external keystore, and then set the first TDE master encryption key in the external keystore. In short, there is one external keystore per database, and the database locates this keystore by checking the keystore type that you define in the TDE_CONFIGURATION
parameter.
3.6.2 About Configuring a Container Database with United Mode PDBs for Oracle Key Vault
In united mode, you can configure Oracle Key Vault by setting the WALLET_ROOT
and TDE_CONFIGURATION
parameters in the container database (CDB).
Oracle recommends that you set the parameters WALLET_ROOT
and TDE_CONFIGURATION
for new deployments. Alternatively, you can migrate from the old configuration in the sqlnet.ora file
to the new configuration with WALLET_ROOT
and TDE_CONFIGURATION
at your earliest convenience (for example, the next time you apply a quarterly bundle patch).
United Mode is the default TDE setup that is used in Oracle Database release 12.1.0.2 and later with the TDE configuration in sqlnet.ora
. In Oracle Database release 18c and later, TDE configuration in sqlnet.ora
is deprecated. You must first set the static initialization parameter WALLET_ROOT
to an existing directory; for this change to be picked up, a database restart is necessary. After the restart, set the KEYSTORE_CONFIGURATION
attribute of the dynamic TDE_CONFIGURATION
parameter to OKV
(for a password-protected connection into Oracle Key Vault), or OKV|FILE
for an auto-open connection into Oracle Key Vault, and then open the configured external keystore, and then set the TDE master encryption keys. After you complete these tasks, you can begin to encrypt data in your database.
3.6.3 Step 1: Configure Oracle Key Vault for United Mode
You can configure Oracle Key Vault for united mode PDBs by setting the WALLET_ROOT
and TDE_CONFIGURATION
parameters in the container database (CDB).
3.6.4 Step 2: Open the Connection to Oracle Key Vault
After you have configured the database to use Oracle Key Vault for TDE key management, you must open the connection to Oracle Key Vault before you can use it.
- About Opening the Connection to Oracle Key Vault
You must open the connection to Oracle Key Vault so that it is accessible to the database before you can perform any encryption or decryption. - Opening the Oracle Key Vault Connection in a United Mode PDB
To open the Oracle Key Vault connection in united mode, you must use theADMINISTER KEY MANAGEMENT
statement with theSET KEYSTORE OPEN
clause.
3.6.4.1 About Opening the Connection to Oracle Key Vault
You must open the connection to Oracle Key Vault so that it is accessible to the database before you can perform any encryption or decryption.
If a recovery operation is needed on your database (for example, if the database was not cleanly shut down, and has an encrypted tablespace that needs recovery), then you must open the connection to Oracle Key Vault before you can open the database itself.
There are two ways that you can open the Oracle Key Vault connection:
-
Manually open the keystore by issuing the
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN
statement. Afterward, you can perform the operation. -
Include the
FORCE KEYSTORE
clause in theADMINISTER KEY MANAGEMENT
statement.FORCE KEYSTORE
temporarily opens the keystore for the duration of the operation, and when the operation completes, the keystore is closed again.FORCE KEYSTORE
is useful for situations when the database is heavily loaded. In this scenario, because of concurrent access to encrypted objects in the database, the auto-login keystore continues to open immediately after it has been closed but before a user has had a chance to open the password-based keystore.
To check the status of the keystore, query the STATUS
column of the V$ENCRYPTION_WALLET
view. Keystores can be in the following states: CLOSED
, NOT_AVAILABLE
(that is, not present in the WALLET_ROOT
location), OPEN
, OPEN_NO_MASTER_KEY
, OPEN_UNKNOWN_MASTER_KEY_STATUS
.
Be aware that for external keystores, if the database is in the mounted state, then it cannot check if the master key is set because the data dictionary is not available. In this situation, the status will be OPEN_UNKNOWN_MASTER_KEY_STATUS
.
Related Topics
Parent topic: Step 2: Open the Connection to Oracle Key Vault
3.6.4.2 Opening the Oracle Key Vault Connection in a United Mode PDB
To open the Oracle Key Vault connection in united mode, you must use the ADMINISTER KEY MANAGEMENT
statement with the SET KEYSTORE OPEN
clause.
Parent topic: Step 2: Open the Connection to Oracle Key Vault
3.6.5 Step 3: Set the TDE Master Encryption Key in Oracle Key Vault
After you have opened the connection to Oracle Key Vault, you are ready to set the TDE master encryption key.
- About Setting the External Keystore TDE Master Encryption Key
You must create a TDE master encryption key that is stored inside the external keystore. - Heartbeat Batch Size for External Keystores
You can control the size of the batch of heartbeats issued during each heartbeat period. - Setting the TDE Master Encryption Key for United Mode PDBs in an External Keystore
To set the TDE master encryption key in the keystore when the PDB is configured in united mode, use theADMINISTER KEY MANAGEMENT
statement with theSET KEY
clause. - Migration of an Encrypted Database from a TDE Wallet to Oracle Key Vault or OCI KMS
To switch from a TDE wallet to centralized key management with Oracle Key Vault or Oracle Cloud Infrastructure (OCI) Key Management Service (KMS), after you upload all current and retired TDE master keys you must migrate the database from the TDE wallet to Oracle Key Vault or OCI KMS.
3.6.5.1 About Setting the External Keystore TDE Master Encryption Key
You must create a TDE master encryption key that is stored inside the external keystore.
Oracle Database uses the master encryption key from Oracle Key Vault or Oracle Cloud Infrastructure (OCI) Key Management Service (KMS) to encrypt or decrypt TDE table keys or tablespace encryption keys (data encryption keys) inside the database.
If you have not previously configured TDE with a wallet, then you must set the master encryption key in Oracle Key Vault or OCI KMS. If you have already configured TDE with a wallet, then you must migrate the database to Oracle Key Vault or OCI KMS.
Along with the current master encryption key, all TDE keystores (TDE wallet, Oracle Key Vault, and OCI KMS) maintain historical master encryption keys that are generated after every re-key operation that rekeys the master encryption key. These historical master keys help to restore Oracle Database backups that were taken previously using one of the master encryption keys. Only Oracle Key Vault allows you to upload all historical key from a TDE wallet before migrating the database to use Oracle Key Vault. After migration to Oracle Key Vault, the TDE wallet can be deleted, which satisfies security regulation that mandate that encryption keys cannot reside on the encrypting server.
3.6.5.2 Heartbeat Batch Size for External Keystores
You can control the size of the batch of heartbeats issued during each heartbeat period.
When a PDB is configured to use an external key manager, the GEN0
background process must perform a heartbeat request on behalf of the PDB to the external key manager. This background process ensures that the external key manager is available and that the TDE master encryption key of the PDB is available from the external key manager and can be used for both encryption and decryption. The GEN0
background process must complete this request within the heartbeat period (which defaults to three seconds).
When a very large number of PDBs (for example, 1000) are configured to use an external key manager, you can configure the HEARTBEAT_BATCH_SIZE
database instance initialization parameter to batch heartbeats and thereby mitigate the possibility of the hang analyzer mistakenly flagging the GEN0
process as being stalled when there was not enough time for it to perform a heartbeat for each PDB within the allotted heartbeat period.
By setting the heartbeat batch size, you can stagger the heartbeats across batches of PDBs to ensure that for each batch a heartbeat can be completed for each PDB within the batch during the heartbeat period, and also ensure that PDB master encryption keys can be reliably fetched from an Oracle Key Vault server and cached in the Oracle Key Vault persistent cache. The HEARTBEAT_BATCH_SIZE
parameter configures the size of the batch of heartbeats sent per heartbeat period to the external key manager. The value must be between 2 and 100 and it defaults to 5. The default duration of the heartbeat period is three seconds.
For example, if 500 PDBs are configured and are using Oracle Key Vault, the usual time taken by GEN0
to perform a heartbeat on behalf of a single PDB is less than half a second. In addition, assume that the CDB$ROOT
has been configured to use an external key manager such as Oracle Key Vault (OKV
). Therefore, it should generally be possible to send five heartbeats (one for the CDB$ROOT
and four for a four-PDB batch) in a single batch within every three-second heartbeat period.
Even though the HEARTBEAT_BATCH_SIZE
parameter configures the number of heartbeats sent in a batch, if the CDB$ROOT
is configured to use an external key manager, then each heartbeat batch must include a heartbeat for the CDB$ROOT
. The minimum value of the HEARTBEAT_BATCH_SIZE
parameter is 2 and its maximum value is 100. When the CDB$ROOT
is configured to use an external key manager, then each batch of heartbeats includes one heartbeat for the CDB$ROOT
. This is why the minimum batch size is two: one must be reserved for the CDB$ROOT
, because it might be configured to use an external key manager.
For example, suppose you set the HEARTBEAT_BATCH_SIZE
parameter as follows:
ALTER SYSTEM SET HEARTBEAT_BATCH_SIZE=3 SCOPE=BOTH SID='*';
Each iteration corresponds to one GEN0
three-second heartbeat period.
Example 1: Setting the Heartbeat for Containers That Are Configured to Use Oracle Key Vault
Suppose the container list is 1 2 3 4 5 6 7 8 9 10, with all containers configured to use Oracle Key Vault (OKV
). The iterations are as follows:
- Iteration 1: batch consists of containers: 1 2 3
- Iteration 2: batch consists of containers: 1 4 5
- Iteration 3: batch consists of containers: 1 6 7
- Iteration 4: batch consists of containers: 1 8 9
- Iteration 5: batch consists of containers: 1 10
- Repeat this cycle.
Example 2: Setting the Heartbeat for Isolated PDBs with Different Keystores (Root Container in Oracle Key Vault)
In this example, the container list is 1 2 3 4 5 6 7 8 9 10, with only odd-numbered PDBs configured to use OKV, and the even-numbered PDBs configured to use a TDE wallet (FILE
).
- Iteration 1: batch consists of containers: 1 3 5
- Iteration 2: batch consists of containers: 1 7 9
- Iteration 3: batch consists of containers: 1
- Repeat this cycle.
Example 3: Setting the Heartbeat for Isolated PDBs with Different Keystores (Root Container in TDE Wallet)
Assume that the container list is 1 2 3 4 5 6 7 8 9 10, with only even-numbered container numbers configured to use Oracle Key Vault, and the odd-numbered containers configured to use FILE
. In the following example, there is no heartbeat for the CDB$ROOT
, because it is configured to use FILE
.
- Iteration 1: batch consists of containers: 2 4 6
- Iteration 2: batch consists of containers: 8 10
- Repeat this cycle.
3.6.5.3 Setting the TDE Master Encryption Key for United Mode PDBs in an External Keystore
To set the TDE master encryption key in the keystore when the PDB is configured in united mode, use the ADMINISTER KEY MANAGEMENT
statement with the SET KEY
clause.
3.6.5.4 Migration of an Encrypted Database from a TDE Wallet to Oracle Key Vault or OCI KMS
To switch from a TDE wallet to centralized key management with Oracle Key Vault or Oracle Cloud Infrastructure (OCI) Key Management Service (KMS), after you upload all current and retired TDE master keys you must migrate the database from the TDE wallet to Oracle Key Vault or OCI KMS.
Tools such as Oracle Data Pump and Oracle Recovery Manager require access to the old TDE wallet to perform decryption and encryption operations on data exported or backed up using the TDE wallet. Along with the current master encryption key, Oracle keystores maintain historical master encryption keys that are generated after every re-key operation that rotates the master encryption key. These historical master encryption keys help to restore Oracle database backups that were taken previously using one of the historical master encryption keys.
Related Topics