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.

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:

  1. In the CDB root, configure the database to use united mode by setting the WALLET_ROOT and TDE_CONFIGURATION parameters.

    The WALLET_ROOT parameter sets the location for the wallet directory and the TDE_CONFIGURATION parameter sets the type of keystore to use.

  2. Restart the database after setting the static initialization parameter WALLET_ROOT, then set the dynamic initialization parameter TDE_CONFIGURATION.

  3. In the CDB root, create the keystore, open the keystore, and then create the TDE master encryption key.

  4. 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.

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 CONTAINER clause.

Opening a keystore

ADMINISTER KEY MANAGEMENT 
SET KEYSTORE OPEN
IDENTIFIED BY
[EXTERNAL STORE | keystore_password]
[CONTAINER = ALL | CURRENT];

In this operation, the EXTERNAL STORE clause fetches the keystore password from the SSO wallet located in the WALLET_ROOT/tde_seps directory.

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 CONTAINER clause.

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 CONTAINER clause.

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 (SET) or later on (CREATE)

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 CONTAINER clause.

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 CONTAINER clause.

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 CONTAINER clause.

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 EXTERNAL_STORE clause uses the password in the TDE SEPS SSO wallet. This wallet is located in the tde_seps directory in the WALLET_ROOT location.

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 (SET) or later on (CREATE)

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 CONTAINER clause.

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 CONTAINER clause.

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 CONTAINER clause.

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 CONTAINER clause.

Using the FORCE clause when a clone of a PDB is using the TDE master encryption key that is being isolated; then copying (rather than moving) the TDE master encryption keys from the keystore that is in the CDB root into the isolated mode keystore of the PDB

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]];

-

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.

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.

  1. Log in to the database server where the CDB root of the Oracle database resides.
  2. If necessary, create a wallet directory.
    This directory cannot contain any wallets. Oracle recommends that you create a directory outside of $ORACLE_HOME or $ORACLE_BASE, to avoid backing up the keystore (wallet or Oracle Key Vault installation tree) with the encrypted database during an operating system-level backup.
  3. Connect to the CDB root as a common user who has been granted the ALTER SYSTEM privilege.
  4. Run the following ALTER SYSTEM statement:
    ALTER SYSTEM SET WALLET_ROOT='/etc/ORACLE/KEYSTORES/${ORACLE_SID}' SCOPE = SPFILE;
  5. Restart the CDB.
    SHUTDOWN IMMEDIATE
    STARTUP
  6. In the CDB root, check the WALLET_ROOT setting.
    SHOW PARAMETER WALLET_ROOT

    The VALUE column of the output should show the absolute path location of the wallet directory. For example:

    wallet_root string /etc/ORACLE/KEYSTORES/finance
  7. Set the TDE_CONFIGURATION dynamic initialization parameter to specify the keystore type, using the following syntax:
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=keystore_type" 
    SCOPE=BOTH;

    In this specification:

    • keystore_type can be one of the following settings:

      • FILE configures a TDE keystore.

      • OKV configures an Oracle Key Vault keystore.

    • scope_type sets the type of scope, which in this case is BOTH.

    To configure a TDE keystore if the server parameter file (spfile) is in use:

    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" 
    SCOPE=BOTH SID = '*';
  8. Check the TDE_CONFIGURATION parameter setting.
    SHOW PARAMETER TDE_CONFIGURATION
    

    The VALUE column should show the keystore type, prepended with KEYSTORE_CONFIGURATION=.

  9. Confirm that the TDE_CONFIGURATION parameter was set correctly.
    SELECT CON_ID, KEYSTORE_MODE FROM V$ENCRYPTION_WALLET;
    The output should be similar to the following:
        CON_ID KEYSTORE
    ---------- --------
             1 NONE
             2 UNITED
             3 UNITED
             4 UNITED
             5 UNITED
    
    The CDB root (CON_ID 1) will always be in the NONE state, and at this stage, the remaining CON_IDs should be set to UNITED. PDBs can be either UNITED or ISOLATED, depending on how you configure them. When you query the V$ENCRYPTION_WALLET view, if the ORA-46691: The value of the KEYSTORE_CONFIGURATION attribute is invalid error appears, then check the initialization parameter file where you added this setting.
After you configure united mode, you can create keystores and master encryption keys, and when these are configured, you can encrypt data.

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.

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.

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

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.

After you create this TDE wallet in the CDB root, it becomes available for all united PDBs, but not for isolated PDBs.
A TDE wallet can only contain TDE-related security objects, and no security objects used by other database or application components. In addition, do not use orapki or mkstore to create password-protected or (local) auto-open TDE wallets. Instead, use the ADMINISTER KEY MANAGEMENT statement.
  1. Connect to the CDB root as a common user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
  2. Use the SHOW PARAMETER command to confirm that WALLET_ROOT is set, and TDE_CONFIGURATION is set to KEYSTORE_CONFIGURATION=FILE.
  3. Run the ADMINISTER KEY MANAGEMENT SQL statement to create the TDE wallet using the following syntax:
    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE 
    IDENTIFIED BY TDE_wallet_password;

    The /tde directory is automatically created under WALLET_ROOT, if it does not already exist. In Oracle Automatic Storage Management (Oracle ASM), for the /tde directory to be automatically created if it does not already exist, WALLET_ROOT must point to +DATA/ORACLE_UNQNAME.

    In this specification, TDE_wallet_password is the password of the TDE wallet that you, the security administrator, creates.

    For example, to create the TDE wallet in the WALLET_ROOT/tde directory:

    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY TDE_wallet_password;
    
    keystore altered.

    After you run this statement, the ewallet.p12 file, which is the TDE wallet, appears in the TDE wallet location.

After you complete these steps, the 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.
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.

Both of these TDE wallets have system-generated passwords. They are also PKCS#12-based files. The auto-login TDE wallet can be opened from different computers from the computer where this TDE wallet resides, but the local auto-login TDE wallet can only be opened from the computer on which it was created. Both the auto-login and local auto-login TDE wallets are created from the password-protected TDE wallets. Creating any of them does not require database downtime.
  1. Connect to the CDB root as a common user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
  2. Use the SHOW PARAMETER command to confirm that WALLET_ROOT is set, and TDE_CONFIGURATION is set to KEYSTORE_CONFIGURATION=FILE.
  3. Create the auto-login or local auto-login TDE wallet by using the following syntax:
    ADMINISTER KEY MANAGEMENT CREATE [LOCAL] AUTO_LOGIN KEYSTORE 
    FROM KEYSTORE IDENTIFIED BY TDE_wallet_password;

    In this specification:

    • LOCAL enables you to create a local auto-login TDE wallet. Otherwise, omit this clause if you want the TDE wallet to be accessible by other computers. LOCAL creates a local auto-login wallet file, cwallet.sso, and this wallet will be tied to the host on which it was created. For an Oracle Real Application Clusters (Oracle RAC) environment, omit the LOCAL keyword, because each Oracle RAC node has a different host name. If you configure a local auto-login wallet for the Oracle RAC instance, then only the first Oracle RAC node, where the cwallet.sso file was created, would be able to access the TDE wallet. If you try to open the TDE wallet from another node instead of from that first node, there would be a problem auto-opening cwallet.sso, and so it would result in a failure to auto-open the TDE wallet. This restriction applies if you are using a shared location to hold the cwallet.sso file for the Oracle RAC cluster, because using LOCAL only works if you have a separate cwallet.sso file (containing the same credentials) on each node of the Oracle RAC environment.

    • TDE_wallet_password is the password of the TDE wallet from which you want to create.

    For example, to create an auto-login TDE wallet of the password-protected TDE wallet that is located in the ORACLE_WALLET/tde directory:

    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE 
    FROM KEYSTORE IDENTIFIED BY password;
    
    keystore altered.

    After you run this statement, the cwallet.sso file appears in the TDE wallet location. The ewallet.p12 file is the password-protected 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 the PKCS#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 the ENCRYPTION_WALLET_LOCATION parameter set, then be aware this parameter is deprecated. Oracle recommends that you use the WALLET_ROOT static initialization parameter and TDE_CONFIGURATION dynamic initialization parameter instead.

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.

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 the ADMINISTER 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.

  1. Connect to the CDB root as a common user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
  2. Open the TDE wallet in the CDB root.
    For example:
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY password;
    
    keystore altered.

    If the CDB is configured with the TDE wallet password stored in WALLET_ROOT/tde_seps and has a (local) auto-login TDE wallet in WALLET_ROOT/tde, you must include the FORCE KEYSTORE clause and the IDENTIFIED BY EXTERNAL STORE clause in the ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN statement, as follows:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    FORCE KEYSTORE 
    IDENTIFIED BY EXTERNAL STORE;
    
    keystore altered.

    If the WALLET_ROOT parameter has been set, then Oracle Database finds the external store in the WALLET_ROOT/tde_seps directory.

  3. Ensure that the PDB in which you want to open the TDE wallet is in READ WRITE mode.
    For example:
    SHOW PDBS
    
    CON_ID CON_NAME   OPEN MODE    RESTRICTED
    ------ ---------- ------------ -----------
    2      PDB$SEED   READ ONLY    NO
    3      CDB1_PDB1  READ WRITE   NO

    If any PDB has an OPEN MODE value that is different from READ WRITE, then run the following statement to open the PDB, which will set it to READ WRITE mode:

    ALTER PLUGGABLE DATABASE CDB1_PDB1 OPEN;

    Now the TDE wallet can be opened in both the CDB root and the PDB.

  4. Connect to the PDB.
  5. Run the ADMINISTER KEY MANAGEMENT statement to open the TDE wallet.
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY TDE_wallet_password | EXTERNAL STORE;
    keystore altered.

    To open a password-protected TDE wallet when a (local) auto-login TDE wallet is open, specify the FORCE KEYSTORE clause as follows.

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    FORCE KEYSTORE 
    IDENTIFIED BY TDE_wallet_password | EXTERNAL STORE;
    keystore altered.

    FORCE KEYSTORE is also useful for databases that are heavily loaded. The IDENTIFIED BY EXTERNAL STORE clause is included in the statement because the TDE wallet credentials exist in an external store. This enables the password-protected TDE wallet to be opened without specifying the TDE wallet password within the statement itself.

    If the WALLET_ROOT parameter has been set in the CDB, then united PDBs find the external store in the WALLET_ROOT/tde_seps directory.

  6. Confirm that the TDE wallet is open.
    SELECT STATUS FROM V$ENCRYPTION_WALLET;
Note that if the TDE wallet is open but you have not created a TDE master encryption key yet, the STATUS column of the V$ENCRYPTION_WALLET view reminds you with an OPEN_NO_MASTER_KEY status.

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.

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 set a key for immediate use, using ADMINISTER KEY MANAGEMENT SET, or create a key for later use, by activating it with the ADMINISTER KEY MANAGEMENT USE KEY statement.

3.4.4.2 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 the ADMINISTER KEY MANAGEMENT statement with the SET KEY clause.

  1. Connect to the CDB root as a common user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
  2. Ensure that the CDB is open in READ WRITE mode.
    You can set the TDE master encryption key if OPEN_MODE is set to READ WRITE. To find the status, query the OPEN_MODE column of the V$DATABASE dynamic view. (If you cannot access this view, then connect as SYSDBA and try the query again. In order to connect as SYSKM for this type of query, you must create a password file for it.)
  3. Run the ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY statement to set the TDE master encryption key in the TDE wallet.
    Use the following syntax:
    ADMINISTER KEY MANAGEMENT SET KEY 
    [USING TAG 'tag'] 
    [FORCE KEYSTORE] 
    IDENTIFIED BY EXTERNAL STORE | TDE_wallet_password 
    WITH BACKUP [USING 'backup_identifier'];

    In this specification:

    • tag is the associated attributes and information that you define. Enclose this setting in single quotation marks (' ').
    • FORCE KEYSTORE should be included if the TDE wallet is closed. This automatically opens the keystore before setting the TDE master encryption key. The FORCE KEYSTORE clause also switches over to opening the password-protected TDE wallet when an auto-login TDE wallet is configured and is currently open.

    • IDENTIFIED BY specifies the TDE wallet password. Alternatively, if the TDE wallet password is in an external store, you can use the IDENTIFIED BY EXTERNAL STORE clause.

    • WITH BACKUP creates a backup of the TDE wallet. You must use this option for password-protected TDE wallets. Optionally, you can use the USING clause to add a brief description of the backup. Enclose this description in single quotation marks (' '). This identifier is appended to the named TDE wallet file (for example, ewallet_time_stamp_emp_key_backup.p12, with emp_key_backup being the backup identifier). Follow the file naming conventions that your operating system uses.

    For example, if the TDE wallet is password-protected and open, and you want to set the TDE master encryption key in the current container:

    ADMINISTER KEY MANAGEMENT SET KEY 
    IDENTIFIED BY EXTERNAL STORE | TDE_wallet_password 
    WITH BACKUP USING 'emp_key_backup';

    If the TDE wallet is closed:

    ADMINISTER KEY MANAGEMENT SET KEY 
    [USING TAG 'tag']
    FORCE KEYSTORE
    IDENTIFIED BY EXTERNAL STORE | TDE_wallet_password 
    WITH BACKUP USING 'emp_key_backup';
  4. Confirm that the TDE master encryption key is set.
    SELECT MASTERKEY_ACTIVATED FROM V$DATABASE_KEY_INFO;

    The output should be YES.

3.4.5 Step 4: Encrypt Your Data in United Mode

Now that you have completed the configuration, you can begin to encrypt data.

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

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.

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).

  1. If the WALLET_ROOT parameter is set, then install the Oracle Key Vault client software into the WALLET_ROOT/okv directory.
  2. Log in to the database instance as a user who has been granted the ALTER SYSTEM administrative privilege.
  3. Set the TDE_CONFIGURATION dynamic initialization parameter to specify the keystore type by using the following syntax:
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=keystore_type" SCOPE=BOTH SID = '*';

    In this specification:

    • keystore_type is OKV, to configure an Oracle Key Vault keystore.

    For example, to configure your database to use Oracle Key Vault:

    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=OKV" 
    SCOPE=BOTH SID = '*";

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.

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 the ADMINISTER 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.

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.

  1. Connect to the CDB root as a common user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
  2. Open the keystore in the CDB root by using the following syntax.
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY EXTERNAL STORE | "Oracle_Key_Vault_password" 
    [CONTAINER = ALL | CURRENT];

    In this specification:

    • IDENTIFIED BY can be one of the following settings:

      • EXTERNAL STORE uses the keystore password stored in the external store to perform the keystore operation.

      • Oracle_Key_Vault_password is the Oracle Key Vault password that was giving during the Oracle Key Vault client installation. If no password was given, then the password in the ADMINISTER KEY MANAGEMENT statement becomes NULL. Enclose this password in double quotation marks.

    • CONTAINER specifies the scope in which to open the Oracle Key Vault connection.

      • ALL opens the connection to Oracle Key Vault for the root container and all open united PDBs.
      • CURRENT opens the connection to Oracle Key Vault for the root container.

    If the password contains a semi-colon (;), then enclose the password in double quotation marks.

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY "Oracle_Key_Vault_password";
  3. Ensure that the PDB in which you want to open the keystore is in READ WRITE mode.
  4. Connect to the PDB and run the ADMINISTER KEY MANAGEMENT statement to open the keystore.
    For example:
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY "external_key_manager_password";
  5. Confirm that the keystore is open.
    SELECT STATUS FROM V$ENCRYPTION_WALLET;
  6. Repeat this procedure each time you restart the PDB.

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.

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.

  1. Connect to the CDB root as a common user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
  2. Ensure that the database is open in READ WRITE mode.

    You can set the master encryption key if OPEN_MODE is set to READ WRITE. To find the status, for a non-multitenant environment, query the OPEN_MODE column of the V$DATABASE dynamic view. If you are in a multitenant environment, then run the show pdbs command.

  3. To enable or disable in-memory caching of master encryption keys, set the TDE_KEY_CACHE initialization parameter.
    This optional setting is only available for databases in Oracle Cloud Infrastructure (OCI) that use the OCI Key Management Service (KMS) for key management.
    Enabling in-memory caching of master encryption keys helps to reduce the dependency on the OCI KMS during the decryption of data encryption keys. By having the master encryption key local to the database, you can improve the database availability by avoiding the failures that can happen because of intermittent network issues if the calls were made to the key server instead. A setting of TRUE enables in-memory caching; FALSE disables it.
    ALTER SYSTEM SET TDE_KEY_CACHE = TRUE SCOPE=BOTH SID='*';
  4. To configure the heartbeat batch size, set the HEARTBEAT_BATCH_SIZE initialization parameter.
    The HEARTBEAT_BATCH_SIZE parameter configures the size of the "batch of heartbeats" sent per heartbeat period to the external key manager. Enter a value between 2 and 100. The default value is 5. The default duration of the heartbeat period is three seconds. 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 the TDE master encryption key of the PDB can be reliably fetched from an Oracle Key Vault server and cached in the Oracle Key Vault persistent cache. (See Heartbeat Batch Size for External Keystores for details about how HEARTBEAT_BATCH_SIZE works.)
    ALTER SYSTEM SET HEARTBEAT_BATCH_SIZE=3 SCOPE=BOTH SID='*';
  5. Run the ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY statement to set the TDE master encryption key in the keystore.
    ADMINISTER KEY MANAGEMENT SET KEY 
    [USING TAG 'tag'] 
    [FORCE KEYSTORE] 
    IDENTIFIED BY [EXTERNAL STORE | "external_key_manager_password"];
    

    In this specification:

    • tag is the associated attributes and information that you define. Enclose this setting in single quotation marks (' ').

    • FORCE KEYSTORE temporarily opens the password-protected TDE wallet for this operation. You must open the TDE wallet for this operation.

    • IDENTIFIED BY can be one of the following settings:

      • EXTERNAL STORE uses the keystore password stored in the external store to perform the keystore operation.

      • external_key_manager_password is for an external keystore manager, which can be Oracle Key Vault or OCI Vault - Key Management. Enclose this password in double quotation marks. For Oracle Key Vault, enter the password that was given during the Oracle Key Vault client installation. If at that time no password was given, then the password in the ADMINISTER KEY MANAGEMENT statement becomes NULL.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEY 
    FORCE KEYSTORE 
    IDENTIFIED BY "external_key_manager_password";
    
    keystore altered.
  6. Confirm that the TDE master encryption key is set.
    SELECT MASTERKEY_ACTIVATED FROM V$DATABASE_KEY_INFO;

    The output should be YES.

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.

3.6.6 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.