9 Administering Isolated Mode

Administering isolated mode means managing the keystores, master encryption keys, and general Transparent Database Encryption (TDE) functionality.

9.1 Administering Keystores and TDE Master Encryption Keys in Isolated Mode

After you create a keystore and a TDE master encryption key in isolated mode, you can perform administration tasks such as rekeying or tagging encryption keys.

To change the password of an external keystore, you must use the administrative interface of the external keystore. You cannot perform this operation by using the ADMINISTER KEY MANAGEMENT statement.

9.1.1 Changing the Keystore Password in Isolated Mode

You can change the password of a software keystore when the PDB is in isolated mode.

To change the password of an external keystore, you must use the administrative interface of the external keystore. You cannot perform this operation by using the ADMINISTER KEY MANAGEMENT statement.

9.1.1.1 Changing the Password-Protected Software Keystore Password in Isolated Mode

To change the password of a password-protected software keystore in isolated mode, you must use the ADMINISTER KEY MANAGEMENT statement.

You can change this password at any time, as per the security policies, compliance guidelines, and other security requirements of your site. As part of the command to change the password, you will be forced to specify the WITH BACKUP clause, and thus forced to make a backup of the current keystore. During the password change operation, Transparent Data Encryption operations such as encryption and decryption will continue to work normally. You can change this password at any time. You may want to change this password if you think it was compromised.
  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNNECT sec_admin@pdb_name AS SYSKM
  2. Change the password for the keystore by using the following syntax:
    ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD 
    [FORCE KEYSTORE] 
    IDENTIFIED BY
    old_password SET new_password 
    [WITH BACKUP [USING 'backup_identifier']];
    

    In this specification:

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

    • old_password is the current keystore password that you want to change.

    • new_password is the new password that you set for the keystore.

    The following example creates a backup of the keystore and then changes the keystore password:

    ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD 
    IDENTIFIED BY
    old_password SET new_password 
    WITH BACKUP USING 'pwd_change';
    
    keystore altered.

    This example performs the same operation but uses the FORCE KEYSTORE clause in case the auto-login software keystore is in use or the password-protected software keystore is closed.

    ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD
    FORCE KEYSTORE 
    IDENTIFIED BY
    old_password SET new_password 
    WITH BACKUP USING 'pwd_change';
    
    keystore altered.
9.1.1.2 Changing the Password of an External Keystore in Isolated Mode

To change the password of an external keystore, you must close the external keystore and then change the password from the external keystore’s management interface.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNNECT sec_admin@pdb_name AS SYSKM
  2. Close the external keystore.
    • For example:
      ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE 
      IDENTIFIED BY "external_key_manager_password";
      
    • For an external keystore whose password is stored externally:
      ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE 
      IDENTIFIED BY EXTERNAL STORE;
  3. Update the credentials of the external store to use "new_external_key_manager_password".

    Currently, the external store contains the old credentials, which would no longer work.

    For example:

    ADMINISTER KEY MANAGEMENT
    UPDATE SECRET 'new_external_key_manager_password' 
    FOR CLIENT 'TDE_WALLET' 
    TO LOCAL AUTO_LOGIN KEYSTORE '/etc/ORACLE/WALLETS/orcl/external_store';
  4. Open the external keystore.

    For example:

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

    For an external keystore whose password is stored externally:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY EXTERNAL STORE;

9.1.2 Backing Up a Password-Protected Software Keystore in Isolated Mode

The BACKUP KEYSTORE clause of the ADMINISTER KEY MANAGEMENT statement backs up a password-protected software keystore.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Back up the keystore by using the following syntax:
    ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE 
    [USING 'backup_identifier'] 
    [FORCE KEYSTORE] 
    IDENTIFIED BY [EXTERNAL STORE | software_keystore_password] 
    [TO 'keystore_location'];
    

    In this specification:

    • USING backup_identifier is an optional string that you can provide to identify the backup. Enclose this identifier in single quotation marks (' '). This identifier is appended to the named keystore file (for example, ewallet_time-stamp_emp_key_backup.p12).

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

    • IDENTIFIED BY is required for the BACKUP KEYSTORE operation on a password-protected keystore because although the backup is simply a copy of the existing keystore, the status of the TDE master encryption key in the password-protected keystore must be set to BACKED UP and for this change the keystore password is required.

    • keystore_location is the path at which the backup keystore is stored. This setting is restricted to the PDB when the PDB lockdown profile EXTERNAL_FILE_ACCESS setting is blocked in the PDB or when the PATH_PREFIX variable was set when the PDB was created. If you do not specify the keystore_location, then the backup is created in the same directory as the original keystore. Enclose this location in single quotation marks (' ').

    The following example backs up a software keystore in the same location as the source keystore.

    ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE 
    USING 'hr.emp_keystore' 
    FORCE KEYSTORE 
    IDENTIFIED BY 
    'software_keystore_password';
    
    keystore altered.
    

    In the following version, the password for the keystore is stored externally, so the EXTERNAL STORE clause is used.

    ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE 
    USING 'hr.emp_keystore' 
    FORCE KEYSTORE 
    IDENTIFIED BY EXTERNAL STORE;

    After you run this statement, an ewallet_identifier.p12 file (for example, ewallet_time-stamp_hr.emp_keystore.p12) appears in the keystore backup location.

9.1.3 Merging Software Keystores in Isolated Mode

In isolated mode, you can merge software keystores.

9.1.3.1 Merging One Software Keystore into an Existing Software Keystore in Isolated Mode

In isolated mode, you can use the ADMINISTER KEY MANAGEMENT statement with the MERGE KEYSTORE clause to merge one software keystore into another existing software keystore.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Merge the software keystores by using the following syntax:
    ADMINISTER KEY MANAGEMENT MERGE KEYSTORE 'keystore1_location' 
    [IDENTIFIED BY software_keystore1_password] 
    INTO EXISTING KEYSTORE 'keystore2_location' 
    IDENTIFIED BY software_keystore2_password 
    [WITH BACKUP [USING 'backup_identifier]];
    

    In this specification:

    • keystore1_location is the directory location of the first keystore, which will be left unchanged after the merge. Enclose this path in single quotation marks (' ').

    • The IDENTIFIED BY clause is required for the first keystore if it is a password-protected keystore. software_keystore1_password is the password for the first keystore.

    • keystore2_location is the directory location of the second keystore into which the first keystore is to be merged. Enclose this path in single quotation marks (' ').

    • software_keystore2_password is the password for the second keystore.

The target keystore (keystore2) remains a password-protected keystore after the keystore merge operation.
9.1.3.2 Merging Two Software Keystores into a Third New Keystore in Isolated Mode

In isolated mode, you can merge two software keystores into a third new keystore, so that the two existing keystores are not changed and the new keystore contains the keys of both source keystores.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Merge the keystores by using the following syntax:
    ADMINISTER KEY MANAGEMENT MERGE KEYSTORE 'keystore1_location' 
    [IDENTIFIED BY software_keystore1_password] AND KEYSTORE 'keystore2_location' 
    [IDENTIFIED BY software_keystore2_password] 
    INTO NEW KEYSTORE 'keystore3_location' 
    IDENTIFIED BY software_keystore3_password;
    

    In this specification:

    • keystore1_location is the directory location of the first keystore, which will be left unchanged after the merge. Enclose this path in single quotation marks (' ').

    • The IDENTIFIED BY clause is required for the first keystore if it is a password-protected keystore. software_keystore1_password is the current password for the first keystore.

    • keystore2_location is the directory location of the second keystore. Enclose this path in single quotation marks (' ').

    • The IDENTIFIED BY clause is required for the second keystore if it is a password-protected keystore. software_keystore2_password is the current password for the second keystore.

    • keystore3_location specifies the directory location of the new, merged keystore. Enclose this path in single quotation marks (' '). If there is already an existing keystore at this location, the command exits with an error.

    • software_keystore3_password is the new password for the merged keystore.

    The following example merges an auto-login software keystore with a password-protected keystore to create a merged password-protected keystore at a new location:

    ADMINISTER KEY MANAGEMENT MERGE KEYSTORE '/etc/ORACLE/KEYSTORE/DB1' 
    AND KEYSTORE '/etc/ORACLE/KEYSTORE/DB2' 
    IDENTIFIED BY existing_password_for_keystore_2 
    INTO NEW KEYSTORE '/etc/ORACLE/KEYSTORE/DB3' 
    IDENTIFIED BY new_password_for_keystore_3;
    
    keystore altered.

9.1.4 Closing Keystores in Isolated Mode

You can close both software and external keystores in isolated mode, unless the system tablespace is encrypted.

9.1.4.1 Closing a Software Keystore in Isolated Mode

You can close password-protected keystores, auto-login keystores, and local auto-login software keystores in isolated mode.

In the case of an auto-login keystore, which opens automatically when it is accessed, you must first move it to a new location where it cannot be automatically opened, then you must manually close it. You must do this if you are changing your configuration from an auto-login keystore to a password-protected keystore: you change the configuration to stop using the auto-login keystore (by moving the auto-login keystore to another location where it cannot be automatically opened), and then closing the auto-login keystore.
  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Close the software keystore by using the following syntax.
    Note that the only difference between the following two ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE statements is that a password must be provided for a password-protected keystore.
    • For a password-protected software keystore:
      ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE 
      IDENTIFIED BY [EXTERNAL STORE | software_keystore_password];

      Closing a password-protected keystore disables all encryption and decryption operations. Any attempt to encrypt or decrypt data or access encrypted data results in an error.

    • For an auto-login or local auto-login software keystore:
      ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE;

      The result of this statement will not necessarily be that the keystore status will change to CLOSED, because unless you also moved the cwallet.sso file to a location that Oracle Database cannot find, then a background job or background process could automatically re-open the auto-login keystore. This can cause the status to potentially always appear to be OPEN even after the ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE statement completed successfully.

9.1.4.2 Closing an External Keystore in Isolated Mode

To close an external keystore, you must use the ADMINISTER KEY MANAGEMENT statement with the SET KEYSTORE CLOSE clause.

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.
  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Close the external keystore by using the following syntax:
    ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE 
    IDENTIFIED BY [EXTERNAL STORE | "external_key_manager_password"];
Closing a keystore disables all encryption and decryption operations. Any attempt to encrypt or decrypt data or access encrypted data results in an error.

9.1.5 Creating a User-Defined TDE Master Encryption Key in Isolated Mode

To create a user-defined TDE master encryption key, use the ADMINISTER KEY MANAGEMENT statement with the SET | CREATE [ENCRYPTION] KEY clause.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Create the user-defined TDE master encryption key by using the following syntax:
    ADMINISTER KEY MANAGEMENT SET | CREATE [ENCRYPTION] KEY
    'mkid:mk | mk' 
    [USING ALGORITHM 'algorithm'] 
    [FORCE KEYSTORE]
    IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
    [WITH BACKUP [USING 'backup_identifier']];

    In this specification:

    • SET | CREATE : Enter SET if you want to create the master and activate the TDE master encryption key now, or enter CREATE if you want to create the key for later use, without activating it yet.

    • mkid and mk:

      • mkid, the TDE master encryption key ID, is a 16–byte hex-encoded value that you can specify or have Oracle Database generate.

      • mk, the TDE master encryption key, is a hex-encoded value that you can specify or have Oracle Database generate, either 32 bytes (for the for AES256, ARIA256, and GOST256 algorithms) or 16 bytes (for the SEED128 algorithm).

      If you omit the mkid:mk|mkid clause but include the mk value, then Oracle Database generates the mkid for the mk.

      If you omit the entire mkid:mk|mkid clause, then Oracle Database generates these values for you.

    • USING ALGORITHM: Specify one of the following supported algorithms:

      • AES256

      • ARIA256

      • SEED128

      • GOST256

      If you omit the algorithm, then the default, AES256, is used.

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

    The following example includes a user-created TDE master encryption key but no TDE master encryption key ID, so that the TDE master encryption key ID is generated:

    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY 
    '3D432109DF88967A541967062A6F4E460E892318E307F017BA048707B402493C' 
    USING ALGORITHM 'GOST256'
    FORCE KEYSTORE
    IDENTIFIED BY keystore_password;

    The next example creates user-defined keys for both the master encryption ID and the TDE master encryption key. It omits the algorithm specification, so the default algorithm AES256 is used.

    ADMINISTER KEY MANAGEMENT CREATE ENCRYPTION KEY 
    '10203040506070801112131415161718:3D432109DF88967A541967062A6F4E460E892318E307F017BA048707B402493C' 
    IDENTIFIED BY keystore_password;

9.1.6 Creating a TDE Master Encryption Key for Later Use in Isolated Mode

A keystore must be open before you can create a TDE master encryption key for use later on in isolated mode.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Create the TDE master encryption key by using the following syntax:
    ADMINISTER KEY MANAGEMENT CREATE KEY 
    [USING TAG 'tag'] 
    [FORCE KEYSTORE] 
    IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
    [WITH BACKUP [USING 'backup_identifier']];
    

    In this specification:

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

    • IDENTIFIED BY is required for the BACKUP KEYSTORE operation on a password-protected keystore because although the backup is simply a copy of the existing keystore, the status of the TDE master encryption key in the password-protected keystore must be set to BACKED UP and for this change the keystore password is required.

    • keystore_location is the path at which the backup keystore is stored. This setting is restricted to the PDB when the PDB lockdown profile EXTERNAL_FILE_ACCESS setting is blocked in the PDB or when the PATH_PREFIX variable was not set when the PDB was created. If you do not specify the keystore_location, then the backup is created in the same directory as the original keystore. Enclose this location in single quotation marks (' ').

    For example:

    ADMINISTER KEY MANAGEMENT CREATE KEY 
    FORCE KEYSTORE 
    IDENTIFIED BY keystore_password
    WITH BACKUP;
  3. If necessary, activate the TDE master encryption key.
    1. Find the key ID.
      SELECT KEY_ID FROM V$ENCRYPTION_KEYS; 
      
      KEY_ID
      ----------------------------------------------------
      AWsHwVYC2U+Nv3RVphn/yAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    2. Use this key ID to activate the key.
      ADMINISTER KEY MANAGEMENT USE KEY 
      'AWsHwVYC2U+Nv3RVphn/yAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAA' 
      USING TAG 'quarter:second;description:Activate Key on standby' 
      IDENTIFIED BY password 
      WITH BACKUP;

9.1.7 Activating a TDE Master Encryption Key in Isolated Mode

To activate a TDE master encryption key in isolated mode, you must open the keystore and use ADMINISTER KEY MANAGEMENT with the USE KEY clause.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Query the KEY_ID column of the V$ENCRYPTION_KEYS view to find the key identifier.
    For example:
    SELECT KEY_ID FROM V$ENCRYPTION_KEYS; 
    
    KEY_ID
    ----------------------------------------------------
    ARaHD762tUkkvyLgPzAi6hMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    
  3. Use this key identifier to activate the TDE master encryption key by using the following syntax:
    ADMINISTER KEY MANAGEMENT USE KEY 'key_identifier_from_V$ENCRYPTION_KEYS' 
    [USING TAG 'tag'] 
    [FORCE KEYSTORE] 
    IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
    [WITH BACKUP [USING 'backup_identifier']];
    

    In this specification:

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

    For example:

    ADMINISTER KEY MANAGEMENT USE KEY 'ARaHD762tUkkvyLgPzAi6hMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
    FORCE KEYSTORE
    IDENTIFIED BY keystore_password
    WITH BACKUP;

9.1.8 Rekeying the TDE Master Encryption Key in Isolated Mode

You can use the ADMINISTER KEY MANAGEMENT statement with the SET KEY clause to rekey a TDE master encryption key.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. If you are rekeying the TDE master encryption key for a keystore that has auto login enabled, then ensure that both the auto login keystore, identified by the .sso file, and the encryption keystore, identified by the .p12 file, are present.
    You can find the location of these files by querying the WRL_PARAMETER column of the V$ENCRYPTION_WALLET view. To find the WRL_PARAMETER values for all of the database instances, query the GV$ENCRYPTION_WALLET view.
  3. Rekey the TDE master encryption key by using the following syntax:
    ADMINISTER KEY MANAGEMENT SET [ENCRYPTION] KEY 
    [FORCE KEYSTORE]
    [USING TAG 'tag_name'] 
    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 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.

      • keystore_password is the password that was created for this keystore.

    For example:

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

9.1.9 Moving a TDE Master Encryption Key into a New Keystore in Isolated Mode

In isolated mode, you can move an existing TDE master encryption key into a new keystore from an existing software password keystore.

This feature enables you to move a subset, or all, of a keystore’s keys into a new keystore. After you move the key or keys to the new keystore and then back up the old keystore, optionally you then can delete this old keystore.
  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Query the CREATION_TIME and KEY_ID columns of the V$ENCRYPTION_KEYS view to find the key identifier of the key that you want to move.
    For example:
    SELECT CREATION_TIME, KEY_ID FROM V$ENCRYPTION_KEYS; 
    
    CREATION TIME
    ----------------------------------------------------
    22-SEP-19 08.55.12.956170 PM +00:00
    
    KEY_ID
    ----------------------------------------------------
    ARaHD762tUkkvyLgPzAi6hMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
  3. Move the key into a new keystore by using the following syntax:
    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_identifier' [, 'key_identifier' ]... | ( subquery ) }]
    [WITH BACKUP [USING 'backup_identifier'] ];

    In this specification:

    • keystore_location1 is the path to the wallet directory that will store the new keystore .p12 file. By default, this directory is in $ORACLE_BASE/admin/db_unique_name/wallet.

    • keystore1_password is the password for the keystore from which the new keystore is moved.

    • FORCE temporarily opens the keystore for this operation.

    • keystore_password is the password for the keystore from which the key is moving.

    • subquery can be used to find the exact key identifier that you want.

    • backup_identifier is an optional description of the backup. Enclose backup_identifier in single quotation marks (' ').

    For example:

    ADMINISTER KEY MANAGEMENT MOVE KEYS 
    TO NEW KEYSTORE '$ORACLE_BASE/admin/orcl/wallet' 
    IDENTIFIED BY keystore_password 
    FROM FORCE KEYSTORE 
    IDENTIFIED BY keystore_password 
    WITH IDENTIFIER IN 
    (SELECT KEY_ID FROM V$ENCRYPTION_KEYS WHERE ROWNUM < 2)
    WITH BACKUP;
    After the keys are moved to the new keystore, they no longer exist in the old keystore.
  4. To delete the old keystore, go to the wallet directory and do the following:
    1. Back up the .p12 file containing the keystore that you want to delete.
    2. Manually delete the .p12 file containing the keystore.
    To find the location of the keystore, open the keystore, and then query the WRL_PARAMETER column of the V$ENCRYPTION_WALLET view.

9.1.10 Creating a Custom Attribute Tag in Isolated Mode

To create a custom attribute tag in isolated mode, you must use the SET TAG clause of the ADMINISTER KEY MANAGEMENT statement.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. If necessary, query the TAG column of the V$ENCRYPTION_KEY dynamic view to find a listing of existing tags for the TDE master encryption keys.
    When you create a new tag for a TDE master encryption key, it overwrites the existing tag for that TDE master encryption key.
  3. Create the custom attribute tag by using the following syntax:
    ADMINISTER KEY MANAGEMENT SET TAG 'tag' 
    FOR 'master_key_identifier' 
    [FORCE KEYSTORE] 
    IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
    [WITH BACKUP [USING 'backup_identifier']];
    

    In this specification:

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

    • master_key_identifier identifies the TDE master encryption key for which the tag is set. To find a list of TDE master encryption key identifiers, query the KEY_ID column of the V$ENCRYPTION_KEYS dynamic view.

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

      • keystore_password is the password that was created for this keystore.

      • backup_identifier defines the tag values. Enclose this setting in single quotation marks (' ') and separate each value with a colon.

    For example, to create a tag that uses two values, one to capture a specific session ID and the second to capture a specific terminal ID:

    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY 
    USING TAG 'sessionid=3205062574:terminal=xcvt' 
    IDENTIFIED BY keystore_password 
    WITH BACKUP;
    
    keystore altered.
    

    Both the session ID (3205062574) and terminal ID (xcvt) can derive their values by using either the SYS_CONTEXT function with the USERENV namespace, or by using the USERENV function.

9.1.11 Exporting and Importing the TDE Master Encryption Key in Isolated Mode

You can export and import the TDE master encryption key in different ways in isolated mode.

9.1.11.1 Exporting a TDE Master Encryption Key in Isolated Mode

In isolated mode, you can use the ADMINISTER KEY MANAGEMENT statement to export a TDE master encryption key.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Export the TDE master encryption keystore by using the following syntax:
    ADMINISTER KEY MANAGEMENT EXPORT [ENCRYPTION] KEYS 
    WITH SECRET "export_secret" 
    TO 'file_path' 
    [FORCE KEYSTORE]
    IDENTIFIED BY [EXTERNAL STORE | keystore_password]
    [WITH IDENTIFIER IN 'key_id1', 'key_id2', 'key_idn' | (SQL_query)];
    

    In this specification:

    • export_secret is a password that you can specify to encrypt the export the file that contains the exported keys. Enclose this secret in double quotation marks (" "), or you can omit the quotation marks if the secret has no spaces.

    • file_path is the complete path and name of the file to which the keys must be exported. Enclose this path in single quotation marks (' '). You can export to regular file systems only.

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

    • key_id1, key_id2, key_idn is a string of one or more TDE master encryption key identifiers for the TDE master encryption key being exported. Separate each key identifier with a comma and enclose each of these key identifiers in single quotation marks (' '). To find TDE master encryption key identifiers, query the KEY_ID column of the V$ENCRYPTION_KEYS dynamic view.

    • SQL_query is a query that fetches a list of the TDE master encryption key identifiers. It should return only one column that contains the TDE master encryption key identifiers. This query is executed with current user rights.

9.1.11.2 Importing a TDE Master Encryption Key in Isolated Mode

The ADMINISTER KEY MANAGEMENT statement with the IMPORT [ENCRYPTION] KEYS WITH SECRET clause can import a TDE master encryption key.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Import the TDE master encryption keystore by using the following syntax:
    ADMINISTER KEY MANAGEMENT IMPORT [ENCRYPTION] KEYS 
    WITH SECRET "import_secret"  
    FROM 'file_name'  
    [FORCE KEYSTORE]
    IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
    [WITH BACKUP [USING 'backup_identifier']];
    

    In this specification:

    • import_secret is the same password that was used to encrypt the keys during the export operation. Enclose this secret in double quotation marks (" "), or you can omit the quotation marks if the secret has no spaces.

    • file_name is the complete path and name of the file from which the keys need to be imported. 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.

9.1.12 Storing Oracle Database Secrets in Isolated Mode

Secrets are data that support internal Oracle Database features that integrate external clients such as Oracle GoldenGate into the database.

9.1.12.1 About Storing Oracle Database Secrets in a Keystore in Isolated Mode

Keystores can store secrets that support internal Oracle Database features and integrate external clients such as Oracle GoldenGate.

The secret key must be a string adhering to Oracle identifier rules. You can add, update, or delete a client secret in an existing keystore. The Oracle GoldenGate Extract process must have data encryption keys to decrypt the data that is in data files and in REDO or UNDO logs. Keys are encrypted with shared secrets when you share the keys between an Oracle database and an Oracle GoldenGate client. The software keystore stores the shared secrets.

Depending on your site's requirements, you may require automated open keystore operations even when an external keystore is configured. For this reason, the external key manager password can be stored in a software auto-login keystore, which enables the auto-login capability for the external key manager. The Oracle Database side can also store the credentials for the database to log in to an external storage server in the software keystore.

You can store Oracle Database secrets in both software keystores and external keystores:

  • Software keystores: You can store secrets in software password-based, auto-login, and local auto-login software keystores. If you want to store secrets in an auto-login (or auto-login local) keystore, then note the following:

    • If the software auto-login keystore is in the same location as its corresponding password-based software keystore, then the secrets are added automatically.

    • If the software auto-login keystore is in a different location from its corresponding password-based software keystore, then you must create the auto-login keystore again from the password-based keystore, and keep the two keystores in synchronization.

  • External keystores: You can store secrets in standard external key managers.

9.1.12.2 Storing Oracle Database Secrets in a Software Keystore in Isolated Mode

The ADMINISTER KEY MANAGEMENT ADD SECRET|UPDATE SECRET|DELETE SECRET statements can add secrets, update secrets, and delete secrets in a keystore.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Add, update, or delete a database secret in a software keystore by using the following syntax:
    • To add a secret:
      ADMINISTER KEY MANAGEMENT
      ADD SECRET 'secret' FOR CLIENT 'client_identifier' 
      [USING TAG 'tag']
      [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location 
      [WITH BACKUP [USING backup_id]] 
      | [FORCE KEYSTORE]  
      IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
      [WITH BACKUP [USING backup_id]]];
    • To update a secret:
      ADMINISTER KEY MANAGEMENT
      UPDATE SECRET 'secret' FOR CLIENT 'client_identifier' 
      [USING TAG 'tag']
      [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location 
      [WITH BACKUP [USING backup_id]] 
      | [FORCE KEYSTORE]  
      IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
      [WITH BACKUP [USING backup_id]]]; 
    • To delete a secret:
      ADMINISTER KEY MANAGEMENT
      DELETE SECRET FOR CLIENT 'client_identifier' 
      [FROM [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location 
      [FORCE KEYSTORE]
      IDENTIFIED BY [EXTERNAL STORE | keystore_password] 
      [WITH BACKUP [USING backup_id]]]; 

    The specification is as follows:

    • secret is the client secret key to be stored, updated, or deleted. To find information about existing secrets and their client identifiers, query the V$CLIENT_SECRETS dynamic view.

    • client_identifier is an alphanumeric string used to identify the secret key.

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

9.1.12.3 Example: Adding an Oracle Key Vault Password to a Software Keystore

The ADMINISTER KEY MANAGEMENT ADD SECRET statement can add an Oracle Key Vault password to a software keystore.

Example 9-1 shows how to add an Oracle Key Vault password as a secret into an existing software keystore (for example, after migrating to Oracle Key Vault, the Oracle Key Vault password can be added to the old TDE software keystore to set up an auto-open connection into Oracle Key Vault.

Example 9-1 Adding an Oracle Database Secret to a Software Keystore

ADMINISTER KEY MANAGEMENT 
ADD SECRET 'external_key_manager_password' FOR CLIENT 'OKV_PASSWORD' 
IDENTIFIED BY software_keystore_password WITH BACKUP;

Before migrating from a software keystore to Oracle Key Vault, you can upload the software keystore into the virtual wallet of that endpoint in Oracle Key Vault. After migrating, you now can delete the old TDE wallet, because its key is in Oracle Key Vault. In order to configure auto-open Oracle Key Vault without a wallet being already present, execute the following statement:

ADMINISTER KEY MANAGEMENT ADD SECRET 'external_keystore_password' 
FOR CLIENT 'OKV_PASSWORD' INTO [LOCAL] AUTO_LOGIN KEYSTORE 'WALLET_ROOT/tde';

Note that the setting TDE_CONFIGURATION='KEYSTORE_CONFIGUARTION=OKV' is for a password-protected connection into Oracle Key Vault. After the Oracle Key Vault password has been inserted into an existing or newly created wallet, change the TDE_CONFIGURATION setting to 'KEYSTORE_CONFIGURATION=OKV|FILE'.

9.1.12.4 Example: Changing an Oracle Key Vault Password Stored as a Secret in a Software Keystore

The ADMINISTER KEY MANAGEMENT UPDATE SECRET statement can change an Oracle Key Vault password that is stored as a secret in a software keystore.

Example 9-2 shows how to change an Oracle Key Vault password that is stored as a secret in a software keystore.

Example 9-2 Changing an Oracle Key Vault Password Secret to a Software Keystore

ADMINISTER KEY MANAGEMENT
UPDATE SECRET admin_password FOR CLIENT 'admin@myhost' 
USING TAG 'new_host_credentials' FORCE KEYSTORE
IDENTIFIED BY software_keytore_password;

In this version, the password for the keystore is in an external store:

DMINISTER KEY MANAGEMENT
UPDATE SECRET admin_password FOR CLIENT 'admin@myhost' 
USING TAG 'new_host_credentials' FORCE KEYSTORE
IDENTIFIED BY EXTERNAL STORE;
9.1.12.5 Example: Deleting an Oracle Key Vault Password Stored as a Secret in a Software Keystore

The ADMINISTER KEY MANAGEMENT DELETE SECRET statement can delete Oracle Key Vault passwords that are stored as secrets in a software keystore.

Example 9-3 shows how to delete an Oracle Key Vault password that is stored as a secret in the software keystore.

Example 9-3 Deleting an Oracle Key Vault Password Secret in a Software Keystore

ADMINISTER KEY MANAGEMENT 
DELETE SECRET FOR CLIENT 'OKV_PASSWORD' 
FORCE KEYSTORE
IDENTIFIED BY password WITH BACKUP;

In this version, the password for the keystore is in an external store:

ADMINISTER KEY MANAGEMENT 
DELETE SECRET FOR CLIENT 'OKV_PASSWORD'
FORCE KEYSTORE 
IDENTIFIED BY EXTERNAL STORE WITH BACKUP;
9.1.12.6 Storing Oracle Database Secrets in an External Keystore in Isolated Mode

The ADMINISTER KEY MANAGEMENT ADD SECRET|UPDATE SECRET|DELETE SECRET statements can add secrets, update secrets, and delete secrets in a keystore.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Add, update, or delete a database secret in an external keystore by using the following syntax:
    • To add a secret:
      ADMINISTER KEY MANAGEMENT
      ADD SECRET 'secret' FOR CLIENT 'client_identifier' 
      [USING TAG 'tag']
      [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location 
      [FORCE KEYSTORE]
      IDENTIFIED BY "external_key_manager_password"]
      [WITH BACKUP [USING backup_id]];
    • To update a secret:
      ADMINISTER KEY MANAGEMENT
      UPDATE SECRET 'secret' FOR CLIENT 'client_identifier' 
      [USING TAG 'tag']
       [TO [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location 
      [FORCE KEYSTORE]
      IDENTIFIED BY "external_key_manager_password"
      [WITH BACKUP [USING backup_id]]; 
    • To delete a secret:
      ADMINISTER KEY MANAGEMENT
      DELETE SECRET FOR CLIENT 'client_identifier' 
      [FROM [[LOCAL] AUTO_LOGIN] KEYSTORE keystore_location 
      [FORCE KEYSTORE]
      IDENTIFIED BY "eexternal_key_manager_password"; 

    The specification is as follows:

    • secret is the client secret key to be stored, updated, or deleted. To find information about existing secrets and their client identifiers, query the V$CLIENT_SECRETS dynamic view.

    • client_identifier is an alphanumeric string used to identify the secret key.

    • FORCE KEYSTORE temporarily opens the password-protected keystore for this operation. You must open the keystore for this 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.

9.1.12.7 Example: Adding an Oracle Database Secret to an External Keystore

The ADMINISTER KEY MANAGEMENT ADD SECRET statement can add an Oracle Database secret to an external keystore.

Example 9-4 shows how to add a password for a user to an external keystore.

Example 9-4 Adding an Oracle Database Secret to an External Keystore

ADMINISTER KEY MANAGEMENT ADD SECRET 'password' 
FOR CLIENT 'admin@myhost' USING TAG 'myhost admin credentials' 
IDENTIFIED BY "external_key_manager_password";

In this version, the keystore password is in an external store, so the EXTERNAL STORE setting is used for IDENTIFIED BY:

ADMINISTER KEY MANAGEMENT ADD SECRET 'password' 
FOR CLIENT 'admin@myhost' USING TAG 'myhost admin credentials' 
IDENTIFIED BY EXTERNAL STORE;
9.1.12.8 Example: Changing an Oracle Database Secret in an External Keystore

The ADMINISTER KEY MANAGEMENT MANAGEMENT UPDATE SECRET statement can change an Oracle Database secret in an external keystore.

Example 9-5 shows how to change a password that is stored as a secret in an external keystore.

Example 9-5 Changing an Oracle Database Secret in an External Keystore

ADMINISTER KEY MANAGEMENT MANAGEMENT UPDATE SECRET 'password2' 
FOR CLIENT 'admin@myhost' USING TAG 'New host credentials' 
IDENTIFIED BY "external_key_manager_password";

In this version, the password for the keystore is in an external store:

ADMINISTER KEY MANAGEMENT MANAGEMENT UPDATE SECRET 'password2' 
FOR CLIENT 'admin@myhost' USING TAG 'New host credentials' 
IDENTIFIED BY EXTERNAL STORE;
9.1.12.9 Example: Deleting an Oracle Database Secret in an External Keystore

The ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT statement can delete an Oracle Database secret that is in an external keystore.

Example 9-6 shows how to delete an external key manager password that is stored as a secret in the external keystore.

Example 9-6 Deleting an Oracle Database Secret in an External Keystore

ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'admin@myhost' 
IDENTIFIED BY "external_key_manager_password";

In this version, the password for the keystore is in an external store:

ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'admin@myhost' 
IDENTIFIED BY EXTERNAL STORE;

9.1.13 Storing Oracle GoldenGate Secrets in a Keystore in Isolated Mode

You can store Oracle GoldenGate secrets in Transparent Data Encryption keystores.

9.1.13.1 About Storing Oracle GoldenGate Secrets in Keystores in Isolated Mode

You can use a keystore to store secret keys for tools and external clients such as Oracle GoldenGate.

The secret key must be a string adhering to Oracle identifier rules. You can add, update, or delete a client secret in an existing keystore. This section describes how to capture Transparent Data Encryption encrypted data in the Oracle GoldenGate Extract (Extract) process using classic capture mode.

TDE support when Extract is in classic capture mode requires the exchange of the following keys:

  • TDE support for Oracle GoldenGate in the classic capture mode of the Extract process requires that an Oracle database and the Extract process share the secret to encrypt sensitive information being exchanged. The shared secret is stored securely in the Oracle database and Oracle GoldenGate domains. The shared secret is stored in the software keystore or the external keystore as the database secret.

  • The decryption key is a password known as the shared secret that is stored securely in the Oracle database and Oracle GoldenGate domains. Only a party that has possession of the shared secret can decrypt the table and redo log keys.

After you configure the shared secret, Oracle GoldenGate Extract uses the shared secret to decrypt the data. Oracle GoldenGate Extract does not handle the TDE master encryption key itself, nor is it aware of the keystore password. The TDE master encryption key and password remain within the Oracle database configuration.

Oracle GoldenGate Extract only writes the decrypted data to the Oracle GoldenGate trail file, which Oracle GoldenGate persists during transit. You can protect this file using your site's operating system standard security protocols, as well as the Oracle GoldenGate AES encryption options. Oracle GoldenGate does not write the encrypted data to a discard file (specified with the DISCARDFILE parameter). The word ENCRYPTED will be written to any discard file that is in use.

Oracle GoldenGate does require that the keystore be open when processing encrypted data. There is no performance effect of Oracle GoldenGate feature on the TDE operations.

9.1.13.2 Oracle GoldenGate Extract Classic Capture Mode TDE Requirements

Ensure that you meet the requirements for Oracle GoldenGate Extract to support Transparent Data Encryption capture.

The requirements are as follows:

  • To maintain high security standards, ensure that the Oracle GoldenGate Extract process runs as part of the Oracle user (the user that runs the Oracle database). That way, the keys are protected in memory by the same privileges as the Oracle user.

  • Run the Oracle GoldenGate Extract process on the same computer as the Oracle database installation.

9.1.13.3 Configuring Keystore Support for Oracle GoldenGate

You can configure Transparent Data Encryption keystore support for Oracle GoldenGate by using a shared secret for the keystore.

9.1.13.3.1 Step 1: Decide on a Shared Secret for the Keystore

A shared secret for a keystore is a password.

  • Decide on a shared secret that meets or exceeds Oracle Database password standards.

Do not share this password with any user other than trusted administrators who are responsible for configuring Transparent Data Encryption to work with Oracle GoldenGate Extract.

9.1.13.3.2 Step 2: Configure Oracle Database for TDE Support for Oracle GoldenGate

The DBMS_INTERNAL_CLKM PL/SQL package enables you to configure TDE support for Oracle GoldenGate.

  1. Connect to the united mode CDB root or isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT c##sec_admin AS SYSKM (or CONNECT sec_admin@pdb_name AS SYSKM)
    Enter password: password
  2. Load the Oracle Database-supplied DBMS_INTERNAL_CLKM PL/SQL package.

    For example:

    @?/app/oracle/product/20.1/rdbms/admin/prvtclkm.plb
    

    The prvtclkm.plb file also enables Oracle GoldenGate to extract encrypted data from an Oracle database.

  3. Grant the EXECUTE privilege on the DBMS_INTERNAL_CLKM PL/SQL package to the Oracle GoldenGate Extract database user.

    For example:

    GRANT EXECUTE ON DBMS_INTERNAL_CLKM TO psmith;
    

    This procedure enables the Oracle database and Oracle GoldenGate Extract to exchange information.

9.1.13.3.3 Step 3: Store the TDE GoldenGate Shared Secret in the Keystore

The ADMINISTER KEY MANAGEMENT statement can store a TDE GoldenGate shared secret in a keystore.

Before you begin this procedure, ensure that you have configured the TDE software or external keystore.
  1. Connect to the united mode CDB root or isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT c##sec_admin AS SYSKM (or CONNECT sec_admin@pdb_name AS SYSKM)
    Enter password: password
  2. Set the Oracle GoldenGate-TDE key in the keystore by using the following syntax.
    ADMINISTER KEY MANAGEMENT ADD|UPDATE|DELETE SECRET 'secret' 
    FOR CLIENT 'secret_identifier' [USING TAG 'tag'] 
    IDENTIFIED BY keystore_password [WITH BACKUP [USING 'backup_identifier']];
    

    In this specification:

    • secret is the client secret key to be stored, updated, or deleted. Enclose this setting in single quotation marks (' ').

    • secret_identifier is an alphanumeric string used to identify the secret key. secret_identifier does not have a default value. Enclose this setting in single quotation marks (' ').

    • tag is an optional, user-defined description for the secret key to be stored. tag can be used with the ADD and UPDATE operations. Enclose this setting in single quotation marks (' '). This tag appears in the SECRET_TAG column of the V$CLIENT_SECRETS view.

    • keystore_password is the password for the keystore that is configured.

    • WITH BACKUP is required in case the keystore was not backed up before the ADD, UPDATE or DELETE operation. backup_identifier is an optional user-defined description for the backup. Enclose backup_identifier in single quotation marks (' ').

    The following example adds a secret key to the keystore and creates a backup in the same directory as the keystore:

    ADMINISTER KEY MANAGEMENT ADD SECRET 'some_secret' 
    FOR CLIENT 'ORACLE_GG' USING TAG 'GoldenGate Secret' 
    IDENTIFIED BY password WITH BACKUP USING 'GG backup';
    
  3. Verify the entry that you just created.

    For example:

    SELECT CLIENT, SECRET_TAG FROM V$CLIENT_SECRETS WHERE CLIENT = 'ORACLEGG';
    
    CLIENT   SECRET_TAG
    -------- ------------------------------------------
    ORACLEGG some_secret
    
  4. Switch the log files.
    CONNECT / AS SYSDBA
    
    ALTER SYSTEM SWITCH LOGFILE;
    
9.1.13.3.4 Step 4: Set the TDE Oracle GoldenGate Shared Secret in the Extract Process

The GoldenGate Software Command Interface (GGSCI) utility sets the TDE Oracle GoldenGate shared secret in the extract process.

  1. Start the GGSCI utility.
    ggsci
    
  2. In the GGSCI utility, run the ENCRYPT PASSWORD command to encrypt the shared secret within the Oracle GoldenGate Extract parameter file.
    ENCRYPT PASSWORD shared_secret algorithm ENCRYPTKEY keyname
    

    In this specification:

    • shared_secret is the clear-text shared secret that you created when you decided on a shared secret for the keystore. This setting is case sensitive.

    • algorithm is one of the following values to specify AES encryption:

      • AES128

      • AES192

      • AES256

    • keyname is the logical name of the encryption key in the ENCKEYS lookup file. Oracle GoldenGate uses this name to look up the actual key in the ENCKEYS file.

    For example:

    ENCRYPT PASSWORD password AES256 ENCRYPTKEY mykey1
    
  3. In the Oracle GoldenGate Extract parameter file, set the DBOPTIONS parameter with the DECRYPTPASSWORD option.
    As input, supply the encrypted shared secret and the Oracle GoldenGate-generated or user-defined decryption key.
    DBOPTIONS DECRYPTPASSWORD shared_secret algorithm ENCRYPTKEY keyname
    

    In this specification:

    • shared_secret is the clear-text shared secret that you created when you decided on a shared secret for the keystore. This setting is case sensitive.

    • algorithm is one of the following values to specify AES encryption:

      • AES128

      • AES192

      • AES256

    • keyname is the logical name of the encryption key in the ENCKEYS lookup file.

      For example:

      DBOPTIONS DECRYPTPASSWORD AACAAAAAAAAAAAIALCKDZIRHOJBHOJUH AES256 ENCRYPTKEY mykey1

9.1.14 Migrating Keystores in Isolated Mode

You can perform migration and reverse migration operations between software keystores and external keystores in isolated mode.

9.1.14.1 Migrating from a Password-Protected Software Keystore to an External Keystore in Isolated Mode

In isolated mode, you can migrate from a password-protected software keystore to an external keystore.

For both the software keystore and the external keystore to open at the same time, either the software keystore must have the same password as the external keystore, or alternatively, after the migration has completed you can create an auto-login keystore for the software keystore.
  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Set the password of the external keystore so that it matches that of the software keystore.
    Some Oracle tools, such as Oracle Data Pump and Oracle Recovery Manager, require access to the old software keystore to decrypt data that was exported or backed up using the TDE master encryption key from the old software keystore.
    • To set the software keystore password so that it is the same as that of the external keystore, use the following syntax:
      ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD 
      [FORCE KEYSTORE]
      IDENTIFIED BY software_keystore_password 
      SET "external_key_manager_password" 
      WITH BACKUP [USING 'backup_identifier'];

      In this specification:

      • software_keystore_password is the password that was assigned to this keystore when it was created.

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

    • Alternatively, to create an auto-login keystore for a software keystore, use the following syntax:
      ADMINISTER KEY MANAGEMENT CREATE [LOCAL] AUTO_LOGIN KEYSTORE 
      FROM KEYSTORE 'keystore_location' 
      IDENTIFIED BY software_keystore_password;
  3. Provision Oracle Key Vault for the isolated mode PDB by following the instructions in Oracle Key Vault Administrator's Guide to install the Oracle Key Vault software onto the endpoint.
  4. Set the configuration of the keystore so that the external keystore becomes the new primary, and the password-protected software keystore becomes the secondary, as follows:
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=OKV|FILE";
  5. Migrate the external keystore by using the following syntax:
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY 
    IDENTIFIED BY "external_key_manager_password" 
    [FORCE KEYSTORE]
    MIGRATE USING software_keystore_password 
    [WITH BACKUP [USING 'backup_identifier']];
    After you complete the migration, you do not need to restart the database, nor do you need to manually re-open the external keystore.
9.1.14.2 Migrating from an External Keystore to a Password-Protected Software Keystore in Isolated Mode

In isolated mode, you can migrate from an external keystore to a password-protected software keystore.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Ensure that you have enrolled the PDB endpoint and that the Oracle Key Vault configuration is present at the $WALLET_ROOT/PDB_GUID/okv location.
    For both the software keystore and the external keystore to open at the same time, either the software keystore must have the same password as the external keystore, or alternatively, after the reverse migration has completed, you can create an auto-login keystore for the software keystore.
  3. Set the TDE_CONFIGURATION parameter as follows, so that FILE becomes the new primary keystore, and OKV becomes the secondary keystore.
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE|OKV";
  4. Now that the keystore configuration has been completed, issue the following statement to reverse migrate from the external keystore to the password-protected software keystore:
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY 
    IDENTIFIED BY software_keystore_password 
    REVERSE MIGRATE USING "external_key_manager_password" 
    [WITH BACKUP [USING 'backup_identifier']]; 
  5. Optionally, change the password of the newly migrated software keystore.
    For example:
    ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD 
    IDENTIFIED BY
    old_password SET new_password 
    WITH BACKUP USING 'pwd_change';
After you complete these steps, the migration process automatically reloads the keystore keys in memory. You do not need to restart the database, nor do you need to manually re-open the software keystore. The external keystore may still be required after reverse migration because the old keys are likely to have been used for encrypted backups or by tools such as Oracle Data Pump and Oracle Recovery Manager. You should create an auto-login keystore and put the HSM_PASSWORD client secret into it. For example:
ADMINISTER KEY MANAGEMENT ADD SECRET 'external_key_manager_password'
FOR CLIENT 'EXTERNAL_PASSWORD'
TO LOCAL AUTO_LOGIN KEYSTORE software_keystore_location
WITH BACKUP;

9.1.15 Uniting a Pluggable Database Keystore

Uniting a PDB keystore moves the TDE master encryption keys from the PDB keystore into the keystore of the CDB root. This enables the administrator of the keystore of the CDB root to manage the keys.

The client secrets are not moved. Instead, they are left behind in the keystore that the PDB used while it was configured in isolated mode. Oracle recommends that you delete client secrets from that keystore before you unite the PDB keystore. Similarly, when a PDB becomes isolated, no client secret contained in the keystore of the CDB root is moved.
  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Unite the PDB keystore, which moves the TDE master encryption keys from the PDB keystore into the keystore of the CDB root, by using the following syntax:
    ADMINISTER KEY MANAGEMENT UNITE KEYSTORE
    IDENTIFIED BY isolated_keystore_password
    WITH ROOT KEYSTORE [FORCE KEYSTORE]
    IDENTIFIED BY 
    [EXTERNAL STORE | keystore_password_of_cdb_root]
    [WITH BACKUP [USING backup_id]];

    In this specification:

    • FORCE KEYSTORE temporarily opens the password-protected keystore for this operation if an auto-login keystore is open (and in use) or if the keystore is closed.

    • united_keystore_password: Knowledge of this password does not enable the user who performs the UNITE KEYSTORE operation privileges to perform ADMINISTER KEY MANAGEMENT UNITE KEYSTORE operations on the PDB.

    When the keystore of a PDB is united with a keystore in the CDB root, all of the previously active (historical) TDE master encryption keys that were associated with the PDB are moved to the keystore of the CDB root. (If an ORA-46694: The keys are already in the root keystore error appears, see below.)
  3. Confirm that the isolated mode PDB is now a united mode PDB.
    SELECT KEYSTORE_MODE FROM V$ENCRYPTION_WALLET;

    The output should be UNITED.

The keystore no longer exists but its master encryption key is now in the keystore in the CDB root. If you later decide that you want the united mode PDB to be an isolated mode PDB again, then you can use the ADMINISTER KEY MANAGEMENT ISOLATE KEYSTORE statement.

ORA-46694 error: If a wallet is created in the in a PDB context, then it changes the keystore type of the PDB to isolated, and unless a key is set for the PDB, the wallet status will be OPEN_NO_MASTER_KEY. Uniting this type of PDB using the ADMINISTER KEY MANAGEMENT UNITE KEYSTORE statement will result in an ORA-46694: The keys are already in the root keystore error. To change the KEYSTORE_MODE to UNITED for this PDB, you must change the TDE configuration for the PDB. In the PDB, execute the following statement:

ALTER SYSTEM RESET TDE_CONFIGURATION;

9.1.16 Creating a Keystore When the PDB Is Closed

When you create a keystore in a PDB that is closed, the new keystore is empty and the PDB is converted to isolated mode.

9.1.16.1 About Creating a Keystore When the PDB Is Closed

Creating a keystore in a PDB that is closed could inadvertently cause problems in rekey operations, but the keystore creation can be reverted.

In previous releases, if you tried to create a keystore in a closed PDB, you were prevented and an ORA-65040: operation not allowed from within a pluggable database error would appear. Starting in Oracle Database release 18c, for convenience, when the keystore of the PDB is closed and if you run the ADMINISTER KEY MANAGEMENT CREATE KEYSTORE statement in the PDB, Oracle Database allows the operation.

If the closed PDB has not been configured to use encryption (that is, it has never had an ADMINISTER KEY MANAGEMENT SET KEY statement performed in it), after you execute ADMINISTER KEY MANAGEMENT CREATE KEYSTORE, resulting in an empty keystore and the configuration of the PDB being changed to isolated mode, then you can create a TDE master encryption key in this empty keystore.

If, however, the PDB was already configured to use encryption, then the PDB may be configured in united mode (and thus have its TDE master encryption key being managed in the keystore of the CDB root).

Mistakenly running an ADMINISTER KEY MANAGEMENT CREATE KEYSTORE statement on such a closed PDB will create an additional keystore (which will be empty), and will then configure the PDB to be in isolated mode. This effectively misconfigures the PDB, because the PDB is now in isolated mode (whereas it should be in united mode), yet its TDE master encryption key is still in the keystore of the CDB root. This misconfiguration can cause problems later on, if you try to rekey the TDE master encryption key by using the ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY statement . An ORA-28362: master key not found error will appear, because when encryption has already been enabled and a key has been set, Oracle Database treats the ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY statement as a rekey operation. In order to perform a rekey operation, Oracle Database must locate the currently active TDE master encryption key of the PDB. But in this misconfigured PDB, Oracle Database cannot locate the TDE master encryption key, because the PDB is now in isolated mode and the necessary key is in the keystore of the CDB root. Hence, the PDB is no longer configured to search in the keystore of the PDB, and the rekey operation fails.

To remedy the misconfiguration of the PDB, you must reconfigure the PDB to united mode and you must remove the empty keystore. (Always make a backup before removing any keystore.) When the PDB is configured back to united mode, then the currently active TDE master encryption key is once again available for rekey and other TDE master encryption key operations.

If later on you want to configure the PDB to be in isolated mode, then you can open the PDB and run the ADMINISTER KEY MANAGEMENT ISOLATE KEYSTORE statement, which isolates the PDB and moves its TDE master encryption key and previously-active (historical) keys from the keystore of the CDB root to a newly-created keystore for the isolated PDB.

9.1.16.2 Reverting a Keystore Creation Operation When a PDB Is Closed

If you have inadvertently created a keystore in a PDB (and thereby caused it to become configured in isolated mode), then you should reverse the keystore creation operation.

Use this procedure if you created a keystore in a closed PDB that already had encryption enabled (that is, it already had a TDE master encryption key).
  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Confirm the mode of the PDB by querying the KEYSTORE_MODE column of the V$ENCRYPTION_WALLET dynamic view.
  3. If the V$ENCRYPTION_WALLET output is ISOLATED, then execute the ALTER SYSTEM statement to reconfigure the PDB to united mode.
    • When pfile is in use, clear the TDE_CONFIGURATION parameter by using the following statement:
      ALTER SYSTEM RESET TDE_CONFIGURATION SCOPE=MEMORY;

      In an Oracle Real Application Clusters environment, include the SID parameter:

      ALTER SYSTEM RESET TDE_CONFIGURATION SCOPE=MEMORY SID='*';
    • When spfile is in use, clear the TDE_CONFIGURATION parameter by using this statement:
      ALTER SYSTEM RESET TDE_CONFIGURATION SCOPE=BOTH;

      In an Oracle Real Application Clusters environment, include the SID parameter:

      ALTER SYSTEM RESET TDE_CONFIGURATION SCOPE=BOTH SID='*';
  4. In the WALLET_ROOT/pdb_guid/tde directory, find and back up the ewallet.p12 keystore file that was mistakenly created.
  5. Delete the mistakenly-created empty keystore file.
At this stage, the PDB will be in united mode and the correct keystore and TDE master encryption key will be available for any future rekey operations.

9.2 Administering Transparent Data Encryption in Isolated Mode

You can perform a number of general administrative tasks with Transparent Data Encryption in isolated mode.

9.2.1 Moving PDBs from One CDB to Another in Isolated Mode

In isolated mode, you can automatically move a PDB from one CDB to another (for example, for load balancing or adding new functionality).

If the PDB has TDE-encrypted tables or tablespaces, then you can set the ONE_STEP_PLUGIN_FOR_PDB_WITH_TDE dynamic system parameter to TRUE to enable the PDB to include the TDE keys in the PDB move operation. This setting enables cloning or relocating PDBs across container databases (when the source PDB is Oracle Database release 12.2.0.1 or later). This parameter avoids you having to manually provide a keystore password when you import the TDE keys into the PDB after it has moved to a different CDB. When ONE_STEP_PLUGIN_FOR_PDB_WITH_TDE is set to TRUE, the database caches the keystore password in memory, obfuscated at the system level, and then uses it for the import operation. The default for ONE_STEP_PLUGIN_FOR_PDB_WITH_TDE is FALSE.

If you are trying to move a non-CDB or a PDB in which the SYSTEM, SYSAUX, UNDO, or TEMP tablespace is encrypted, and using the manual export or import of keys, then you must first import the keys for the non-CDB or PDB in the target database's CDB$ROOT before you create the PDB. Import of the keys are again required inside the PDB to associate the keys to the PDB.

  1. Connect to the CDB root as a common user who has been granted the SYSDBA privilege.
    For example:
    CONNECT c##sec_admin AS SYDBA
    Enter password: password
  2. Move (relocate) the PDB.

9.2.2 Unplugging and Plugging a PDB with Encrypted Data in a CDB in Isolated Mode

In isolated mode, for a PDB that has encrypted data, you can plug it into a CDB. Conversely, you can unplug this PDB from the CDB.

9.2.2.1 Unplugging a PDB That Has Encrypted Data in Isolated Mode

You can unplug a PDB (that has encrypted data) from one CDB and then optionally plug it into another CDB.

Unlike united mode, you do not need to specify the ENCRYPT clause in the ALTER PLUGGABLE DATABASE statement. The database that is unplugged contains data files and other associated files. Because each PDB can have its own unique keystore, you do not need to export the TDE master encryption key of the PDB that you want to unplug. You can check if a PDB has already been unplugged by querying the STATUS column of the DBA_PDBS data dictionary view.
  • Unplug the isolated mode PDB as you normally unplug PDBs.
    For example:
    ALTER PLUGGABLE DATABASE pdb1
      UNPLUG INTO '/oracle/data/pdb1.xml';
9.2.2.2 Plugging a PDB That Has Encrypted Data into a CDB in Isolated Mode

After you plug a PDB that has encrypted data into a CDB, you can set the encryption key in the PDB.

Unlike united mode, you do not need to specify the DECRYPT clause in the CREATE PLUGGABLE DATABASE statement. When you plug an unplugged PDB into another CDB, the key version is set to 0 because this operation invalidates the history of the previous keys. You can check the key version by querying the KEY_VERSION column of the V$ENCRYPTED_TABLESPACES dynamic view. Similarly, if a control file is lost and recreated, then the previous history of the keys is reset to 0. You can check if a PDB has already been plugged in by querying the STATUS column of the DBA_PDBS data dictionary view.
  1. Create the PDB by plugging the unplugged PDB into the CDB.

    • For example, if you had exported the PDB data into a metadata XML file:

      CREATE PLUGGABLE DATABASE CDB1_PDB2 
      USING '/tmp/cdb1_pdb2.xml' 
      NOCOPY KEYSTORE 
      IDENTIFIED BY password;
    • If you had exported the PDB into an archive file:

      CREATE PLUGGABLE DATABASE CDB1_PDB2 
      USING '/tmp/cdb1_pdb2.pdb';

    During the open operation of the PDB after the plug operation, Oracle Database determines if the PDB has encrypted data. If so, it opens the PDB in the RESTRICTED mode.

    You can find if the source database has encrypted data or a TDE master encryption key set in the keystore by querying the V$ENCRYPTION_KEYS dynamic view.

  2. Open the PDB.

    For example:

    ALTER PLUGGABLE DATABASE CDB1_PDB2 OPEN;
  3. Open the keystore in the CDB root.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY password;

    Optionally, open the keystore in the PDB.

  4. In the PDB, open the keystore and set the TDE master encryption key for the PDB.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEY 
    IDENTIFIED BY keystore_password 
    WITH BACKUP USING 'emp_key_backup';
9.2.2.3 Unplugging a PDB That Has Master Encryption Keys Stored in an External Keystore in Isolated Mode

You can unplug a PDB from one CDB that has been configured with an external keystore and then plug it into another CDB also configured with an external keystore.

  1. Unplug the PDB.
    You can check if a PDB has already been unplugged by querying the STATUS column of the DBA_PDBS data dictionary view.
  2. Move the master encryption keys of the unplugged PDB from the hardware that was used at the source CDB to the hardware that is in use at the destination CDB.

    Refer to the documentation for the external keystore for information about moving master keys between external keystores.

9.2.2.4 Plugging a PDB That Has Master Keys Stored in an External Keystore in Isolated Mode

The ADMINISTER KEY MANAGEMENT statement can import an external keystore master encryption key to a PDB that has been moved to another CDB.

  1. Plug the unplugged isolated mode PDB into the destination CDB that has been configured with the external keystore.
    You can check if a PDB has already been plugged in by querying the STATUS column of the DBA_PDBS data dictionary view.
    After the plug-in operation, the PDB that has been plugged in will be in restricted mode.
  2. Ensure that the master keys from the external keystore that has been configured with the source CDB are available in the external keystore of the destination CDB.
  3. Connect to the plugged PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  4. Open the keystore of the plugged PDB.

    For example, for a PDB called PDB1:

    ALTER SESSION SET CONTAINER = PDB1;
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
    IDENTIFIED BY "external_key_manager_password";
  5. Import the external keystore master encryption key into the PDB.
    ADMINISTER KEY MANAGEMENT IMPORT ENCRYPTION KEYS 
    WITH SECRET "external_keystore" FROM 'external_keystore' 
    IDENTIFIED BY "external_key_manager_password"; 
  6. Close and re-open the PDB.
    ALTER PLUGGABLE DATABASE PDB1 CLOSE;
    ALTER PLUGGABLE DATABASE PDB1 OPEN;

9.2.3 Cloning a PDB with Encrypted Data in a CDB in Isolated Mode

The CREATE PLUGGABLE DATABASE statement with the KEYSTORE IDENTIFIED BY clause can clone a PDB that has encrypted data.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Ensure that the software keystore of the PDB that you plan to clone is open.

    You can query the STATUS column of the V$ENCRYPTION_WALLET view to find if the software keystore is open.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN FORCE KEYSTORE IDENTIFIED BY keystore_password;
  3. Clone the PDB.

    For example:

    CREATE PLUGGABLE DATABASE cdb1_pdb3 FROM cdb1_pdb1 
    FILE_NAME_CONVERT=('cdb1_pdb1', 'pdb3/cdb1_pdb3') KEYSTORE 
    IDENTIFIED BY keystore_password;

    Replace keystore_password with the password of the keystore of the CDB where the cdb1_pdb3 clone is created.

    After you create the cloned PDB, encrypted data is still accessible by the clone using the master encryption key of the original PDB. After a PDB is cloned, there may be user data in the encrypted tablespaces. This encrypted data is still accessible because the master encryption key of the source PDB is copied over to the destination PDB. Because the clone is a copy of the source PDB but will eventually follow its own course and have its own data and security policies, you should rekey the master encryption key of the cloned PDB.
  4. Rekey the master encryption key of the cloned PDB.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEY 
    IDENTIFIED BY keystore_password 
    WITH BACKUP USING 'emp_key_backup';
    Before you rekey the master encryption key of the cloned PDB, the clone can still use master encryption keys that belong to the original PDB. However, these master encryption keys do not appear in the cloned PDB V$ dynamic views. Rekeying the master encryption key ensures that the cloned PDB uses its own unique keys, which will be viewable in the V$ views.

9.2.4 Remotely Cloning an Encrypted PDB in Isolated Mode

The CREATE PLUGGABLE DATABASE statement with the KEYSTORE IDENTIFIED BY clause can remotely clone a PDB that has encrypted data.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Query the STATUS column of the V$ENCRYPTION_WALLET view to ensure that the software keystore of the PDB that you plan to clone is open.
  3. Create a database link for the PDB that you want to clone remotely.
    Use the CREATE DATABASE LINK SQL statement to create the database link. You must create the database link by following the database link prerequisites that are required for cloning a remote PDB.
  4. Use the CREATE PLUGGABLE DATABASE statement with the KEYSTORE IDENTIFIED BY clause to perform the clone of the PDB.

    For example:

    CREATE PLUGGABLE DATABASE target_pdb
    FROM source_pdb@clone_link KEYSTORE
    IDENTIFIED BY keystore_password;

    The keystore_password is the password of a new software keystore that will be created in WALLET_ROOT/target_pdb_guid/tde for the incoming PDB.

    After you create the cloned PDB, encrypted data is still accessible because the master encryption key of the source PDB is copied over to the destination PDB. Because it will eventually follow its own course and have its own data and security policies, you should rekey the master encryption key of the cloned PDB.
  5. Rekey the master encryption key of the remotely cloned PDB.

    Execute the following SQL statement to create an administer key management command with a TAG:

    SELECT ' ADMINISTER KEY MANAGEMENT SET KEY 
    USING TAG '''||SYS_CONTEXT('USERENV', 'CON_NAME')||' '||TO_CHAR (SYSDATE, 'YYYY-MM-DD HH24:MI:SS')||''' 
    IDENTIFIED BY KEYSTORE_PASSWORD WITH BACKUP;' 
    AS "SET KEY COMMAND" FROM DUAL;
    ADMINISTER KEY MANAGEMENT SET KEY USING TAG 'PDB_NAME DATE TIME' 
    IDENTIFIED BY KEYSTORE_PASSWORD WITH BACKUP;
    Before you rekey the master encryption key of the cloned PDB, the clone can still use master encryption keys that belong to the original PDB. However, these master encryption keys do not appear in the cloned PDB V$ dynamic views. Rekeying the master encryption key ensures that the cloned PDB uses its own unique keys, which will be viewable in the V$ views.

9.2.5 Relocating an Encrypted PDB in Isolated Mode

The CREATE PLUGGABLE DATABASE statement with the KEYSTORE IDENTIFIED BY clause can relocate across CDBs a cloned PDB that has encrypted data.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Query the STATUS column of the V$ENCRYPTION_WALLET view to ensure that the software keystore of the PDB that you want to relocate is open.
  3. Create a database link for the PDB that you want to relocate.
    Use the CREATE DATABASE LINK SQL statement to create the database link. You must create the database link by following the database link prerequisites that are required for relocating a remote PDB or a non-CDB.
  4. Use the CREATE PLUGGABLE DATABASE statement with the KEYSTORE IDENTIFIED BY clause to relocate the PDB.

    For example:

    CREATE PLUGGABLE DATABASE target_pdb_name 
    FROM src_pdb_name@dblink RELOCATE  
    KEYSTORE IDENTIFIED BY keystore_password;

    Replace keystore_password with the password of the keystore of the CDB where the cdb1_pdb3 clone is created.

    After you create the cloned PDB, encrypted data is still accessible by the clone using the master encryption key of the original PDB. After a PDB is cloned, there may be user data in the encrypted tablespaces. This encrypted data is still accessible because the master encryption key of the source PDB is copied over to the destination PDB. Because the clone is a copy of the source PDB but will eventually follow its own course and have its own data and security policies, you should rekey the master encrytion key of the cloned PDB.
  5. Use the ALTER PLUGGABLE DATABASE statement to perform the relocation operation.
    For example:
    ALTER PLUGGABLE DATABASE cdb1_pdb3
    OPEN RELOCATE TO 'need instance name example';
  6. Rekey the master encryption key of the remotely cloned PDB.

    For example:

    ADMINISTER KEY MANAGEMENT SET KEY 
    FORCE KEYSTORE
    IDENTIFIED BY keystore_password 
    WITH BACKUP USING 'emp_key_backup';

    In this example, FORCE KEYSTORE is included because the keystore must be open during the rekey operation.

    Before you rekey the master encryption key of the cloned PDB, the clone can still use master encryption keys that belong to the original PDB. However, these master encryption keys do not appear in the cloned PDB V$ dynamic views. Rekeying the master encryption key ensures that the cloned PDB uses its own unique keys, which will be viewable in the V$ views.

9.2.6 How Keystore Open and Close Operations Work in Isolated Mode

You should be aware of how keystore open and close operations work in isolated mode.

For each PDB in isolated mode, you must explicitly open the password-protected software keystore or external keystore in the PDB to enable the Transparent Data Encryption operations to proceed. (Auto-login and local auto-login software keystores open automatically.) Closing a keystore on a PDB blocks all of the Transparent Data Encryption operations on that PDB.

The open and close keystore operations in a PDB depend on the open and close status of the keystore in the PDB.

Note the following:

  • You can create a separate keystore password for each PDB in the multitenant environment.

  • Before you can manually open a password-protected software or an external keystore in an individual PDB, you must open the keystore in the CDB root.

  • If an auto-login keystore is in use, or if the keystore is closed, then include the FORCE KEYSTORE clause in the ADMINISTER KEY MANAGEMENT statement when you open the keystore.

  • If the keystore is a password-protected software keystore that uses an external store for passwords, then replace the password in the IDENTIFIED BY clause with EXTERNAL STORE.

  • Before you can set a TDE master encryption key in an individual PDB, you must set the key in the CDB root. Oracle highly recommends that you include the USING TAG clause when you set keys in PDBs. For example:

    SELECT ' ADMINISTER KEY MANAGEMENT SET KEY 
    USING TAG '''||SYS_CONTEXT('USERENV', 'CON_NAME')||' '||TO_CHAR (SYSDATE, 'YYYY-MM-DD HH24:MI:SS')||''' 
    FORCE KEYSTORE IDENTIFIED BY EXTERNAL STORE 
    WITH BACKUP CONTAINER = CURRENT;' AS "SET KEY COMMAND" FROM DUAL;

    Including the USING TAG clause enables you to quickly and easily identify the keys that belong to a certain PDB, and when they were created.

  • Auto-login and local auto-login software keystores open automatically. You do not need to manually open these from the root first, or from the PDB.

  • If there is any PDB configured in isolated mode that has its keystore open, then an attempt to close the keystore in the CDB root would fail with an ORA-46692 cannot close wallet error. Use the FORCE CLOSE clause in the ADMINISTER KEY MANAGEMENT statement to override this behavior.

  • If you perform an ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN statement in the CDB root and set the CONTAINER clause to ALL, then the keystore will only be opened in each open PDB that is configured in united mode. Keystores for any PDBs that are configured in isolated mode are not opened.

9.2.7 Exporting and Importing Master Encryption Keys for a PDB in Isolated Mode

In isolated mode, the EXPORT and IMPORT clauses of ADMINISTER KEY MANAGEMENT EXPORT can export or import master encryption keys for a PDB.

9.2.7.1 About Exporting and Importing Master Encryption Keys for a PDB in Isolated Mode

In isolated mode, you can export and import master encryption keys from the CDB root.

You can export and import all of the master encryption keys that belong to the PDB by exporting and importing the master encryption keys from within a PDB. Export and import operations of master encryption keys in a PDB supports the PDB unplug and plug operations. During a PDB unplug and plug operations, all the master encryption keys that belong to a PDB, as well as the metadata, are involved. Therefore, the WITH IDENTIFIER clause of the ADMINISTER KEY MANAGEMENT EXPORT statement is not allowed when you export keys from within a PDB. The WITH IDENTIFIER clause is only permitted in the CDB root.

You should include the FORCE KEYSTORE clause if the CDB root has an auto-login keystore or if the keystore is closed. If the keystore has been configured to use an external store for the password, then use the IDENTIFIED BY EXTERNAL STORE clause. For example, to perform an export operation for this scenario:

ADMINISTER KEY MANAGEMENT EXPORT KEYS 
WITH SECRET "my_secret"
TO '/etc/TDE/export.exp'
FORCE KEYSTORE 
IDENTIFIED BY EXTERNAL STORE;

This ADMINISTER KEY MANAGEMENT EXPORT operation exports not only the keys but creates metadata that is necessary for PDB environments (as well as for cloning operations).

Inside a PDB, the export operation of master encryption keys exports the keys that were created or activated by a PDB with the same GUID as the PDB where the keys are being exported. Essentially, all of the keys that belong to a PDB where the export is being performed will be exported.

The importing of master encryption keys from an export file within a PDB takes place only if the master encryption key was exported from another PDB with the same GUID. To support the plug-in of a non-CDB as PDB into a CDB, you must have already exported the TDE master encryption keys from the non-CDB and imported them into the PDB without the WITH IDENTIFIER clause. Because the PDB-specific details, such as the PDB name and database ID, can change from one CDB to the next, the PDB-specific information is modified during the import to reflect the updated PDB information.

Note:

Within a PDB, you can only export the keys of a PDB as a whole. The ability to export them selectively based on a query or an identifier is restricted to the root.

9.2.7.2 Exporting or Importing a Master Encryption Key for a PDB in Isolated Mode

In isolated mode, the ADMINISTER KEY MANAGEMENT statement can export or import a master encryption key for a PDB.

  1. Connect to the isolated mode PDB as a user who has been granted the ADMINISTER KEY MANAGEMENT or SYSKM privilege.
    For example:
    CONNECT sec_admin@pdb_name AS SYSKM
  2. Perform the export or import operation.
    For example:
    ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS 
    WITH SECRET "hr_secret" TO '/tmp/export.p12' 
    FORCE KEYSTORE 
    IDENTIFIED BY password;

    Ensure that you include the FORCE KEYSTORE clause because the keystore must be open for this operation.

9.2.7.3 Example: Exporting a Master Encryption Key from a PDB in Isolated Mode

The ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS statement can export master encryption keys for a PDB.

Example 9-7 shows how to export a master encryption key from the PDB hrpdb. In this example, the FORCE KEYSTORE clause is included in case the auto-login keystore is in use, or if the keystore is closed.

Example 9-7 Exporting a Master Encryption Key from a PDB

ADMINISTER KEY MANAGEMENT EXPORT ENCRYPTION KEYS 
WITH SECRET "my_secret" TO '/tmp/export.p12' 
FORCE KEYSTORE 
IDENTIFIED BY password;
9.2.7.4 Example: Importing a Master Encryption Key into a PDB in Isolated Mode

The ADMINISTER KEY MANAGEMENT IMPORT ENCRYPTION KEYS statement can import a master encryption key into a PDB.

Example 9-8 shows how to import a master encryption key into the PDB hrpdb.

Example 9-8 Importing a Master Encryption Key into a PDB

ADMINISTER KEY MANAGEMENT IMPORT ENCRYPTION KEYS 
WITH SECRET "my_secret" 
FROM '/tmp/export.p12' 
FORCE KEYSTORE 
IDENTIFIED BY password 
WITH BACKUP;