Using Oracle Key Vault Trail File Encryption in Oracle GoldenGate

Learn about the benefits of using Oracle Key Vault (OKV) with Oracle GoldenGate Microservices Architecture. Determine the system requirements, processes and parameters available with Oracle GoldenGate for configuring OKV with Oracle GoldenGate.

The following diagram explains the Oracle Key Vault set up and workflow in the Oracle GoldenGate environment.

As shown in the diagram, you can select the Key Vault (OKV) as the Key Management System while configuring the the encryption profile for the deployment in Oracle GoldenGate. This encryption profile is used by the Extract, Replicat processes to store and apply the master keys before transferring trail files using the distribution path and receiving the files on the other end with the RECVPATH process. The Web Secure Socket (WSS) protocol is used to validate the connection between the DISTPATH and RECVPATH to estable a secure communication channel.

Oracle Key Vault Capabilities

Oracle GoldenGate 23ai and higher releases support Oracle Key Vault 21.8 for trail file encryption. The following table provides the behavior and capabilities of Oracle Key Vault (OKV).

For more information about configuring OKV, see Installing and Configuring Oracle Key Vault .

KMS Name	KMS Type	Support Tags	Support Importing of Keys
Oracle Key Vault	Keyname and custom attributes for versioning	Yes	Yes

Prerequisites for Configuring OKV on Oracle GoldenGate

Learn the prerequisites for setting up OKV with Oracle GoldenGate.

The following steps belong to the OKV configuration on the machine where the Oracle GoldenGate instance is running:

1. Download the okvrestservices.jar from the OKV server, where Oracle GoldenGate is deployed as the same system user as the deployment.

2. Download and install the endpoint file, okvclient.jar from the OKV server, where Oracle GoldenGate is deployed as the same system user as the deployment. For example,

   OS> java -jar okvclient.jar -d /u01/app/oracle/OKV

3. Create the key. The name of the wallet is provided by the OKV administrator. The following example show how the key is created:

   OS> 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" 
           --wallet OKV_WALLET76876ABA-B06D-4F35-BF7C-D9306D29764B

   Alternatively, you can register your own key, as shown in the following example:

   OS>java -jar okvrestservices.jar kmip 
               --config ./conf/okvclient.ora --service reg_key -ENCRYPT,DECRYPT,TRANSLATE_ENCRYPT,TRANSLATE_DECRYPT,TRANSLATE_WRAP,TRANSLATE_UNWRAP 
               --wallet OGG_WALLET 
               --object /u01/key.txt64B3AAD0-BE77-1821-E053-0100007FD178

4. Set the OKV_HOME environment variable.

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

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

5. Activate the key as shown in the following example:

   OS> java -jar okvrestservices.jar kmip 
               --config /u01/app/oracle/OKV/conf/okvclient.ora
               --service activate 
               --uid 76876ABA-B06D-4F35-BF7C-D9306D29764B
   INFO: Success

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

   OS> java -jar okvrestservices.jar kmip 
               --config /u01/app/oracle/OKV/conf/okvclient.ora
               --service add_custom_attr 
               --uid 76876ABA-B06D-4F35-BF7C-D9306D29764B 
               --attribute x-OGG-KeyName 
               --type TEXT 
               --value OGG_Masterkey 
   INFO: Success

   OS> java -jar okvrestservices.jar kmip 
               --config /u01/app/oracle/OKV/conf/okvclient.ora
               --service add_custom_attr 
               --uid 76876ABA-B06D-4F35-BF7C-D9306D29764B 
               --attribute x-OGG-KeyVersion 
               --type TEXT 
               --value 1
   INFO: Success

7. Use okvutil to list the configuration setting and check the endpoint status. As shown in the following example:

   OS>okvutil list -v 4
   okvutil version 18.2.0.0.0
   Endpoint type: Oracle (non-database)
   Configuration file: /u01/app/oracle/OKV/conf/okvclient.ora
   Server: 10.245.64.45:5696 10.245.64.46:5696
   Standby Servers:Read Servers: 10.245.64.48:5696
   Auto-login wallet found, no password needed
   Trying to connect to 10.245.64.45:5696 ...
   Connected to 10.245.64.45:5696.
   Unique ID Type Identifier
   72B673E8-840B-4AD6-8400-CB77B68D74B5 Template Default template for OGG_EP
   76876ABA-B06D-4F35-BF7C-D9306D29764B Symmetric Key -

The next steps are managed within Oracle GoldenGate and are shown as an implementation from the Admin Client.

Client Behavior Against Different Key States for Oracle Key Vault

Following table describes the relative behavior of the of the writer (Extract) or reader (Replicat) client processes depending on the different trail encryption key states.

If the master key is non-extractable, then it implies that OKV cryptographic operations are using remote encryption. This means that the master key cannot leave or be retrieved from OKV. Commands to encrypt and decrypt in Oracle GoldenGate on the basis of once per trail file, are performed inside OKV.

A key can be in the following states:

Key State	Trail Writer (encryption)	Trail Reader (decryption)
Active	Trail writer chooses the highest version number with Active state for encryption.	Trail reader can use this key and version number to decrypt the trail.
Preactive	Trail writer ignores and does not consider the key version number with these states.	Not Applicable
Deactivated	None	Trail file reader retrieves and decrypts the trail if the key and version number is deactivated or compromised.
Compromised	None	Trail file reader retrieves and decrypts the trail if the key and version number is deactivated or compromised.
Destroyed	Non	Trail file reader generates an error and abends if the key and version number required to decrypt is in the destroyed or destroyed-compromised state.
Destroyed-Compromised	None	Trail file reader raises an error and abends if the key and version number required to decrypt is in the destroyed or destroyed-compromised state.