Using OCI KMS Trail File Encryption in Oracle GoldenGate

Oracle GoldenGate with OCI KMS Workflow

The following diagrams explains how Oracle GoldenGate works with OCI KMS for trail file encryption.

Setting up OCI KMS encryption profile in Oracle GoldenGate and attaching the encryption profile to Extract. Including the ENCRYPTTRAIL parameter to specify the encryption algorithm in the Extract parameter file.

This diagram shows the source deployment EAST containing an Extract associated with the OCI KMS encryption profile. To create the encryption profile in Oracle GoldenGate, the OCI user needs to access the OCI tenancy and get some values from the OCI vault and generate the master key and the API key for the OCI user.

The OCI vault contains information about the tenancy OCID, user OCID, and cryptographic endpoint URL used for downloading the digital CA certificate. The master key associated with the vault is also generated from the OCI vault. The API key pair is also required, which you can generate from the OCI tenancy or upload an existing key pair. See Configure OCI KMS to Connect with Oracle GoldenGate for details.

After you have saved all the values from the OCI tenancy, you can create an encryption profile in Oracle GoldenGate Administration Service. This encryption profile is then associated with the Extract and the Extract parameter file applies the encryption algorithm (AES 128, AES 192, AES 256) that you have decided to apply, using the ENCRYPTTRAIL parameter. The encrypted trail file is transported by the DISTPATH to the target deployment (WEST). The Replicat parameter file on the target deployment (WEST) includes the DECRYPTTRAIL parameter, which allows decrypting the trail file. See Configure Oracle GoldenGate Processes to Enable OCI KMS Trail File Encryption.

Prerequisites for Connecting Oracle GoldenGate with OCI KMS

Perform the tasks in this section before you begin configuring an OCI KMS encryption profile in Oracle GoldenGate.

Download the CA Certificate using the Cryptographic Endpoint

To perform the steps in this topic, you need to have a Vault in your OCI tenancy where the cryptographic endpoint URL is mentioned. This URL is required to download the digital CA certificate, for establishing a trusted connection from Oracle GoldenGate to the OCI tenancy. If you don't have an existing vault, then see Create or Access the OCI Vault, and return to this topic for steps to download the CA certificate using the cryptographic endpoint.

If you have an existing Vault in your OCI tenancy, then follow the steps provided in this topic, to download the CA certificate using the cryptographic endpoint.

Navigate to Identity & Security page from the left-navigation pane and select Vault to open the Vault Information page.
From the Vault Information page, copy the cryptographic endpoint value and OCID.
Open a web browser and paste the cryptographic endpoint value in the browser URL bar. The browser does not display any page. However, you can click the Connection is secure to view the CA certificate.

This CA certificate is required by Oracle GoldenGate to be able to trust this OCI tenancy when connecting to it.
Go to the Downloads section of the web browser. The CA certificate are listed here.
Click Export to download the Root certificate.

Tip:
Keep the same directory for downloading the API key and the Root certificate.

Add the Digital CA Certificate as a Trusted CA Certificate in Oracle GoldenGate

The digital CA certificate which you downloaded previously using the cryptographic endpoint URL, needs to be added to the Oracle GoldenGate source deployment as a trusted CA certificate. See Create Certificates for a Secure Deployments.

Note:

In OCI GoldenGate Service, you can skip this step as the CA certificate is already added as part of the service.

From the Oracle GoldenGate Service Manager, perform the following steps to add the digital CA certificate as a Trusted CA certificate for the source deployment:

Log in to Oracle GoldenGate Service Manager.
From the left-navigation pane, select the Certificate Management option.

Certificate Management page in Oracle GoldenGate Service Manager

As of now, there is no certificate added as a trusted certificate to connect to the specific OCI tenancy. You will need to add the root certificate that you had downloaded in step of
Add the root certificate as a trusted certificate to the CA Certificates in the Oracle GoldenGate deployment. This enables Oracle GoldenGate to trust a connection with the specific OCI tenancy. Also see, Add a CA Certificate.

Configure OCI KMS to Connect with Oracle GoldenGate

From the OCI KMS tenancy, certain values are needed to set up a connection between Oracle GoldenGate and OCI KMS. These values are:

Tenancy ID
Cryptographic Endpoint
User OCID
API Key

Before configuring Oracle GoldenGate to connect with OCI KMS, you need to log in to the OCI tenancy to perform the following tasks:

Create a vault, if not already created and get the cryptographic endpoint and User OCID values. See
Create and download an API private key pair and information associated with the API key such as the fingerprint and API key value.
Download the CA certificate using the cryptographic endpoint. This step is also a prerequisite for configuring Oracle GoldenGate encryption profile. See Download the CA Certificate using the Cryptographic Endpoint for details.

Use the following steps to view and save the OCI KMS values, which would be required while setting up Oracle GoldenGate processes for connecting to OCI KMS:

Create or Access the OCI Vault

Access the vault if it already exists in your OCI tenancy to determine the values for:

Cryptographic Endpoint: This is the link from where you need to obtain the trusted certificate. Copy this link for use in the later steps.
OCID: This is the unique ID for your OCI environment. It will be required while setting up the encryption profile in Oracle GoldenGate.

Use the following steps to create and access the vault:

Log in to your Oracle Cloud account.
From the left-navigation pane of the Oracle Cloud home page, click the Identity & Security option and then select Vault.
Click Create Vault to create a vault, if you haven't already created a vault. In this case, the vault (WSJCVAULT) is already created.
Click the vault name, for example WSJCVAULT shown in the following image, to access the information regarding vault ocid, cryptographic endpoint, and master key details. In the following image, the General Information section contains the ocid and cryptographic endpoint details and the Master Encryption Keys in the Compartment_WH section displays the master key details.

From this page, you get the values required to set up a trusted connection between Oracle GoldenGate and OCI KMS. Copy this information to a notepad for reference.

Generate the Master Key and Download the API Private Key

The following steps assume that you are already logged into your OCI tenancy.

Generate Master Key

To create the master key:

Navigate to the Vault Information page.
Click Create Key to display the Create Key page.
Specify the name of the Master key and encryption algorithm among other details to create a master key, as shown in the following image.
Click Create Key. This generates the master key that would be used by Oracle GoldenGate.

Generate API Key

To connect the user with OCI KMS, create an API key using the following steps:

From the vault information page, click the User Settings icon on the top-right corner.
Click the API Key option from the Resource section of the left panel to open the API Keys section.
Click Add API Key to open the Add API Key dialog box.
Select the Generate the API key Pair option to create a key pair for the OCI user to connect with OCI KMS. You also have the option to upload an existing public key file using the Choose Public Key File option or paste the value of public key in the text box using the Paste Public Key option.
Click Download Private Key and keep it in a known location. You can rename the file to a user-friendly name such as API_private_key.pem.
Click Add. This displays the Configuration File Preview dialog box, which contains all information associated with the API key such as the fingerprint, tenancy, region and other details. Copy and save these values in notepad.

Tip:
Maintain the same notepad file to store information about the API key's fingerprint, tenancy value and the information about the cryptographic endpoint and OCID values for the OCI vault.
Click Close to return to the API Keys section where the new API key is listed.

The next step is to set up Oracle GoldenGate encryption profile using all these details and then apply the encryption profile to Extract, Replicat processes, as needed. See the Configure Oracle GoldenGate Processes to Enable OCI KMS Trail File Encryption for next steps.

To learn about the OCI KMS encrypt and decrypt endpoints, see /encrypt and /decrypt endpoint documentation in Oracle Cloud Infrastructure Documentation.

Configure Oracle GoldenGate Processes to Enable OCI KMS Trail File Encryption

Before beginning the steps in this section, make sure that you have completed the Prerequisites for Connecting Oracle GoldenGate with OCI KMS .

In the Oracle GoldenGate interface, perform the following tasks when configuring Oracle GoldenGate to set up a trusted connection with OCI KMS:

Create an encryption profile using the OCID, cryptographic endpoint, API key, tenancy, and fingerprint values.
Apply the encryption profile to Extract, Distribution Path, or Replicat processes.

Use the steps provided in the following sections to apply OCI KMS-based trail encryption from Oracle GoldenGate Microservices Architecture:

Create Encryption Profile in Oracle GoldenGate Processes

Use the following steps to apply OCI KMS-based trail file encryption from Oracle GoldenGate Microservices Architecture web interface:

Open the notepad file where you saved the details for the OCI KMS API key and crypto endpoint details. See step 8 for reference from the Configure OCI KMS to Connect with Oracle GoldenGate. The following image displays the values obtained from API Configuration File Preview dialog box:

The information would include the following values:
- Crypto Endpoint URL: This value is displayed in the Vault page of OCI KMS.
- Tenancy OCID: This value can be obtained from the API values that were copied in the notepad file.
- Key OCID: To obtain this value:
  1. Go to the OCI Vault page and click the API key to open the key details page where the OCID for the API key is provided.
  2. Copy the API private key OCID from the Key Details page.
- User OCID: Obtain this value from the API configuration details.
- API Private Key: Upload the API Private Key from the location where you saved it while performing tasks in Configure OCI KMS to Connect with Oracle GoldenGate.
- API Key Fingerprint: Obtain this value from the API configuration details.
Log in to the Administration Service and select the Encryption and then select Profiles from the left navigation pane.
Click the plus sign next to Oracle Cloud Infrastructure to open the Create Encryption Profile dialog box.
Add the values to the encryption profile and Submit. When you click Submit, the encryption profile is validated and if the validation is successful, then the OCI KMS encryption profile displays on the Encryption Profiles page, as shown in the following image:

You can change the values for the encryption profile by clicking the pencil icon, which opens the Edit Encryption Profile dialog box.

Apply the OCI KMS Encryption Profile for Extract

Use the following steps to implement the OCI KMS encryption profile for Extract:

From the Administration Service home page, click the plus sign next to Extracts to open the Add Extract dialog box.
After providing other details for the Extract, scroll down and expand the Encryption Profile section and select OCIKMS profile name.
In the Extract parameter file, include the ENCRYPTTRAIL AES256 option. The Extract parameter file would look similar to the following:
```
EXTRACT exte
USERIDALIAS ggwest DOMAIN OracleGoldenGate
ENCRYPTTRAIL AES256
EXTTRAIL ea  
TABLE WPDB.U1.*;
```
Click Create to add Extract and then start the Extract.
On the target host, select Add Replicat from the Administration Service Overview page to add a Replicat.
Select the type of Replicat and populate the Replicat details.
Scroll to the Encryption Profile section, and select the same OCIKMS encryption profile (in this case OCIKMS). Click Next.
In the Replicat parameter file, include the DECRYPTTRAIL option. The Replicat parameter file looks similar to the following:
```
REPLICAT renct
USERIDALIAS ggeast DOMAIN OracleGoldenGate
DECRYPTTRAIL
MAP WPDB.U1.*, TARGET U2.*;
```
Create and then start the Replicat process.
If you want to apply the encryption profile on a Distribution Path (DISTPATH), then you need to do the following steps:
1. Create the OCI KMS encryption profile on the target host.
2. Create the DISTPATH and apply the OCI KMS encryption profile to it. See Add a Distribution Path.
3. Use the same encryption profile to decrypt the trail on the target. This implies that you use the encryption profile created on the target host, while adding a Replicat.

The next section describes steps to test that the committed transactions are captured and applied when using an encryption profile

See ADD ENCRYPTIONPROFILE, ALTER ENCRYPTIONPROFILE if you want to set up the encryption profile using the Admin Client.

Test Data Replication with Trail File Encryption Using OCI KMS

Test the trail file encryption on the source side and trail file decryption on the target side using the steps given in this topic.

Test Trail File Encryption in the Source Deployment

In Configure Oracle GoldenGate Processes to Enable OCI KMS Trail File Encryption, the Extract is set up with the OCI KMS encryption profile.

In this example, you will be able to confirm that the encryption profile is being used by Extract by viewing the Extract report file.

To check if Extract is using the OCI KMS encryption profile:

From the Administration Service, click Extract and then select the Extract where the encryption profile is applied. You will be able to see the OCI KMS encryption profile listed under the Encryption section of the Extract page, as shown in the following image.
For troubleshooting purposes, you can check if the trail file is encrypted at source, using Logdump commands. See the Scanning a Trail File to Check for Trail File Encryption from the Logdump Reference for Oracle GoldenGate.

Test the Trail File Decryption on the Target Deployment

On the target side, the following example tests that Replicat applies the 3000 transactions that were captured from source. To make sure that the Replicat is using the OCI KMS encryption profile to decrypt the trail file, check the Replicat report file.

From the Administration Service home page, click Replicat, and select the Replicat name.
Click Statistics. On the Statistics page, the applied transactions are displayed.
Check the Replicat main page to see if the encryption profile is implemented and used by the Replicat.

Tip:
To check if the trail data is received in encrypted format on the target, you can run Replicat without the DECRYPTTRAIL parameter. In this case, the Replicat report file displays that the trail data is encrypted and could not be decrypted without proper key setting.

With these use cases, you can test that the trail file on the Extract side is using OCI KMS encryption profile to encrypt the trail data. On the Replicat side, the OCI KMS encryption profile is used to decrypt the trail data and apply the transactions on the target.