Provisioning a TDE HSM-enabled vPDB

Provisioning a TDE HSM-enabled Virtual Pluggable Database (vPDB) to a TDE HSM-enabled target container requires specifying several TDE provisioning parameters using either the GUI or CLI. Additionally, vPDB parameters, such as the vPDB name, target container, and the snapshot to provision from, must be provided. A TDE HSM-enabled vPDB can be provisioned to either a Linked CDB or a vCDB.

It is important to note that the Delphix Continuous Data Engine does not support provisioning a TDE HSM-enabled vPDB from a source snapshot of a dSource or virtual database that is not encrypted or encrypted using a software wallet or OKV at the time of linking.

Prerequisites for provisioning a TDE HSM-enabled vPDB

Before initiating the provision, Delphix Continuous Data Engine needs the following pieces of information:

TDE External Key Manager Credential
- Description: The credential of the external key manager which is managing master encryption keys of target databases.
  - Required for linked CDB or existing vCDB targets.
  - Not applicable to new vCDB targets.
- CLI parameter: host.oracleHostParameters.tdeExternalKeyManagerCredential OR sourceconfig.tdeKeystorePassword
  - TDE External Key Manager Credential provided at the database level takes precedence over that provided at the host level.
- Notes
  - This parameter must be updated via the GUI or CLI in the Environments page as specified in Adding or Editing TDE External Key Manager Credential.
  - 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.
  - This parameter must be updated via GUI or CLI whenever the endpoint password for the target database is rotated.
  - In the context of CipherTrust Manager, the external key manager credential format is specified as follows: "domain:username:password" For the default domain, the format simplifies to "username:password".
Granting target domain access to a parent dSource master encryption keys

To provision a vPDB, access to the master encryption key of the parent dSource is required. In the case of Thales CipherTrust Manager, ensure that the target domain has at least Read Only access to the master encryption key of the parent dSource domain.

If the same CipherTrust domain or subdomain is used for both the parent and target endpoints, we don’t need to set up the access. Same domain security objects are automatically accessible.

However, if different CipherTrust domains or subdomains are used for the parent and target endpoints, the master encryption key of the parent dSource must be accessible into the target domain or subdomain. For instructions on setting up access, refer to the CipherTrust Manager Documentation.

Provisioning parameters for a TDE HSM-enabled vPDB

TDE Encryption Secret
- Description: Encryption Secret for the pluggable database while executing unplug operation. (Required)
- CLI parameter: source.tdeExportedKeyFileSecret
- Notes
  - Oracle requires a transport secret to be set when executing the unplug operation on a TDE-enabled vPDB.
  - This parameter represents a new user-specified secret that is used by Continuous Data when unplugging vPDB, 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 the Delphix Continuous Data Engine during provisioning and subsequent vPDB operations that require unplugging or plugging of vPDB.
TDE Keystores 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 parameter: host.oracleParameters.tdeKeystoresRootPath
- Notes
  - This includes keystores used by the auxiliary CDB during provisioning and the artifact directories for TDE-enabled vPDBs.
  - This parameter must be updated via the GUI or CLI in the Environments page, as specified in Adding or Editing the TDE Keystores Root.
  - 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 Delphix Continuous Data Engine User must have permission to write to this path.
Target vCDB TDE External Key Manager Credential
- Description: The credential of the external key manager which is managing master encryption keys of target databases.
  - Required for new vCDB targets.
  - Not applicable to linked CDB or existing vCDB targets.
- CLI parameter: virtualCdb.sourceConfig.tdeKeystorePassword
- Notes
  - If this password is changed, it must be updated via the GUI or CLI in the Environments page, as described in Adding or Editing TDE External Key Manager Credential.
Target vCDB Autologin Wallet Location
- Description: Path of the location on the target host at which Continuous Data will create the auto-login keystore during new vCDB provisions.
  - Required for new vCDB targets.
  - Not applicable to linked CDB or existing vCDB targets.
- CLI parameter: source.targetVcdbTdeKeystorePath
- Notes
  - This path refers to a location on the target host.
  - This path must either be an existing auto-login location or can be an existing empty directory.
  - The Environment User must have permission to write to this location.
  - Delphix Continuous Data Engine will set the WALLET_ROOT parameter to the provided location.
  - This parameter must be updated if the keystore location is changed or else future Delphix Continuous Data Engine operations may fail.
  - When provisioning to a cluster target, this path must be on shared storage and available to all cluster hosts.

Provisioning a TDE HSM-enabled vPDB

If you're provisioning to a Linked CDB for the first time, add the TDE External Key Manager Credential for the target by following the steps listed in Adding or Editing TDE External Key Manager Credential. If you are provisioning to a RAC cluster, make sure to update it for each database node.
If you are provisioning to a Linked CDB or vCDB for the first time, ensure that you grant read access to the parent dSource master encryption key for the target. Please refer to the ‘Granting Target Domain Access to a Parent dSource master encryption keys’ section.
If provisioning to a RAC cluster target, ensure that the keystores root directory path is set correctly following the steps listed in Adding or Editing the TDE Keystores Root.
In the Datasets panel, select an Oracle TDE HSM-enabled PDB dSource or a previously provisioned TDE HSM-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.
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 Continuous Data Engine 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.
When provisioning to a Linked CDB or existing vCDB, the 'Transparent Data Encryption (TDE) Enabled' checkbox is automatically checked, and the 'TDE Keystore Config Type' dropdown is populated with 'HSM'.
TDE Encryption Secret - Specify the passphrase that is required during unplug/plug operation of the vPDB.

Warning: Make sure the TDE Encryption Secret is stored in a secure location for your records. It is only known to you. In the rare event that vPDB needs to be manually plugged from an unplugged vPDB, this passphrase will be required. Delphix Support cannot assist with manually plugging vPDB without this passphrase, therefore it should be known or recorded within your organization.

When provisioning to a new vCDB, click on the “Transparent Data Encryption (TDE) Enabled” checkbox and select ‘HSM’ from the “TDE Keystore Config Type” dropdown. Three additional necessary fields need to be specified - “Target vCDB Autologin Wallet Location”, “TDE External Key Manager Credential” and “TDE Encryption Secret”.
Target vCDB Autologin Wallet Location - Specify the location on the target host at which Continuous Data will create the auto-login keystore during new vCDB provisions. Refer to the “Provisioning parameters for a TDE with Hardware Security Module (HSM)-enabled vPDB” section for information on this field.
TDE External Key Manager Credential - Specify the credential of the external key manager which is managing master encryption keys of target databases. Refer to the “Provisioning parameters for a TDE with Hardware Security Module (HSM)-enabled vPDB” section for information on this field.
TDE Encryption Secret - Specify the passphrase which is required during unplug/plug operation of the vPDB.

Warning: Make sure the TDE Encryption Secret is stored in a secure location for your records. It is only known to you. In the rare event that vPDB needs to be manually plugged from an unplugged vPDB, this passphrase will be required. Delphix Support cannot assist with manually plugging vPDB without this passphrase, therefore it should be known or recorded within your organization.
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 vCDB Listeners, Auto vCDB Restart, Auto vPDB Restart, File Mapping, Patching 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.