Note:

• This tutorial requires access to Oracle Cloud. To sign up for a free account, see Get started with Oracle Cloud Infrastructure Free Tier.
• It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.

Manage Encryption in Oracle GoldenGate Microservices with Oracle Key Vault

Introduction

This tutorial provides a step-by-step process for managing encryption using Oracle Key Vault 21.7 in Oracle GoldenGate microservices.

Key Management Service

Oracle provides two key management services: Oracle Key Vault and Oracle Cloud Infrastructure Key Management Service (OCI KMS); both of which are supported by Oracle GoldenGate. These services provide scalability in managing encryption keys and credentials, ensuring that the key is not stored or managed by Oracle GoldenGate.

Encryption in Oracle GoldenGate

Oracle GoldenGate secures trail files using an encapsulation encryption approach. For each trail file, it generates a unique data encryption key (DEK), referred as a local key, which is used to encrypt the trail file’s contents. This DEK is then encrypted using a master key, and the encrypted DEK is embedded in the trail file header.

This method ensures that a new encryption key is automatically generated for every trail file, enhancing data security. The process of encrypting one key (the DEK) with another key (the master key) is known as key wrapping, a technique standardized by ANSI X9.102 from the American National Standards Institute (ANSI).

Why use OCI KMS to Store Oracle GoldenGate Encryption Keys?

Key management encompasses the generation, distribution, storage, usage, and rotation of encryption keys. An OCI KMS includes key servers, user-defined procedures, and secure protocols. Effective key management is critical to maintaining the overall security posture of an enterprise.

The advantages of using OCI KMS with Oracle GoldenGate are:

• Centralized Master Key Management: Master keys can be generated and uploaded directly to Oracle Key Vault using custom attributes, enabling seamless lifecycle operations such as rotation and expiration within the OCI KMS itself.
• No Local Key Storage: Oracle GoldenGate does not store or manage master keys locally, reducing risk and simplifying compliance.
• Enhanced Security Integration: Oracle GoldenGate benefits from the advanced security capabilities of dedicated OCI KMS solutions, including layered encryption controls and strict access policies.

Trail File Encryption

Oracle GoldenGate provides the following Advanced Encryption Standard (AES) based methods for trail encryption:

• Local Wallet: The encryption master key is stored in local wallet file.

• Oracle Key Vault: The encryption master key is stored in Oracle Key Vault. Oracle Key Vault can reside on a different server from the Oracle GoldenGate server. The Oracle Key Vault method is highly recommended for on-premises Oracle GoldenGate trail encryption. This method is available with Oracle GoldenGate Microservices Architecture and requires defining an encryption profile in Oracle GoldenGate. For more information, see Using Oracle Key Vault Trail File Encryption in Oracle GoldenGate.

• OCI KMS: The encryption master key is stored in OCI KMS, and the master key never leaves OCI KMS. This method is recommended if your Oracle GoldenGate deployment can access OCI KMS. It is compatible with Oracle GoldenGate Microservices Architecture and requires defining an encryption profile in Oracle GoldenGate. For more information, see Configure Oracle GoldenGate Processes to Enable OCI KMS Trail File Encryption.

Task 1: Configure Oracle Key Vault for Oracle GoldenGate

The following steps belong to the Oracle Key Vault configuration on the machine where the Oracle GoldenGate instance is running.

1. Download okvrestservices.jar from the Oracle Key Vault server, ensuring that Oracle GoldenGate is deployed under the same system user as the deployment.

2. Download and install the endpoint file, okvclient.jar, from the Oracle Key Vault server, ensuring that Oracle GoldenGate is deployed under the same system user as the deployment. For example, java -jar okvclient.jar -d /u01/app/oracle/OKV.

   

3. Run the following example command to create the key. The name of the wallet is provided by the Oracle Key Vault administrator or we can associate wallet from Oracle Key Vault console later.

   	java -jar okvrestservices.jar kmip  --config /u01/app/oracle/OKV/conf/okvclient.ora  --service create_key --algorithm AES --length 256 --mask "ENCRYPT,DECRYPT,TRANSLATE_ENCRYPT,TRANSLATE_DECRYPT,TRANSLATE_WRAP,TRANSLATE_UNWRAP"
   
   

   

4. From the Oracle Key Vault console, we can validate the key and match the unique identifier created in Step 3.

   

5. Associate the wallet created from Oracle Key Vault console with encryption key and provide the access to endpoint.

   

6. Add the wallet detail to provide access to endpoint.

   

7. Click Save to save your changes.

   

   

8. Set the OKV_HOME environment variable.

   OS> export OKV_HOME /u01/app/oracle/OKV 
   

   The sub-directory structure contains the necessary libraries, binaries, and configuration files for the Oracle Key Vault environment. For more information about the configuration within the OKV server, see Oracle Key Vault Installation and Configuration in the Oracle Key Vault Administration Guide.

9. Activate the key as shown in the following example.

   java -jar okvrestservices.jar kmip  --config /u01/app/oracle/OKV/conf/okvclient.ora  --service activate -uid A087DAC3-ED0F-4F06-BF6C-3F3CD3FC528B
   

   

10. Add the Oracle GoldenGate related key attributes (KeyName, KeyVersion) to the configuration. The key name must match the master key name in the OCI KMS encryption profile created within Oracle GoldenGate. The key value must match the version number of the master key.

    java -jar okvrestservices.jar kmip  --config /u01/app/oracle/OKV/conf/okvclient.ora  --service add_custom_attr --uid  D98640C4-A4B4-4FA5-BF8B-8D90610CD68A --attribute x-OGG-Keyname --type TEXT --value OGG_Masterkey
    Success
    
    

    java -jar okvrestservices.jar kmip  --config /u01/app/oracle/OKV/conf/okvclient.ora  --service add_custom_attr --uid  D98640C4-A4B4-4FA5-BF8B-8D90610CD68A --attribute x-OGG-KeyVersion --type TEXT --value 1
    Success
    
    

    

    

11. Use the okvutil utility to list the configuration setting and check the endpoint status as shown in the following example.

    -bash-4.2$ export OKV_HOME=/u01/app/oracle/OKV
    -bash-4.2$ $OKV_HOME/bin/okvutil list -v 4
    

    

Task 2: Configure an Encryption Profile in Oracle GoldenGate Microservices with Oracle Key Vault

What is an Encryption Profile?

An encryption profile defines the configuration required to securely access a master key from an OCI KMS. It contains all necessary details for connecting to the OCI KMS, authenticating the request, and identifying the specific master key to be used for encryption and decryption operations. This includes server connection parameters, authentication credentials, and key identification attributes.

How to Configure an Encryption Profile in Oracle GoldenGate Microservices Architecture?

Encryption profiles can be configured using either the Administration Server or the AdminClient.

The AdminClient provides commands such as ADD ENCRYPTIONPROFILE, ALTER ENCRYPTIONPROFILE, DELETE ENCRYPTIONPROFILE, and INFO ENCRYPTIONPROFILE to manage these profiles. Additionally, the ADD and ALTER commands for Extract, Replicat, and Distribution Path have been enhanced to include the ENCRYPTIONPROFILE encryption-profile-name parameter.

Oracle GoldenGate Administration Server provides options to set up encryption profiles for managed Extract and Replicat processes.

1. To set up the encryption profile, click Profile from the navigation pane and select Key Management System (KMS).

2. By default, the local wallet profile is created. In case we need to set up Oracle Key Vault as OCI KMS service for Oracle GoldenGate, click + sign next to Profile to create an encryption profile for Oracle Key Vault by specifying the following details:

   • Name: Enter the name of the Oracle Key Vault encryption profile.
   • Type: Specify the OCI KMS type as Oracle Key Vault.
   • Home Path: Specify the directory location where Oracle Key Vault is installed. In admin client, this is the Oracle Key Vault path. In the web interface, this is the OCI KMS library path.
   • Key Name Attribute: Specify the name of the encryption key using this custom attribute. This value must match the key name in the OCI KMS parameter in Oracle GoldenGate and cannot be changed once replication has started.
   • Key Version Attribute: Specify the version of the encryption key using this custom attribute. This value must be numeric.
   • MasterKey Name: Specify the name of the master key.
   • MasterKey Version: Specify the version of Oracle Key Vault. Default value is LATEST or you can specify the version number such as 18.1.
   • Time to live: Time to live (TTL) for the key retrieved by Extract from OCI KMS. When encrypting the next trail, Extract checks if TTL has expired. If so, it retrieves the latest version of the master key. The default is 24 hours.

   Note: Do not upload keys with duplicate values of Key Name and Key Version. At the time of startup, restart, or rollover, Oracle GoldenGate processes retrieve the highest Key Version value.

   

Task 3: Add Database Details and Test Connection

1. Open Oracle GoldenGate Administration Service Console and log in.

2. Click DB Connections from the left navigation pane.

3. Click the plus sign (+) next to DB Connections. The Credentials will be displayed.

4. Submit the database details and click Submit.

5. Click the connect database icon to connect to database.

Task 4: Add the Extract by Providing the Encryption Profile

To add Extract, enter the required information as shown in the following images.

We can verify that trail files are now encrypted using string command as shown in the following image.

We can also check the Oracle GoldenGate error log to verify that the trail files are encrypted.

Related Links

• Managing Encryption Using a Key Management Service in Oracle GoldenGate Microservices Architecture

Acknowledgments

• Authors - Amresh Kumar Singh (Senior Cloud Engineer, Oracle North America Cloud Services - NACIE), Ankush Chawla (Principal Cloud Architect, Oracle North America Cloud Services - NACIE)

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

Manage Encryption in Oracle GoldenGate Microservices with Oracle Key Vault

G34612-02

Copyright ©2025, Oracle and/or its affiliates.