19 Managing Encryption Using a Key Management Service in Oracle GoldenGate

From Oracle GoldenGate 21c onward, Oracle Key Vault (OKV) and Oracle Cloud Infrastructure Key Management Service (OCI KMS) are available for managing encryption. This chapter describes the benefits, system requirements, processes, and parameters for configuring these Key Management systems with Oracle GoldenGate.

Topics:

• Key Management Service
  Oracle GoldenGate supports Oracle Key Vault (OKV) and Oracle Cloud Infrastructure Key Management Service (OCI KMS) methods to manage encryption keys.
• Managing Encryption Using OKV in Oracle GoldenGate Classic Architecture
  This chapter describes the benefits of using OKV with Oracle GoldenGate Classic Architecture. It also describes the system requirements, processes and parameters available with Oracle GoldenGate for configuring Oracle Key Vault (OKV) with Oracle GoldenGate.

19.1 Key Management Service

Oracle GoldenGate supports Oracle Key Vault (OKV) and Oracle Cloud Infrastructure Key Management Service (OCI KMS) methods to manage encryption keys.

Oracle GoldenGate Microservices Architecture supports KMS to provide scalability in managing encryption keys and credentials along with security such that the key isn't stored or managed by Oracle GoldenGate.

Oracle GoldenGate uses the encapsulation approach to encrypt trail files. It generates a data encryption key (DEK) for each trail file, known as local key. An encrypted version of the local key is included in the trail file header and a master key is used to encrypt the data encryption key. This process is called encapsulation encryption.

In Oracle GoldenGate, a KMS can be used to manage cryptographic keys within an enterprise.

Topics:

• Why Use KMS to Store Oracle GoldenGate Encryption Keys?
  Oracle GoldenGate encryption of trail files is enhanced by using OKV or OCI KMS as the Key Management Service (KMS) to store master keys.
• Oracle Key Vault Capabilities
  Oracle GoldenGate supports Oracle Key Vault.

19.1.1 Why Use KMS to Store Oracle GoldenGate Encryption Keys?

Oracle GoldenGate encryption of trail files is enhanced by using OKV or OCI KMS as the Key Management Service (KMS) to store master keys.

Each time Oracle GoldenGate creates a trail file, it generates a new encryption key automatically. This encryption key encrypts the trail contents. The master key encrypts the encryption key. This process of encrypting encryption keys is known as key wrap and is described in standard ANS X9.102 from American Standards Committee.

Key management refers to managing cryptographic keys within an enterprise. It deals with generating, exchanging, storing, using, and replacing keys as required. A KMS also includes key servers, user procedures, and protocols. The security of the enterprise is dependent upon successful key management.

The advantages of using KMS with Oracle GoldenGate are:

• Centralized lifecycle management of master keys. You'll be able to generate and upload master keys to Oracle Key Vault directly using custom attributes and perform lifecycle maintenance tasks within the KMS directly.

• Oracle GoldenGate doesn't need to store the master keys locally and is not involved in the lifecycle management of the master keys.

• Oracle GoldenGate can leverage from the specialized KMS features that provide key management with several layers of security.

19.1.2 Oracle Key Vault Capabilities

Oracle GoldenGate supports Oracle Key Vault.

The following table provides the behavior and capabilities of Oracle Key Vault.

For more information about configuring Oracle Key Vault, 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

19.2 Managing Encryption Using OKV in Oracle GoldenGate Classic Architecture

This chapter describes the benefits of using OKV with Oracle GoldenGate Classic Architecture. It also describes the system requirements, processes and parameters available with Oracle GoldenGate for configuring Oracle Key Vault (OKV) with Oracle GoldenGate.

Topics:

• What is an Encryption Profile
  In Oracle GoldenGate, the encryption profile is used to define, which encryption technique to use.
• Prerequisites for Configuring OKV on Oracle GoldenGate
  Learn the prerequisites for setting up OKV with Oracle GoldenGate.
• Requirements for Setting up an Encryption Profile
  This topic describes the requirements when configuring an encryption profile in Oracle GoldenGate.
• Client Behavior Against Different Key States for Oracle Key Vault
  This topic describes the relative behavior of the of the reader or writer client processes depending on the different encryption key states.

19.2.1 What is an Encryption Profile

In Oracle GoldenGate, the encryption profile is used to define, which encryption technique to use.

An encryption profile is the configuration information that is used to retrieve a master key from a local wallet or a Key Management Service (KMS) such as OKV or OCI KMS. Encryption profile configuration is only available with Microservices Architecture.

Following methods are available for managing encryption of master keys:

• Local Wallets

• Key Management Systems:

  • Oracle Key Vault

  • Oracle Cloud Infrastructure

Each Extract and Replicat process is associated with an encryption profile. The default encryption profile is stored in the local wallet, if you haven't specified any other encryption profile as default.

If you use a different encryption profile, which uses a KMS, then it includes all the information necessary to connect and authenticate to the KMS server. It also contains the details necessary to retrieve a particular master key that will be used for encryption and decryption. Any KMS uses an authentication token to access their APIs. Oracle GoldenGate Microservices Architecture stores this access token as a credential. This credential is created using the encryption profile in Microservices Architecture.

Oracle Golden Gate processes need to make a request to the Key Management Service (KMS) each time a trail file is opened.

• For Oracle Key Vault (OKV), the encryption profile parameter time to live (TTL) is used to keep the master key on memory until TTL has been reached.

• In OCI KMS, the actual master key is never returned and instead the client sends the data to encrypt or decrypt. Thereafter, the server returns the result to the client.

An encryption profile is used by the Oracle GoldenGate processes to encrypt or decrypt depending on whether the processes are writing or reading trail files.

• Extract: Encrypt (writer)

• Replicat: Decrypt (Reader)

• Distribution Service Path (DISTPATH): Encrypt/Decrypt (Writer/Reader).

• LogDump: Decrypt (Reader)

See How to Configure an Encryption Profile in Step by Step Data Replication Using Oracle GoldenGate Microservices.

19.2.2 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 Install OKV Software Onto Endpoint 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.

19.2.3 Requirements for Setting up an Encryption Profile

This topic describes the requirements when configuring an encryption profile in Oracle GoldenGate.

You can create multiple encryption profiles within a deployment, but an Oracle GoldenGate process (Extract, Replicat, distribution path) can only use one encryption profile at a time. For distribution paths using filtering, decryption is done to apply the filters but the output trail file remains encrypted. In PASSTHRU, a distribution path will not attempt to use the encryption profile or decrypt the trail file unless explicitly specified.

Any of the existing encryption profiles within a deployment can be set as the default profile. This default profile is only relevant during the creation of an Extract, Replicat or Distribution Path processes. If an encryption profile is not explicitly specified during the creation of a process, the current default profile is assigned to the new process. Changing the default profile does not update the encryption profile assigned to any existing Oracle GoldenGate processes.

Note:

It is advised not to change the encryption profile or master key of a process that has already processed trail files.

The Administration Service web interface allows you to manage your encryption profiles. You cannot modify an encryption profile. If you need to change it, you must delete and add a new profile using the Administration Server. See How to Add an Encryption Profile in Step by Step Data Replication Using Oracle GoldenGate Microservices.

You can configure encryption profiles from the Administration Service or the Admin Client.

Tool to Set up Encryption Profile	Description
Administation Service	To configure the encryption profile using the Administration Server, see Administration Server: Profile Page.
Admin Client	The Admin Client commands used to set up the encryption profile for Extract, Replicat, and Distribution Path, include: ADD ENCRYPTIONPROFILE, ALTER ENCRYPTIONPROFILE, DELETE ENCRYPTIONPROFILE, INFO ENCRYPTIONPROFILE. In addition, the ADD or ALTER the Extract, DISTPATH, or Replicat commands have been modified to include the parameter ENCRYPTIONPROFILE encryption-profile-name. To know more, see Admin Client Command Line Interface Commands in Command Line Interface Reference for Oracle GoldenGate.

19.2.4 Client Behavior Against Different Key States for Oracle Key Vault

This topic describes the relative behavior of the of the reader or writer client processes depending on the different encryption key states.

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.