Configuring Isolated Mode

Isolated mode enables you to create a keystore for each pluggable database (PDB).

• About Configuring Isolated Mode

  In isolated mode, where a pluggable database (PDB) has its own keystore and keystore password, you manage the keystore and its TDE master encryption keys from the PDB only.

• Operations That Are Allowed in Isolated Mode

  You can perform many ADMINISTER KEY MANAGEMENT operations in isolated mode.

• Operations That Are Not Allowed in an Isolated Mode PDB

  There are several ADMINISTER KEY MANAGEMENT operations that you cannot perform in an isolated mode PDB.

• Configuring the Keystore Location and Type for Isolated Mode

  For isolated mode, you can configure the keystore location and type by using only parameters or a combination of parameters and the ALTER SYSTEM statement.

• Configuring a TDE Wallet and TDE Master Encryption Key in Isolated Mode

  In isolated mode, the TDE wallet is associated with a PDB.

• Configuring a Container Database with Isolated Mode PDBs for Oracle Key Vault

  Isolated PDBs have their own virtual wallet, with their own password, in Oracle Key Vault.

About Configuring Isolated Mode

In isolated mode, where a pluggable database (PDB) has its own keystore and keystore password, you manage the keystore and its TDE master encryption keys from the PDB only.

Similar to united mode, you must first configure a PDB to use isolated mode by setting the WALLET_ROOT and TDE_CONFIGURATION parameters. After you set these parameters, you can create and manage the keystore from the PDB. In this way, you can have the following scenario:

• United mode PDBs inherit the TDE configuration from the root container. For example, the keystore that you create in the CDB root will be used by the root’s associated united mode PDBs.

• The PDBs that are configured in isolated mode are allowed to independently create and manage their own keystore. An isolated mode PDB can have its own keystore, independent of the keystore of the CDB root.

  This scenario is useful in cases where you have many PDBs that must use one type of keystore, but you have a few PDBs that must use a different type. By different types of keystores, this refers to either TDE wallet or to one of the external keystores that Oracle supports (for example, Oracle Key Vault or Cloud Key Management Service). You cannot have a mixture of different external keystore types in one CDB environment because the Oracle server can load only one PKCS#11 vendor library. If necessary, you can configure these PDBs in isolated mode so that each PDB can use its own keystore.

  Note: Oracle Cloud Infrastructure (OCI) cloud tooling does not support isolated PDBs. This non-support applies to Oracle Base Database Service (BaseDB), Oracle Exadata Database Service on Dedicated Infrastructure (ExaDB-D), ADB-D, ExaDB-D@Azure, Oracle Exadata Database Service on Cloud@Customer(ExaDB-C@C) , Oracle Autonomous AI Database on Dedicated Exadata Infrastructure (ADB-C@C), even when Oracle Key Vault provides key management for those database deployments.

Operations That Are Allowed in Isolated Mode

You can perform many ADMINISTER KEY MANAGEMENT operations in isolated mode.

These operations include creating, backing up, opening keystores; changing keystore passwords, merging keystores, closing keystores; creating, activating, tagging, moving, exporting, importing, and migrating encryption keys; and adding, updating, and deleting client secrets. The following list describes the ADMINISTER KEY MANAGEMENT operations that you can perform in an isolated mode PDB.

• Creating a keystore

  ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY isolated_PDB_keystore_password;

  You can create password-protected, local auto-login, and auto-login keystores in an isolated mode PDB.

• Creating an auto-login keystore

  ADMINISTER KEY MANAGEMENT CREATE [LOCAL] AUTO_LOGIN KEYSTORE FROM KEYSTORE IDENTIFIED BY
  isolated_PDB_keystore_password;

  The isolated PDB knows the keystore location of both password protected and (local) auto-open wallet from WALLET_ROOT/pdb_guid/tde.

• Opening a keystore

  ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN [FORCE KEYSTORE] IDENTIFIED BY EXTERNAL STORE |
  isolated_PDB_keystore_password;

  The EXTERNAL_STORE clause retrieves the isolated mode PDB keystore password from a wallet in the tde_seps directory in the WALLET_ROOT/PDB-GUID location.

• Changing a keystore password

  ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD IDENTIFIED BY old_isolated_PDB_keystore_password
  SET new_isolated_PDB_keystore_password WITH BACKUP [USING 'backup_identifier'];

• Backing up a TDE wallet

  ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE [USING 'backup_identifier'] IDENTIFIED BY EXTERNAL STORE |
  TDE_wallet_password] [TO 'TDE_wallet_backup_location'];

• Merging the contents of one keystore into an existing keystore

  ADMINISTER KEY MANAGEMENT MERGE KEYSTORE 'keystore1_location' [IDENTIFIED BY TDE_wallet1_password]
  INTO EXISTING KEYSTORE 'keystore2_location' IDENTIFIED BY TDE_wallet2_password WITH BACKUP [USING
  'backup_identifier'];

• Merging the contents of two keystores to create a third keystore

  ADMINISTER KEY MANAGEMENT MERGE KEYSTORE 'keystore1_location' [IDENTIFIED BY TDE_wallet1_password]
  AND KEYSTORE 'keystore2_password' [IDENTIFIED BY TDE_wallet2_password] INTO NEW KEYSTORE
  'keystore3_location' IDENTIFIED BY TDE_wallet3_password;

• Closing a keystore

  ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE [IDENTIFIED BY [EXTERNAL STORE | keystore_password]];

• Closing the keystore of the CDB root when a PDB in isolated mode has its keystore open

  ADMINISTER KEY MANAGEMENT FORCE KEYSTORE CLOSE [IDENTIFIED BY [EXTERNAL STORE | keystore_password]];

  The FORCE clause allows the keystore to be closed in the CDB root even when a PDB in isolated mode still has its keystore open

• Creating and activating a new TDE master encryption key (rekeying)

  ADMINISTER KEY MANAGEMENT SET [ENCRYPTION] KEY [USING TAG 'tag_name'] [FORCE KEYSTORE] IDENTIFIED BY
  [EXTERNAL STORE | keystore_password ]WITH BACKUP [USING 'backup_identifier'];

• 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 | TDE_wallet_password WITH
  BACKUP [USING 'backup_identifier'] [CONTAINER = CURRENT];

• Activating an existing TDE master encryption key

  ADMINISTER KEY MANAGEMENT USE [ENCRYPTION] KEY 'key_id' [USING TAG 'tag'] IDENTIFIED BY [EXTERNAL
  STORE | keystore_password] WITH BACKUP [USING 'backup_identifier'];

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

• Exporting a TDE master encryption key

  ADMINISTER KEY MANAGEMENT EXPORT [ENCRYPTION] KEYS WITH SECRET secret TO 'filename' IDENTIFIED BY
  TDE_wallet_password [WITH IDENTIFIER IN { 'key_id' [, 'key_id' ]... | ( subquery ) }];

• Importing a TDE master encryption key

  ADMINISTER KEY MANAGEMENT IMPORT [ENCRYPTION] KEYS WITH SECRET secret FROM 'filename' IDENTIFIED BY
  TDE_wallet_password WITH BACKUP [USING 'backup_identifier'];

• Migrating an encrypted database from a TDE wallet to Oracle Key Vault

  ADMINISTER KEY MANAGEMENT SET [ENCRYPTION] KEY IDENTIFIED BY Oracle_Key_Vault_password [FORCE
  KEYSTORE] MIGRATE USING TDE_wallet_password;

• Reverse-migrating an encrypted database from an external keystore to a TDE wallet

  ADMINISTER KEY MANAGEMENT SET [ENCRYPTION] KEY IDENTIFIED BY TDE_wallet_password REVERSE MIGRATE
  USING Oracle_Key_Vault_password;

• Adding a client secret

  ADMINISTER KEY MANAGEMENT ADD SECRET 'secret' FOR CLIENT 'client_identifier' [USING TAG 'tag_name' ]
  IDENTIFIED BY [EXTERNAL STORE | keystore_password] WITH BACKUP [USING 'backup_identifier'];

• Updating a client secret

  ADMINISTER KEY MANAGEMENT UPDATE SECRET 'secret' FOR CLIENT 'client_identifier' [USING TAG
  'tag_name' ] IDENTIFIED BY [EXTERNAL STORE | keystore_password] WITH BACKUP [USING
  'backup_identifier'];

• Deleting a client secret

  ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'client_identifier IDENTIFIED BY [EXTERNAL STORE
  | keystore_password] WITH BACKUP [USING 'backup_identifier'];

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

  This operation performs two actions. First, it changes the TDE_CONFIGURATION of the PDB so that it is in isolated mode. Second, it moves the PDB’s current and previously active TDE master encryption keys from the root keystore to a newly-created isolated keystore of the PDB, having its own isolated keystore password, where the PDB will be able to manage its own keys.

Operations That Are Not Allowed in an Isolated Mode PDB

There are several ADMINISTER KEY MANAGEMENT operations that you cannot perform in an isolated mode PDB.

These operations include the following:

• Using the CONTAINER = ALL clause to create a new TDE master encryption key for later use in each pluggable database (PDB)

• Moving encryption keys from the keystore of the CDB root into a keystore of a PDB that is configured in isolated mode

Configuring the Keystore Location and Type for Isolated Mode

For isolated mode, you can configure the keystore location and type by using only parameters or a combination of parameters and the ALTER SYSTEM statement.

Caution:

It is not recommended to configure PDB$SEED in ISOLATED mode, as it may impact subsequent PDB creation and database upgrade operations.

Do not upgrade databases to version 19.30 or later if PDB$SEED is in an isolated state. Ensure that PDB$SEED is moved back to UNITED mode before proceeding with the upgrade. If you upgrade to 19.30 while PDB$SEED is already isolated, the error PDB$SEED cannot be opened from MOUNT mode is encountered. Apply the temporary fix for bug 39113867 to transition PDB$SEED to UNITED mode. After confirming the change, remove the temporary fix and continue with the upgrade.

• About Configuring the Keystore Location and Type for Isolated Mode

  Configuring the WALLET_ROOT and TDE_CONFIGURATION parameters for the CDB environment is similar to the procedure used for united mode.

• Configuring the Keystore Location and Keystore Type for an Isolated Mode PDB

  You can configure isolated mode by setting WALLET_ROOT in the initialization parameter file in the CDB root and TDE_CONFIGURATION in the PDB you want to isolate.

• Example: Restoring an Older Version of a Control File

  You can set TDE_CONFIGURATION if you have an older version of a control file that must be restored and only a few PDBs were configured in isolated mode.

• Example: Addressing the Problem of a Lost Control File

  You can address the problem of a lost control file by using the ALTER SYSTEM statement.

• Example: Configuring Isolated Mode in an Oracle Real Application Clusters Environment

  You can use ALTER SYSTEM to configure isolated mode in an Oracle Real Application Clusters (Oracle RAC) environment.

• Resolving the Transition From an Isolated Mode PDB to a United Mode PDB in a Data Guard Environment

About Configuring the Keystore Location and Type for Isolated Mode

Configuring the WALLET_ROOT and TDE_CONFIGURATION parameters for the CDB environment is similar to the procedure used for united mode.

The difference is that rather than using the RESET clause of the ALTER SYSTEM statement, you use the SET clause. You can perform the configuration by adding the WALLET_ROOT and TDE_CONFIGURATION parameters to the initialization parameter file. To configure a PDB in isolated mode, you must set a value for the TDE_CONFIGURATION parameter of the PDB, which you can do either by using the ALTER SYSTEM statement or by issuing the ADMINISTER KEY MANAGEMENT ISOLATE KEYSTORE statement. This section focuses on the use of the ALTER SYSTEM statement.

Depending on whether your system uses pfile or spfile, you must set the SCOPE clause in the ALTER SYSTEM statement appropriately when setting the value of the TDE_CONFIGURATION parameter for the PDB. The value of the TDE_CONFIGURATION parameter is a list of attribute-value pairs, and it is the value of the KEYSTORE_CONFIGURATION attribute that specifies the type of the keystore, as follows:

• FILE specifies a TDE wallet.

• OKV specifies Oracle Key Vault.

• FILE|OKV specifies a reverse-migration from the OKV keystore type to the FILE keystore type has occurred.

• FILE|HSM specifies a reverse-migration from the HSM keystore type to the FILE keystore type has occurred.

• OKV|FILE specifies a migration from the FILE keystore type to the OKV keystore type has occurred. The keystore type has two meanings: it either means that you are migrating from FILE to OKV, or it means that the configuration started out as using OKV but is now using an auto-login OKV configuration, where the OKV password resides in a cwallet.sso file in the WALLET_ROOT/pdb_guid/tde directory.

  After you have used ALTER SYSTEM to configure the TDE_CONFIGURATION value for the selected PDB, the PDB in the CDB environment is in isolated mode. The steps in this procedure explain in detail how to configure an individual PDB to be in isolated mode, using its own keystore type.

Configuring the Keystore Location and Keystore Type for an Isolated Mode PDB

You can configure isolated mode by setting WALLET_ROOT in the initialization parameter file in the CDB root and TDE_CONFIGURATION in the PDB you want to isolate.

1. In the root, ensure that the WALLET_ROOT parameter is set correctly.

   For example:

   SHOW PARAMETER WALLET_ROOT

2. As a user who has the ADMINISTER KEY MANAGEMENT or SYSKM privilege, run the following statement in the PDB:

   ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY "iso_PDB_TDE_wallet_password";

   This statement does the following:

   • Sets the TDE_CONFIGURATION in the isolated PDB to FILE.

   • Creates the directories pdb_guid/tde under WALLET_ROOT.

   • Creates a new TDE wallet with its own password (which might be not known to the CDB administrator).

3. Check the configuration.

   • To check the TDE_CONFIGURATION parameter setting in the isolated PDB:

     SHOW PARAMETER TDE_CONFIGURATION

     The output should reflect the keystore configuration that you set for the current PDB. If it shows a different keystore configuration (for example, FILE if you had set it to OKV), then the setting may be showing the keystore configuration that was set for the CDB root, in united mode.

   • To check the keystore mode:

     SELECT KEYSTORE_MODE FROM V$ENCRYPTION_WALLET;

     The output should be ISOLATED.

     After you configure isolated mode, the CDB root keystore that was available to the PDB when it was in united mode is no longer available to this PDB. At this stage, the PDB is configured to use its own keystore. If the KEYSTORE_CONFIGURATION parameter was FILE (meaning that the PDB is configured to use a TDE wallet), then the keystore location configured for the PDB is WALLET_ROOT/PDB-GUID/tde. If a keystore exists at that location and contains a TDE master encryption key, then that key is only available to this PDB, not to any other PDB. If no keystore exists at that location, you now can now proceed to create a TDE wallet and set a TDE master encryption key. If you later decide that you want the isolated mode PDB to become a united mode PDB again, then you can use the ADMINISTER KEY MANAGEMENT UNITE KEYSTORE statement. When you run ADMINISTER KEY MANAGEMENT UNITE KEYSTORE, it moves the keys from the PDB’s keystore to the keystore of the CDB root, but it leaves any client secrets behind. So if there were no client secrets in the first place, then it would leave the PDB’s keystore essentially “empty”. It can now be backed up, and removed. Always back up keystores before you remove them, even empty keystores.

Related Topics

• Configuring United Mode with the Initialization Parameter File and ALTER SYSTEM

• Uniting a Pluggable Database Keystore

• Example: Configuring a TDE Wallet When Multiple Databases Share the Same Host

• Example: Configuring a TDE Wallet for an Oracle Automatic Storage Management Disk Group

Example: Restoring an Older Version of a Control File

You can set TDE_CONFIGURATION if you have an older version of a control file that must be restored and only a few PDBs were configured in isolated mode.

When the CDB root and the PDB are both in the mount state, then you can only change the PDB’s keystore configuration from the CDB root.

1. Log in to the CDB root as a user who was granted the SYSDBA administrative privilege.

2. For each PDB that you want to change, use the following syntax:

   ALTER SYSTEM SET TDE_CONFIGURATION="CONTAINER=pdb_name;KEYSTORE_CONFIGURATION=keystore_type" SCOPE=memory;

   For example, for the hrpdb and salespdb PDBs using FILE (for TDE wallets) as the keystore type:

   ALTER SYSTEM SET TDE_CONFIGURATION="CONTAINER=hrpdb;KEYSTORE_CONFIGURATION=FILE" SCOPE=memory;
   ALTER SYSTEM SET TDE_CONFIGURATION="CONTAINER=salespdb;KEYSTORE_CONFIGURATION=FILE" SCOPE=memory;

3. After you set the TDE_CONFIGURATION parameter for each PDB, log in to the CDB root and then set TDE_CONFIGURATION for the CDB root itself.

   ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE";

   At this stage, CDB root is in the mounted state. The value of the TDE_CONFIGURATION parameter that was set using ALTER SYSTEM with the CONTAINER attribute is only present in the memory of the CDB root. To ensure that the configuration is properly applied to each PDB, you must close and then reopen the PDB. When an isolated mode PDB is opened, the configuration set by the ALTER SYSTEM statement that was issued in the CDB root is read from the control file and then is automatically applied to the PDB.

4. Connect to each PDB and then close and reopen the PDB.

   ALTER PLUGGABLE DATABASE pdb_name CLOSE IMMEDIATE;
   ALTER PLUGGABLE DATABASE pdb_name OPEN;

Example: Addressing the Problem of a Lost Control File

You can address the problem of a lost control file by using the ALTER SYSTEM statement.

Running these statements with SCOPE set to memory will store the CONTAINER value in memory. When you open the isolated PDB, this configuration will automatically be updated for the PDB.

If you are using an Oracle Data Guard environment, then to correct the control file, run these statements on both the primary and the standby databases.

1. Log in to the CDB root as a user who was granted the SYSDBA administrative privilege.

2. If you are unsure of the exact state of the system, then you should run ALTER SYSTEM with RESET.

   For example:

   ALTER SYSTEM RESET TDE_CONFIGURATION SCOPE=memory;

3. For each PDB that you want to change, use the following syntax:

   ALTER SYSTEM SET TDE_CONFIGURATION="CONTAINER=pdb_name;KEYSTORE_CONFIGURATION=FILE" SCOPE=memory;

   For example, for the hrpdb and salespdb PDBs with FILE (for TDE wallets) as the keystore type:

   ALTER SYSTEM SET TDE_CONFIGURATION="CONTAINER=hrpdb;KEYSTORE_CONFIGURATION=FILE" SCOPE=memory;
   ALTER SYSTEM SET TDE_CONFIGURATION="CONTAINER=salespdb;KEYSTORE_CONFIGURATION=FILE" SCOPE=memory;

4. After you set the TDE_CONFIGURATION parameter for each PDB, log in to the CDB root and then set TDE_CONFIGURATION for the CDB root itself.

   ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE";

   At this stage, CDB root is in the mounted state. The value of the TDE_CONFIGURATION parameter that was set using ALTER SYSTEM with the CONTAINER attribute is only present in the memory of the CDB root. To ensure that the configuration is properly applied to each PDB, you must close and then reopen the PDB. When an isolated mode PDB is opened, the configuration set by the ALTER SYSTEM statement that was issued in the CDB root is read from the control file and then is automatically applied to the PDB.

5. Connect to each PDB and then close and reopen the PDB.

   ALTER PLUGGABLE DATABASE pdb_name CLOSE IMMEDIATE;
   ALTER PLUGGABLE DATABASE pdb_name OPEN;

Example: Configuring Isolated Mode in an Oracle Real Application Clusters Environment

You can use ALTER SYSTEM to configure isolated mode in an Oracle Real Application Clusters (Oracle RAC) environment.

To ensure that the effect of the ALTER SYSTEM statement is applied on each Oracle RAC node, specify the wildcard (*) in the SID clause of the ALTER SYSTEM statement, as follows. You can run this statement from either the CDB root or a PDB.

ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=keystore_type" SID='*';

Resolving the Transition From an Isolated Mode PDB to a United Mode PDB in a Data Guard Environment

1. In an Oracle Data Guard environment, convert the isolated PDB to unified mode on the primary database by running the following on the isolated PDB:

   ALTER SYSTEM RESET tde_configuration

2. On the standby (secondary) database, convert the same isolated PDB to united mode by running the following

   ALTER SYSTEM RESET tde_configuration

   Running ALTER SYSTEM RESET tde_configuration on the primary alone will not convert the PDB to united mode. To complete the conversion from isolated to united, you must run ALTER SYSTEM RESET tde_configuration for the same PDB on both the primary and the standby. If you only copy the wallets to the standby but do not run the reset command there, running the reset on the primary will not update the standby. The standby will continue to look for the master keys in the isolated PDB wallet directory, which will no longer contain the required keys. After converting the wallets on both the primary and standby to united mode, confirm that the Data Guard sync/redo apply is successful before performing any additional wallet-related operations.

Configuring a TDE Wallet and TDE Master Encryption Key in Isolated Mode

In isolated mode, the TDE wallet is associated with a PDB.

• About Configuring a TDE Wallet in Isolated Mode

  You can create all types of TDE wallets in isolated mode: password-protected, password protected with the credential provided from an external store, auto-login, local auto-login.

• Step 1: Create a TDE Wallet in a PDB Configured in Isolated Mode

  A password-protected TDE wallet requires a password to protect the keystore keys and credentials.

• Step 2: Open the TDE Wallet in an Isolated Mode PDB

  To open a TDE wallet in isolated mode, you must use the ADMINISTER KEY MANAGEMENT statement with the SET KEYSTORE OPEN clause.

• Step 3: Set the TDE Master Encryption Key in the TDE Wallet of the Isolated Mode PDB

  To set the TDE master encryption key in a TDE wallet in an isolated mode PDB, use the ADMINISTER KEY MANAGEMENT statement with the SET KEY clause.

• Step 4: Encrypt Your Data in Isolated Mode

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

About Configuring a TDE Wallet in Isolated Mode

You can create all types of TDE wallets in isolated mode: password-protected, password protected with the credential provided from an external store, auto-login, local auto-login.

To enable encryption in the PDB after it is configured in isolated mode with the KEYSTORE_CONFIGURATION attribute set to FILE (that is, to use a TDE wallet), you must create a TDE wallet, open the TDE wallet, and then set a TDE master encryption key in the TDE wallet. Afterward, you can begin to encrypt data for tables and tablespaces that will be accessible in the PDB.

In a multitenant environment, you can create a secure external store to hold the credentials of the TDE wallet. This feature enables you to hide the keystore password: it removes the need for storing the wallet password in any script or tool that accesses the database without user intervention, such as an overnight batch script. When the WALLET_ROOT parameter is specified, the location of the external store for the CDB root is WALLET_ROOT/tde_seps and for the PDB it is WALLET_ROOT/pdb_guid/tde_seps. When the WALLET_ROOT parameter is set, there is no longer a single central external store, so when a keystore password is updated, the corresponding external store must be updated as well. When the WALLET_ROOT parameter is not specified, then the location of the external store is the same for both the CDB root and for every PDB. The external store location must then be set by the EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION initialization parameter. When the WALLET_ROOT parameter is not specified, then there is a single central external store, so when you update the keystore password, only the central external store at the EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION must be updated.

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.

Related Topics

• Configuring an External Store for a Keystore Password

Step 1: Create a TDE Wallet in a PDB Configured in Isolated Mode

A password-protected TDE wallet requires a password to protect the keystore keys and credentials.

1. Connect to the isolated mode PDB as a 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;

   This command creates the /tde directory under WALLET_ROOT/pdb_guid (unless it already exists), and creates a password-protected TDE wallet in this directory. If WALLET_ROOT points to a shared directory in ASM (+DATA/DB_UNIQUE_NAME), then the pdb_guid/tde subdirectory and the TDE wallet is auto-created by the CREATE KEYSTORE statement.

   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/pdb_guid/tde directory:

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

   After you complete these steps, the ewallet.p12 file, which is the TDE wallet, appears in the TDE wallet location.

Related Topics

• Creating an Auto-Login or a Local Auto-Login TDE Wallet

Step 2: Open the TDE Wallet in an Isolated Mode PDB

To open a TDE wallet in isolated mode, you must use the ADMINISTER KEY MANAGEMENT statement with the SET KEYSTORE OPEN clause.

1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

2. 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 switch over to opening the password-protected TDE wallet when an auto-login wallet is configured and is currently 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.

   Here, the IDENTIFIED BY EXTERNAL STORE clause is included in the statement because the 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, then Oracle Database finds the external store by searching in this path: WALLET_ROOT/pdb_guid/tde_seps.

3. Confirm that the TDE wallet is open.

   SELECT STATUS FROM V$ENCRYPTION_WALLET;

Related Topics

• About Opening TDE Wallets

Step 3: Set the TDE Master Encryption Key in the TDE Wallet of the Isolated Mode PDB

To set the TDE master encryption key in a TDE wallet in an isolated mode PDB, use the ADMINISTER KEY MANAGEMENT statement with the SET KEY clause.

1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

2. Ensure that the database is open in READ WRITE mode.

   To find the status, run the show pdbs command.

3. Run the ADMINISTER KEY MANAGEMENT SQL statement to set the key in the TDE wallet.

   For example, if the TDE wallet of the PDB is password-protected, the PDB is open, and the TDE wallet of the PDB is open:

   ADMINISTER KEY MANAGEMENT SET KEY
   IDENTIFIED BY TDE_wallet_password
   WITH BACKUP USING 'emp_key_backup';
   
   keystore altered.

   If the TDE wallet is closed:

   ADMINISTER KEY MANAGEMENT SET KEY
   FORCE KEYSTORE
   IDENTIFIED BY TDE_wallet_password
   WITH BACKUP USING 'emp_key_backup';
   
   keystore altered.

   In this specification:

   • FORCE KEYSTORE should be included if the TDE wallet is closed. This automatically opens the TDE wallet 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.

4. Confirm that the TDE master encryption key is set.

   SELECT MASTERKEY_ACTIVATED FROM V$DATABASE_KEY_INFO;

   The output should be YES.

Related Topics

• About Setting the TDE Wallet TDE Master Encryption Key

Step 4: Encrypt Your Data in Isolated Mode

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

Related Topics

• Encrypting Columns in Tables

• Encryption Conversions for Tablespaces and Databases

Configuring a Container Database with Isolated Mode PDBs for Oracle Key Vault

Isolated PDBs have their own virtual wallet, with their own password, in Oracle Key Vault.

• About Configuring an External Keystore in Isolated Mode

  You can configure an external keystore for a PDB when the PDB is configured in isolated mode.

• Step 1: Configure Isolated PDBs for Oracle Key Vault

  You can configure isolated mode PDBs for Oracle Key Vault by setting the TDE_CONFIGURATION parameter.

• Step 2: Open the Isolated Mode PDB External Keystore

  If the isolated PDB does not have an auto-open connection into the external keystore, then you must open it manually before your open the PDB.

• Step 3: Set the First TDE Master Encryption Key in the External Keystore

  After you have opened the external keystore in an isolated mode PDB, you are ready to set the TDE master encryption key for the PDB.

• Step 4: Encrypt Your Data in Isolated Mode

  Now that you have completed the keystore configuration and the PDB is configured in isolated mode, you can begin to encrypt data in the PDB.

About Configuring an External Keystore in Isolated Mode

You can configure an external keystore for a PDB when the PDB is configured in isolated mode.

To configure an external keystore for a PDB in isolated mode, you first must set the WALLET_ROOT parameter. This is necessary for two reasons: first, to have support for migrating to a TDE wallet in the future, and second, because the configuration file for Oracle Key Vault is retrieved from a location under WALLET_ROOT. Afterwards, you must set the KEYSTORE_CONFIGURATION attribute of the TDE_CONFIGURATION parameter to OKV, open the configured external keystore, and then set the TDE master encryption key for the PDB. After you complete these tasks, you can begin to encrypt data in your database.

How you specify the IDENTIFIED BY clause when you run the ADMINISTER KEY MANAGEMENT statement depends on the type of external keystore. Use the following syntax:

IDENTIFIED BY EXTERNAL STORE|Oracle_Key_Vault_password

Enter the Oracle Key Vault 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.

Step 1: Configure Isolated PDBs for Oracle Key Vault

You can configure isolated mode PDBs for Oracle Key Vault by setting the TDE_CONFIGURATION parameter.

1. If the WALLET_ROOT parameter is set, then install the Oracle Key Vault client software into the WALLET_ROOT/pdb_guid/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 can be OKV, to configure a password-protected Oracle Key Vault keystore, or OKV|TDE for an auto-open connection into Oracle Key Vault.

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

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

Step 2: Open the Isolated Mode PDB External Keystore

If the isolated PDB does not have an auto-open connection into the external keystore, then you must open it manually before your open the PDB.

1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.

2. Open the external keystore as follows, by enclosing the password in double quotation marks:

   For example:

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN
   IDENTIFIED BY "Oracle_Key_Vault_password" | EXTERNAL STORE;

3. Repeat this procedure each time you restart the database instance.

   You must open the keystore of the CDB root first.

Related Topics

• About Opening the Connection to Oracle Key Vault

Step 3: Set the First TDE Master Encryption Key in the External Keystore

After you have opened the external keystore in an isolated mode PDB, you are ready to set the TDE master encryption key for the PDB.

• Setting the TDE Master Encryption Key in the Isolated Mode External Keystore

  You should complete this procedure if you have not previously configured an external keystore for Transparent Data Encryption.

• Migration of a Previously Configured Encryption Key in Isolated Mode

  You must migrate the previously configured master encryption key if you previously configured a TDE wallet.

Setting the TDE Master Encryption Key in the Isolated Mode External Keystore

You should complete this procedure if you have not previously configured an external keystore for Transparent Data Encryption.

1. Connect to the isolated mode PDB as a 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 TDE master encryption key if OPEN_MODE is set to READ WRITE. To find the status, run the show pdbs command.

3. 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=30 SCOPE=BOTH SID='*';

4. Set the new TDE master encryption key by using the following syntax:

   ADMINISTER KEY MANAGEMENT SET KEY
   [USING TAG 'tag']
   [FORCE KEYSTORE]
   IDENTIFIED BY EXTERNAL STORE|Oracle_Key_Vault_password;

   In this specification:

   • FORCE KEYSTORE temporarily opens the password-protected TDE wallet for this operation if the TDE wallet is closed, if an auto-login TDE wallet is configured and is currently open, or if a password-protected TDE wallet is configured and is currently closed.

   • 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 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
       USING TAG 'sessionid=3205062574:terminal=xcvt'
       FORCE KEYSTORE
       IDENTIFIED BY EXTERNAL STORE;
       
       keystore altered.

5. Confirm that the TDE master encryption key is set.

   SELECT MASTERKEY_ACTIVATED FROM V$DATABASE_KEY_INFO;

   The output should be YES.

Related Topics

• About Setting the External Keystore TDE Master Encryption Key

Migration of a Previously Configured Encryption Key in Isolated Mode

You must migrate the previously configured master encryption key if you previously configured a TDE wallet.

Related Topics

• Migration of an Encrypted Database from a TDE Wallet to Oracle Key Vault or OCI KMS

Step 4: Encrypt Your Data in Isolated Mode

Now that you have completed the keystore configuration and the PDB is configured in isolated mode, you can begin to encrypt data in the PDB.

Related Topics

• Encrypting Columns in Tables

• Encryption Conversions for Tablespaces and Databases

• Oracle Key Vault Administrator’s Guide