Provisioning a TDE OKV-enabled vPDB

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

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

Prerequisites for provisioning a vPDB into a TDE OKV-enabled CDB

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

1. OKV Home path

   • Description: The installation path of the Oracle Key Vault client library, particularly the okvclient.jar file, on the target database node will be automatically discovered if it's set for the environment user. (Required)

   • CLI parameter: host.oracleHostParameters.tdeOkvHomePath

   • Notes

     • This parameter must be updated via the GUI or CLI in the Environments page as described in Adding or Editing the OKV Home.

     • In an Oracle Real Application Clusters (RAC) environment, you need to update this attribute for each Oracle RAC node. This is necessary because each RAC node is enrolled and provisioned as an endpoint, and a separate okvclient.jar will be installed on each RAC node.

2. TDE External Key Manager Credential

   • Description: The password for the endpoint provided during the installation of the Oracle Key Vault client library (i.e., okvclient.jar) on the target database node.

     • 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 described 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 an Oracle Real Application Clusters (RAC) environment, you need to update this attribute for each Oracle RAC node. This is necessary because each RAC node is enrolled and provisioned as an endpoint, and a separate okvclient.jar will be installed on each RAC node.

3. Granting target endpoint 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 Oracle Key Vault, ensure that the target endpoint has at least Read Only access to the master encryption key of the parent dSource. 

If the same OKV instance is used for both the parent and target endpoints, Oracle Key Vault virtual wallets can be employed. These wallets control the security object access mechanism among users, groups, and endpoints. For instructions on setting up this access, refer to the Oracle Key Vault documentation.

However, if different OKV instances are used for the parent and target endpoints, the master encryption key of the parent dSource must be uploaded into the target endpoint. For instructions on downloading and uploading the master encryption keys, refer to the Oracle Key Vault Utility documentation.

Provisioning parameters for a TDE OKV-enabled vPDB

To initiate the provision, Delphix Continuous Data Engine needs the following parameters(all of which can be specified in the GUI or CLI). 

1. 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 Continuous Data during provisioning and subsequent vPDB operations that require unplugging or plugging of vPDB. 

2. 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 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 Delphix User must have permission to write to this path.

3. Target vCDB TDE External Key Manager Credential

   • Description: The Target endpoint password for the new vCDB keystore.

     • Required for new vCDB targets.

     • Not applicable to linked CDB or existing vCDB targets.

   • CLI parameter: virtualCdb.sourceConfig.tdeKeystorePassword

   • Notes

     • This is the same password that was provided during the installation of the Oracle Key Vault client library (okvclient.jar) on the target database endpoint.

     • If this password is changed, it must be updated via the GUI or CLI on the Environments page, as described in Adding or Editing TDE External Key Manager Credential.

Provisioning a TDE OKV-enabled vPDB

1. If you are provisioning to a linked CDB or a new vCDB for the first time, add the OKV Home by following the steps listed in Adding or Editing the OKV Home. This is a one-time activity. Once you have updated the OKV Home, you can provision any number of vPDBs in this environment. If you are provisioning to a RAC cluster, make sure to update it for each database node.

2. 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. To validate the correctness of the TDE External Key Manager Credential for the target endpoint, refer to the Oracle Key Vault okvutil utility documentation. 

3. If you are provisioning to a Linked CDB or vCDB for the first time, ensure that you grant at least read access to the parent dSource endpoint master encryption key for the target endpoint.

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

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

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

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

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

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

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

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

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

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

    

14. When provisioning to a new vCDB, click on the “Transparent Data Encryption (TDE) Enabled” checkbox and select ‘OKV’ from the “TDE Keystore Config Type” dropdown. Two additional necessary fields need to be specified - “TDE External Key Manager Credential” and “TDE Encryption Secret”. 

15. TDE External Key Manager Credential - Specify the password for the target endpoint provided during the installation of the Oracle Key Vault client library (i.e., okvclient.jar) on the target database node.

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

    

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

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

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

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

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

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

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

24. Review the provisioning summary. Confirm all the fields are correct. Click Submit to proceed with provisioning the vPDB.