In united mode, you must create the keystore in the CDB root.

1. Connect to the CDB root as a common user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
   For example:

   CONNECT c##sec_admin AS SYSKM
   Enter password: password

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 keystore using the following syntax:

   ADMINISTER KEY MANAGEMENT CREATE KEYSTORE 
   IDENTIFIED BY software_keystore_password;
   

   This command creates the /tde directory under WALLET_ROOT (unless it already exists), and creates a password-protected wallet in this directory. If WALLET_ROOT points to a shared directory in ASM, then the /tde subdirectory is not auto-created and must exist before you can execute the CREATE KEYSTORE statement.

   In this specification, software_keystore_password is the password of the keystore that you, the security administrator, creates.

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

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

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

To open a software keystore 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.
   For example:

   CONNECT c##sec_admin AS SYSKM
   Enter password: password

2. Open the keystore in the CDB root.
   For example:

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
   IDENTIFIED BY password;
   
   keystore altered.

   If the CDB is configured using the EXTERNAL_KEYSTORE_CREDENTIAL_LOCATION instance initialization parameter and has a keystore at that location containing the credentials of the password-protected keystore, and you want to switch over from using an auto-login keystore to using the password-protected keystore with these credentials, 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 by searching in this path in the CDB root: WALLET_ROOT/tde_seps.

3. Ensure that the PDB in which you want to open the keystore 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 keystore 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 keystore.

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
   IDENTIFIED BY password;
   keystore altered.

   To switch over to opening the password-protected software keystore when an auto-login keystore is configured and is currently open, specify the FORCE KEYSTORE clause as follows.

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
   FORCE KEYSTORE 
   IDENTIFIED BY 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 keystore credentials exist in an external store. This enables the password-protected keystore to be opened without specifying the keystore 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.

6. Confirm that the keystore is open.

   SELECT STATUS FROM V$ENCRYPTION_WALLET;

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.
   For example:

   CONNECT c##sec_admin AS SYSKM
   Enter password: password

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 keystore.
   Use the following syntax:

   ADMINISTER KEY MANAGEMENT SET KEY 
   [USING TAG 'tag'] 
   [FORCE KEYSTORE] 
   IDENTIFIED BY [EXTERNAL STORE] | keystore_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 keystore 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 software keystore when an auto-login keystore is configured and is currently open.

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

   • WITH BACKUP creates a backup of the keystore. You must use this option for password-protected keystores. 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 keystore 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 keystore 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 keystore_password 
   WITH BACKUP USING 'emp_key_backup';
   
   keystore altered.

   If the keystore is closed:

   ADMINISTER KEY MANAGEMENT SET KEY 
   [USING TAG 'tag']
   FORCE KEYSTORE
   IDENTIFIED BY keystore_password 
   WITH BACKUP USING 'emp_key_backup';
   
   keystore altered.

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

   SELECT MASTERKEY_ACTIVATED FROM V$DATABASE_KEY_INFO;

   The output should be YES.

To open an external keystore 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.
   For example:

   CONNECT c##sec_admin AS SYSKM
   Enter password: password

2. Open the keystore in the CDB root by using the following syntax.

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
   [FORCE KEYSTORE]
   IDENTIFIED BY "hardware_keystore_credentials";
   

   In this specification:

   • FORCE KEYSTORE enables the keystore operation if the keystore is 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.

     • external_keystore_credentials refers to the credentials for either an HSM or an Oracle Key Vault external keystore. For some HSMs, specify the credentials using this format, enclosed in quotation marks and separating the components with a colon: "user_name:password", with user_name being the user who created the HSM and password being this user’s password. 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.

   The type of external keystore determines how you specify the external keystore password. For hardware security modules, you must use the user_name:password syntax. For example:

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
   IDENTIFIED BY "psmith:password";
   
   keystore altered.

   For an Oracle Key Vault keystore, you can only provide the password. No user name is allowed in the IDENTIFIED BY clause. Enclose the password in double quotation marks.

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
   IDENTIFIED BY "password";

3. Ensure that the PDB in which you want to open the keystore 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 keystore can be opened in both the CDB root and the PDB.

4. Connect to the PDB and run the ADMINISTER KEY MANAGEMENT statement to open the keystore.
   For example, for an HSM:

   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
   IDENTIFIED BY "psmith:password";
   
   keystore altered.

   You can include the FORCE KEYSTORE clause if there is a chance that the CDB root keystore has been closed, or the database is heavily loaded.

5. Confirm that the keystore is open.

   SELECT STATUS FROM V$ENCRYPTION_WALLET;

6. Repeat this procedure each time you restart the PDB.

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 Containers That Have OKV and FILE Keystores

In this example, the container list is 1 2 3 4 5 6 7 8 9 10, with only odd-numbered containers configured to use OKV keystores, and the even-numbered containers configured to use software keystores (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 when CDB$ROOT Is Not Configured to Use an External Key Manager

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

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.
   For example:

   CONNECT c##sec_admin AS SYSKM
   Enter password: password

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 in DBaaS databases (including ExaCS) 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 an external key manager (such as the Oracle Cloud Infrastructure (OCI) Key Management Service (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_keystore_credentials"];
   

   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 keystore for this operation. You must open the keystore 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_keystore_credentials refers to the credentials for either an HSM or an Oracle Key Vault external keystore. For some HSMs, specify the credentials using this format, enclosed in quotation marks and separating the components with a colon: "user_name:password", with user_name being the user who created the HSM and password being this user’s password. 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 "psmith: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.