An unplug-plug upgrade of an encrypted PDB requires the keystore password of the source and target CDB, and you can do it with AutoUpgrade.

How To

The pluggable database PDB1 is encrypted and is plugged into CDB1, which is Oracle Database 12.2. I want to upgrade the PDB to Oracle Database 19c by plugging it into CDB2.

1. Ensure that AutoUpgrade is version 22.2 or higher:

   $ java -jar autoupgrade.jar -version
   

2. Create your AutoUpgrade config file and set global.keystore as specified in a previous blog post:

   global.autoupg_log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade
   global.keystore=/u01/app/oracle/admin/autoupgrade/keystore
   
   upg1.log_dir=/u01/app/oracle/cfgtoollogs/autoupgrade/PDB1
   upg1.source_home=/u01/app/oracle/product/12.2.0.1
   upg1.target_home=/u01/app/oracle/product/19
   upg1.sid=CDB1
   upg1.target_cdb=CDB2
   upg1.pdbs=PDB1
   

3. Analyze:

   $ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze
   

4. The summary report warns me that TDE keystore passwords are needed:

   [Stage Name]    PRECHECKS
   [Status]        FAILURE
   [Start Time]    2022-03-29 07:58:52
   [Duration]       
   [Log Directory] /u01/app/oracle/cfgtoollogs/autoupgrade/PDB1/CDB1/100/prechecks
   [Detail]        /u01/app/oracle/cfgtoollogs/autoupgrade/PDB1/CDB1/100/prechecks/cdb1_preupgrade.log
   		Check failed for PDB1, manual intervention needed for the below checks
   		[TDE_PASSWORDS_REQUIRED]
   

   There are more details in the preupgrade log file:

   ==============
   BEFORE UPGRADE
   ==============
   
   	REQUIRED ACTIONS
   	================
   		1.  Perform the specified action ...
   		ORACLE_SID                      Action Required
   		------------------------------  ------------------------
   		CDB1                            Add TDE password
   		CDB2                            Add TDE password
   

5. Add the TDE keystore passwords into the AutoUpgrade keystore:

   $ java -jar autoupgrade.jar -config PDB1.cfg -load_password
   
   TDE> add CDB1
   Enter your secret/Password:    
   Re-enter your secret/Password: 
   TDE> add CDB2
   Enter your secret/Password:    
   Re-enter your secret/Password: 
   

6. Save the passwords into the AutoUpgrade keystore. I choose to create an auto-login keystore:

   TDE> save
   Convert the keystore to auto-login [YES|NO] ? YES
   TDE> exit
   

7. Re-analyze the PDB:

   $ java -jar autoupgrade.jar -config PDB1.cfg -mode analyze
   

8. If AutoUpgrade does not report any other problems, start the unplug-plug upgrade. Since I chose to create an AutoUpgrade auto-login keystore, I don’t have to provide the password when AutoUpgrade starts:

   $ java -jar autoupgrade.jar -config PDB1.cfg -mode deploy
   

9. That’s it!

What Happens

• When AutoUpgrade needs to unplug the encrypted PDB into a manifest file, the source CDB will need the TDE keystore password. AutoUpgrade can get it from its keystore. This is the IDENTIFIED BY clause of the ALTER PLUGGABLE DATABASE ... UNPLUG INTO statement.
• The encryption keys of the PDB go into the manifest file. The database doesn’t want to write the encryption keys in clear text in the manifest file and asks for a passphrase that can encrypt the encryption keys. AutoUpgrade generates a passphrase and stores the passphrase in the AutoUpgrade keystore. This is the ENCRYPT USING clause of the ALTER PLUGGABLE DATABASE ... UNPLUG INTO statement.
• When the PDB plugs into the target CDB, the target CDB will need the TDE keystore password. This is the IDENTIFIED BY clause of the CREATE PLUGGABLE DATABASE ... USING statement.
• The database must get the encryption keys of the PDB from the manifest files. The encryption keys are encrypted using a passphrase. The database asks AutoUpgrade about the passphrase which is stored in the AutoUpgrade keystore. This is the DECRYPT USING clause of the CREATE PLUGGABLE DATABASE ... USING statement.

Fallback

AutoUpgrade fallback functionality also works on an encrypted PDB. When it comes to unplug-plug upgrades and fallback capability, it is a requirement that the data files were copied as part of the upgrade process.

In the above example, a fallback using AutoUpgrade would not be possible. Since I did not specify a target_pdb_copy_option the data files were re-used. Other means of falling back to the original state is needed.

Had I specified a target_pdb_copy_option in my config file, a fallback would be possible. In the below example, I am specifying a copy option. file_name_convert=none means that the data files are copied and new OMF names are generated:

upg1.target_pdb_copy_option=file_name_convert=NONE

In this case, I can revert the unplug-plug upgrade and return to the original state using AutoUpgrade. 103 is the job id of the upgrade:

$ java -jar autoupgrade.jar -config PDB1.cfg -restore -jobs 103

Isolated Keystore Mode

In CDBs the default way of storing TDE encryption keys is in a united keystore. The CDB has one keystore and all PDBs store their encryption keys in that one keystore.

With Oracle Database 19.14 a new option became possible: isolated keystore. The CDB still has a keystore that PDBs can use. But you can also configure each individual PDB to use its own keystore.

Currently, AutoUpgrade does not support isolated keystore mode. But we are working on it.

Other Blog Posts in This Series

• AutoUpgrade and Transparent Data Encryption (TDE)
• Upgrading an Encrypted Non-CDB or CDB
• Upgrading an Encrypted Non-CDB and Converting To PDB
• Upgrading an Encrypted PDB
• Future-proof Your Encrypted Database During Upgrade
• AutoUpgrade and Secure External Password Store Enables Complete Automation