Provisioning a TDE-enabled vPDB

Overview

Refer to the Transparent Data Encryption and Delphix article for an overview of TDE and the Continuous Data implementation.

Provisioning a TDE-enabled Virtual Pluggable Database (vPDB) to a TDE-enabled target container requires specifying a few TDE provisioning parameters using the GUI or CLI, in addition to the vPDB parameters (such as the vPDB name and target container) and the snapshot to provision from. A TDE-enabled vPDB can be provisioned to either a Linked CDB or a vCDB. It is important to note that the Continuous Data Engine does not support provisioning a TDE-enabled vPDB from a source snapshot of a dSource or virtual database that is not encrypted at the time of linking.

Provisioning parameters for a TDE-enabled vPDB

To initiate the provision, Continuous Data needs the following pieces of information, all of which can be specified in the GUI or CLI. The seven parameters are listed below with some correlated specifics.

1. Parent database TDE KeyStore location

Description: The path to a KeyStore on the target host that contains the keys used to encrypt the source database data files.
- Required.
CLI parameter: source.parentTdeKeystorePath
Notes
- The KeyStore must be accessible on the target host(s) in the specified path.
- The wallet ewallet.p12 must exist in the specified path and must be readable by the Oracle user. This is normally a copy of the source database wallet.
- If the parent database TDE KeyStore has moved to a different location on the target host after provisioning the vPDB, this path must be updated via the GUI or CLI, as specified in the Updating the Parent Database TDE KeyStore Location section, otherwise a subsequent refresh operation on that vPDB will fail.
- If the master encryption keys of the source database have changed after the vPDB has been provisioned, you must ensure that a copy of the new encryption keys are present in the parent database TDE KeyStore location, usually by copying the updated parent database TDE KeyStore wallet from the source database to the parent database TDE KeyStore location on the target host.

Warning

Parent Database TDE KeyStore may be located on local storage, NFS or ACFS, but cannot be located on an ASM filesystem.

2. Parent database TDE KeyStore password

Description: Password for the parent database TDE KeyStore.
- Required.
CLI parameter: source.parentTdeKeystorePassword
Notes
- This parameter must be updated if the password is changed.

3. TDE secret for exported keys

Description: Secret for the exported keys.
- Required.
CLI parameter: source.tdeExportedKeyFileSecret
Notes
- Oracle requires a password to be set when exporting keys to a keyfile from a KeyStore. The secret is an alphanumeric string that protects the keys in the file.
- This parameter represents a new user-specified secret that is used by Continuous Data when exporting keys, and does not need to match any existing KeyStore password.
- Once a vPDB is provisioned using this secret, it cannot be changed for the lifetime of the vPDB.
- This secret is used by Continuous Data during provisioning and subsequent vPDB operations that require exporting the keys to a keyfile.

Warning

Make sure the TDE Secret for Exported Keys is stored in a secure location for your records. It is only known to you. In the rare event that keys need to be manually extracted from an exported keyfile, this password will be required. Delphix Support cannot assist with manually exporting keys without this password, therefore it should be known or recorded within your organization.

4. Target KeyStore password

Description: Password for the target Linked CDB or existing vCDB KeyStore.
- Required for linked CDB or existing vCDB targets.
- Not applicable to new vCDB targets.
CLI parameter: sourceconfig.tdeKeystorePassword
Notes
- This parameter must be updated via the GUI or CLI in the Environments page, as specified in the Adding or Editing the Target KeyStore Password section.
- This is required when provisioning to an existing Linked CDB or existing vCDB, and must match the password used to open the Linked CDB or existing vCDB KeyStore.

5. TDE KeyStore root

Description: Path to a directory on the target host under which all Continuous Data related TDE artifacts will be created.
- Required for cluster targets.
- Optional for single instance targets.
CLI parameters: host.oracleParameters.tdeKeystoresRootPath
Notes
- This includes KeyStores used by the auxiliary CDB during provisioning and the artifact directories for TDE-enabled vPDBs.
- This is an arbitrary path, which does not need to be referenced by sqlnet.ora or wallet_root.
- When provisioning to a single instance target, this will default to <toolkit path>/tde. When provisioning to a cluster target, this path must be on shared storage and available to all cluster hosts.
- The Environment User must have permission to write to this path.

6. Target vCDB TDE KeyStore location

Description: Path of the location on the target host at which Continuous Data will create the KeyStore during new vCDB provisions.
- Required for new vCDB targets.
- Not applicable to linked CDB or existing vCDB targets.
CLI parameters: source.targetVcdbTdeKeystorePath
Notes
- This path refers to a location on the target host.
- This path must either not exist or can be an existing empty directory.
- The Environment User must have permission to write to this location.
- For Oracle 12.2, the path must match what is specified by sqlnet.ora. For higher versions, Continuous Data will set the wallet_root parameter to the provided location.
- This parameter must be updated if the KeyStore location is changed or else future Continuous Data operations may fail.

7. Target vCDB TDE KeyStore password

Description: Password for the new vCDB KeyStore.
- Required for new vCDB targets.
- Not applicable to linked CDB or existing vCDB targets.
CLI parameters: virtualCdb.sourceConfig.tdeKeystorePassword
Notes
- This password is created during provisioning. It does not need to match any existing KeyStore password.
- If this password is changed, it must be updated via the GUI or CLI in the Environments page, as specified in the Adding or Editing the Target KeyStore Password section.

Prerequisites for Provisioning a TDE-enabled vPDB to a Linked CDB

The same prerequisites that apply for provisioning a regular vPDB to a Linked CDB, also apply to a TDE-enabled vPDB. Specifically, there must be a target environment that has an Oracle installation compatible with the Oracle installation of the source CDB and the source PDB. The following database requirements are needed to provision the vPDB to a linked CDB. For more information, see Requirements for Oracle Hosts and Databases.

Recommend autodiscovery so that the linked CDB can be found. Otherwise, the linked CDB must be manually discovered before provisioning.
Linked CDB must be running
Linked CDB must be in ARCHIVELOG mode
Linked CDB should be using Block Change Tracking (BCT)
LogSync must be enabled for the Linked CDB.

The additional prerequisites for provisioning a TDE-enabled vPDB are:

The target KeyStore password must be entered on the Environments page when provisioning to a target linked CDB. Follow the procedure listed in the Adding or Editing the Target KeyStore Password section.
A copy of the source database wallet must be made available on the target host(s) and that path must be specified as the parent database TDE KeyStore location. This can be achieved either through copying the entire KeyStore (ewallet.p12) file from the source host, or by creating a new KeyStore and importing the required keys from the source KeyStore.
The parent database TDE KeyStore location on the target host(s) must be accessible to the Environment User.
If the target CDB is a new vCDB, the Environment User must have permission to write to the “Target vCDB TDE KeyStore Location”.

Compatibility requirements for provisioning a TDE-enabled vPDB to a Linked CDB

For provisioning a vPDB into a Linked CDB, the source CDB and the target CDB must meet the following compatibility requirements:

The value of the COMPATIBLE parameter in the source CDB must be less than or equal to the value of the COMPATIBLE parameter in the target CDB.
They must have the same endianness.
They must have compatible character sets and national character sets.
If TDE is configured using sqlnet.ora, the encryption wallet location should be configured on the target host in the standard location as described in the Oracle documentation. If the TNS_ADMIN environment variable is being used to specify the directory location where the sqlnet.ora is located, TNS_ADMIN should point to the default location as indicated above.

Setting Up Auxiliary CDB Parameters

During a TDE-enabled vPDB provisioning into a Linked CDB or a vCDB, the Continuous Data Engine creates a temporary CDB instance (or Auxiliary CDB) on the target environment to recover the vPDB to a consistent state. This temporary CDB will be automatically deleted (in case of provisioning to a linked CDB or to an existing vCDB) or converted to a vCDB (in case of provisioning to a new vCDB) after the vPDB is provisioned successfully. By default, this temporary CDB is configured to have the same init parameters as the source database. To manage the configuration of the temporary CDB init parameters, you must set up Repository Templates for Oracle Databases prior to provisioning.

For more details on additional TDE-related processing that is performed in the Auxiliary CDB, see the A closer look at TDE provisioning section.

Updating the Parent Database TDE KeyStore Location

The Parent Database TDE KeyStore Location is specified in the GUI in the Configuration tab under the vPDB in the Source tab.

Login to the Delphix Management application.
Click Manage > Datasets.
Click on the vPDB.
Click the Configuration tab.
Click the Source tab.
Next to Source Database, click on the pencil icon to update the Parent Database TDE KeyStore Location.
Click on the checkmark to save your changes.

Adding or Editing the Target KeyStore Password

The target KeyStore password is specified in the GUI in the Databases tab under Environments:

Login to the Delphix Management application.
Click Manage > Environments.
Click the Databases tab for your Environment.
Next to TDE KeyStore Password click on the pencil icon to set or update the password.

Adding or Editing the TDE KeyStores Root

The TDE KeyStores root directory path is specified in the GUI in the Details tab under Environments:

Login to the Delphix Management application.
Click Manage → Environments.
Click the Details tab for your target environment.

Next to Attributes click on the pencil icon to set or update attributes, including the KeyStores root.

Provisioning a TDE-enabled vPDB

When provisioning a TDE-enabled vPDB into a Linked CDB or an existing vCDB:

Continuous Data requires that the Linked CDB or vCDB already be present on the target host with all the encryption keys set up correctly.

When provisioning a TDE-enabled vPDB into a new vCDB:

Continuous Data will provision a vCDB from the source CDB to host the vPDB you are about to create. The newly-created vCDB will be configured with TDE enabled.
There is no need to set up a repository template, as this provision workflow allows a user to directly specify a VDB configuration template, or set individual database parameters.

Procedure

If you’re provisioning to a Linked CDB for the first time, add the Target KeyStore Password following the steps listed in the Adding or Editing the Target KeyStore Password section.

To validate that the parent database TDE KeyStore password is correct, refer to the Validating the KeyStore Password section.

Ensure that the parent database TDE KeyStore location on the target host contains a KeyStore that includes the encryption keys from the source database and is readable by the Oracle User used for provisioning.
If provisioning to a cluster target, ensure that the KeyStores root directory path is set correctly following the steps listed in the Adding or Editing the TDE KeyStores Root section.
In the Datasets panel, select an Oracle TDE-enabled PDB dSource or a previously provisioned TDE-enabled vPDB.
From the Timeflow tab, select a snapshot or point in time to provision from.
Once the Provision wizard is open, you can either provision with a:
1. Target Linked CDB: Select an existing container database as the provision target CDB from the Container Database drop-down menu of CDBs on that environment.
2. Existing vCDB: Select an existing vCDB as the provision target CDB from the Container Database drop-down menu of CDBs on that environment. (Supported only for Oracle versions 12.1.0.2 and later.)
3. New vCDB: Select the Create a New Container Database checkbox. This will create a new vCDB object in that environment with this new vPDB plugged into it.
Click Next to advance the left-hand pane to the Target Configuration tab, and edit as necessary.
Enter the target Group for the vPDB you are about to provision.
The Environment User must have permission to write to the specified Mount Base, as described in Requirements for Oracle Environments and Data.
You can also reuse the Delphix toolkit directory, which already exists as the Mount Base, or create a new writable directory in the target environment with the correct permissions and use that as the Mount Base.
1. Linux and Unix hosts, this mount path must be the full path and not include symlinks.
Enter the vPDB Name and the Oracle Pluggable Database Name.
Click on the “Transparent Data Encryption (TDE) Enabled” checkbox. The following three fields need to be specified during the vPDB provision. Refer to the Provisioning parameters for a TDE-enabled vPDB section for important information on these three fields.
1. Parent Database TDE KeyStore Location - Specify the path to a KeyStore that contains the keys used to encrypt the source database datafiles. As noted earlier, the wallet ewallet.p12 must exist in the specified path and must be readable by the Oracle user. Warning: Parent Database TDE KeyStore may be located on local storage, NFS or ACFS, but cannot be located on an ASM filesystem.
2. Parent Database TDE KeyStore Password - Specify the password for the parent database TDE KeyStore.
3. TDE Secret for Exported Keys - Specify the password for the exported keys. Warning: Make sure the TDE Secret for Exported Keys is stored in a secure location for your records. It is only known to you. In the rare event that keys need to be manually extracted from an exported keyfile, this password will be required. Delphix Support cannot assist with manually exporting keys without this password, therefore it should be known or recorded within your organization.
If the target CDB is a vCDB, two additional necessary fields need to be specified - “Target vCDB TDE KeyStore Location” and “Target vCDB TDE KeyStore Password”. Please note that the Environment User must have permission to write to the “Target vCDB TDE KeyStore Location” otherwise the provisioning will fail. Refer to the Provisioning parameters for a TDE-enabled vPDB section for important information on these two fields.
If you selected to create a new target vCDB, configure the vCDB:
1. Enter the vCDB Name, Database Unique Name, and Database Name for the vCDB you are about to provision.
2. Select the Configure vCDB Parameters checkbox if you want to use a VDB Configuration Template. See Customizing Oracle VDB Configuration Settings.
Click Next to advance the left-hand pane to the Advanced tab.
The available options are Auto vCDB Restart, Auto vPDB Restart, File Mapping, and custom environment variables.
For more information, see Customizing VDB File Mappings and Customizing Oracle VDB Environment Variables.
Click Next to advance the left-hand pane to the Policies tab.
Select the VDB Snapshot policy to be applied to the vPDB.
Select a Retention Policy for the vCDB, if you are provisioning a vCDB.
Click Next to advance the left-hand pane to the Masking tab.
Select the Mask this vPDB checkbox if you want to mask, and select the masking job to be applied.
Click Next to advance the left-hand pane to the Hooks tab, and create any hooks if necessary. For more information, see Hook Scripts for Automation and Customization.
Review the provisioning summary. Confirm all the fields are correct. Click Submit to proceed with provisioning the vPDB.

TDE KeyStores Root and Artifact Directory

The artifact directory on the target host stores the exported keyfiles used during the workflows for TDE-enabled vPDBs. It is located under the KeyStores root, in the directory oracle_tde_keystores. Each TDE-enabled vPDB will have its own directory within the oracle_tde_keystores directory, identified by the vPDB name, group name, and a unique identifier, separated by an underscore. If the KeyStores root directory is not specified, then it defaults to the toolkit directory path.

For example, if the KeyStores root directory is /work (or KeyStores root is not specified, and the toolkit directory is /toolkit), the artifact directory for the vPDB tde_vpdb in the group Encrypted could be

/toolkit/oracle_tde_keystores/tde_vpdb_Encrypted_ce7a47e6-8860-4398-bab0-cf0233fc5e3c

Within the artifact directory, there is a subdirectory exported_keys which contains within it the exported keyfiles for each timeflow associated with that vPDB. Each time an export is performed, a new exported keyfile is generated with a timestamp. The contents of the artifact directory may change in future releases, but the path to the artifact directory and the naming convention is not anticipated to change.

As the default KeyStores root directory is at the same level as the toolkit directory, it will not be overwritten if a host is refreshed through the Continuous Data Engine and the toolkit updated. It is the customer's responsibility to backup the KeyStores root directory and ensure that the contents are not lost, as a disk failure could prevent a TDE-enabled vPDB from being accessed. The Continuous Data Engine never keeps a copy of the KeyStores or exported keyfiles on Continuous Data storage. Thus it is recommended that the KeyStores root directory be on a disk which is regularly backed up.

The artifact directory is not removed when a TDE-enabled vPDB is deleted; the customer can remove it after confirming that the vPDB has been removed (including from any replicated Delphix Engines).

The Continuous Data Engine does not keep a copy of the KeyStores or exported keyfiles on Delphix storage and thus a disk failure could prevent a TDE-enabled vPDB from being accessed. Therefore, Delphix highly recommends that the TDE KeyStores root directory be backed up at regular intervals.

Other operations on a TDE-enabled vPDB

Once a TDE-enabled vPDB is provisioned, it can be used the same as a non-TDE-enabled vPDB within Continuous Data, with the exception of migrate which is separately covered below. There are however a few caveats or behavioral differences as follows:

Refreshing a TDE-enabled vPDB will use the parent KeyStore for the recovery. If the parent PDB’s master keys are changed, the user will need to update the parent KeyStore with the new keys, for example by re-copying the parent PDB’s ewallet.p12 file to the parent KeyStore location on the target host. Similarly, if the location or password to the parent KeyStore has changed then they should be updated before the refresh.
Rewinding a TDE-enabled vPDB will use the target KeyStore for the recovery. If the vPDB is rekeyed after it is provisioned, then the rekey will update the target KeyStore, so it does not need to be updated in Continuous Data.
For a single vPDB in a vCDB, if the Target vCDB TDE KeyStore Location is changed, the new path must be updated in Continuous Data before refresh or rewind.
Disabling a TDE-enabled vPDB will result in the keys being exported to an exported keyfile in the artifact directory, to be used for a subsequent enable. Refresh and rewind operations will first disable the existing vPDB, so those will also result in a new exported keyfile in the artifact directory.
Provisioning a second-generation vPDB (vvPDB) from a TDE-enabled vPDB is done in the same manner as a first-generation vPDB, by specifying the TDE parameters during provision. The parent database TDE KeyStore location for the vPDB can be specified as the parent database TDE KeyStore location for the vvPDB.

If a vPDB is moved to a different host (either through the migrate workflow or an enable after a failover, then the artifact directory will need to be copied to the new target host. See Migrating a TDE-enabled vPDB for details on the manual steps needed for migration.