Skip to main content
Skip table of contents

Provisioning a TDE software keystore based vPDB

Provisioning a TDE software keystore based Virtual Pluggable Database (vPDB) to a TDE software keystore based 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 software keystore based 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 software keystore based vPDB from a source snapshot of a dSource or virtual database that is not encrypted at the time of linking.

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 described in Updating the Parent Database TDE Keystore Location, 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 described in Adding or Editing the Target keystore Password.

    • 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 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 parameters: 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 described 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 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.

    • When provisioning to a cluster target, this path must be on shared storage and available to all cluster hosts.

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 described in Adding or Editing the Target Keystore Password.

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

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

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

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

  2. If provisioning to a cluster target, ensure that the keystores root directory path is set correctly following the steps described in Adding or Editing the TDE Keystores Root.

  3. In the Datasets panel, select an Oracle TDE-enabled PDB dSource or a previously provisioned TDE-enabled vPDB.

  4. From the Timeflow tab, select a snapshot or point in time to provision from.

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

  6. Click Next to advance the left-hand pane to the Target Configuration tab, and edit as necessary. 

  7. Enter the target Group for the vPDB you are about to provision.

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

  9. Enter the vPDB Name and the Oracle Pluggable Database Name.

  10. Click on the “Transparent Data Encryption (TDE) Enabled” checkbox. The following three fields need to be specified during the vPDB provision.

    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.

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

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

  13. Click Next to advance the left-hand pane to the Advanced tab.

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

  15. Click Next to advance the left-hand pane to the Policies tab.

  16. Select the VDB Snapshot policy to be applied to the vPDB.
    Select a Retention Policy for the vCDB, if you are provisioning a vCDB.

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

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

  19. 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 the Continuous Data engine 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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close