This feature centralizes the management of passwords that are used by Oracle GoldenGate processes.

Oracle GoldenGate is an industry leader in data replication capabilities. To perform replication tasks, Oracle GoldenGate processes need to log in to the database using credentials stored in a local wallet (credential store). However,you may not be allowed to store password details locally, passwords need to be stored in a vault outside Oracle GoldenGate. Hence, an integration method is required to allow Oracle GoldenGate to retrieve the password and then connect to the database.

From version 23.5, Oracle GoldenGate includes a user-friendly plugin library that enables a customer to write custom code to retrieve credentials from a 3rd party vault and then return the credentials in a predefined API to Oracle GoldenGate. This feature includes libokvoggdbpwd.so, a library that can be configured in Oracle GoldenGate to manage passwords in Oracle Key Vault.

This topic summarizes the process of storing Oracle GoldenGate passwords in Oracle Key Vault.

1. The Oracle GoldenGate administrator uses the REST software to upload Oracle GoldenGate passwords to Oracle Key Vault.
2. When Oracle Key Vault receives a request for database credentials from Oracle GoldenGate through the libokvoggdbpwd.so plugin library, the password is fetched from Oracle Key Vault after successful backend validations, thus enabling Oracle GoldenGate to connect to the database by using a remotely stored password.

Learn how to download the password plug-in from the Oracle Key Vault management console.

1. Connect to the Oracle Key Vault management console.
   For example:

   https://192.0.2.254

   The login page is displayed. Do not log in.
2. In the lower-right corner under Login, click Endpoint Enrollment and Software Download.
   The Enroll Endpoint & Download Software page is displayed.
   

   
   Description of the illustration download_integration_accelerator.png

   
   
3. At the top of the page, click the Download Integration Accelerator tab.
4. Select the GoldenGate Password Plugin package from the Integration Accelerator drop-down menu.
5. Click Download.
6. Save the okv_ogg_password_plugin.zip file to a desired location. The file contains the following:
   • README.txt: Contains instructions to set up and configure the libokvoggdbpwd.so file as a plug-in library in Oracle GoldenGate.
   • libokvoggdbpwd.so: This file is configured as the plug-in library in the Oracle GoldenGate environment. To log in to the database, Oracle GoldenGate uses this plug-in library to fetch the database user password from Oracle Key Vault.

The following prerequisites are required to centralize the management of passwords that are used by Oracle GoldenGate processes.

1. Enroll an endpoint on Oracle Key Vault 21.11 or higher. Ensure it has read access as a minimum privilege on the wallet where you want to provision the Oracle Key Vault password plugin library. Ensure that you enroll an auto-login endpoint for this plugin to work.

   Note:

   The Oracle Key Vault password plugin library libokvoggdbpwd.so works only on the Linux platform. Hence, ensure that you select Linux as the platform when creating the endpoint. Also, ensure that Oracle GoldenGate is set up on a Linux platform. For more information see, About Endpoint Enrollment and Provisioning.
2. Ensure that you have Java 8 or above.
3. Ensure that the environment variable OKV_HOME is appropriately set. $OKV_HOME is the destination directory for endpoint software specified with the -d option during endpoint installation.
4. Ensure that the okvclient.ora file is available in the ${OKV_HOME}/conf/ path. It is created as part of endpoint enrollment.
5. Unzip the okv_ogg_password_plugin.zip file under $OKV_HOME.
   In Bash UNIX shell:

   $ unzip okv_ogg_password_plugin.zip -d $OKV_HOME

   The okv_ogg_password_plugin.zip file contains:

   • goldengate_password_plugin/lib/libokvoggdbpwd.so

     This library is built using Oracle Key Vault C-SDK and works only for auto-login endpoints of Oracle Key Vault.

     Tracing depends on the _TRACE_LEVEL parameter in the $OKV_HOME/conf/okvclient.ora file:

     • If set to 0, then no trace file will be generated from libokvoggdbpwd.so.
     • If set to > 0, then the trace file is generated in the directory specified in the _TRACE_DIR parameter of the $OKV_HOME/conf/okvclient.ora file. If the directory does not exist, then the trace file is generated in $OKV_HOME/log directory. The name of the trace file is okv_csdk_<pid>.trc.
   • goldengate_password_plugin/README

     Includes instructions to set up and configure the shared library libokvoggdbpwd.so as a password plugin for Oracle GoldenGate.

Perform these steps to upload Oracle GoldenGate Database User Passwords to Oracle Key Vault.

1. Ensure that okvrestclipackage.zip is unzipped file under $OKV_HOME.
   In Bash UNIX shell:

   $ unzip okvrestclipackage.zip -d $OKV_HOME

   $OKV_HOME can be the same endpoint that will fetch the password from Oracle Key Vault by using the libokvoggdbpwd.so password plugin library or it can be a different endpoint.

   For information on downloading the Oracle Key Vault RESTful Services Utility, see the Oracle Key Vault RESTful Services Administrator's Guide.

2. Ensure that the JAVA_HOME environment variable points to the system where JDK 8 is located.
3. Ensure all steps are complete to set up the Oracle Key Vault RESTFul Services Utility for uploading the database user password as secret data to Oracle Key Vault.
4. Upload the database user password (secret data) used by Oracle GoldenGate to Oracle Key Vault.
   In Bash UNIX shell:

   $ cd $OKV_HOME/bin
   $ okv managed-object secret register --type PASSWORD --object 
   <path_to_file_having_db_password> --activation-date now --wallet 
   <wallet_name> --custom-attribute '[ "x-OGG-DBPwd-
   Domain:<db_user_domain>","x-OGG-DBPwd-Alias:<db_user_alias>","x-
   OGG-DBPwd-UserId:<db_user_id>","x-OKV-Obj-
   Version:<object_version#>" ]'
   

   Mandatory Inputs:

   • <path_to_file_having_db_password>: The path of the object file containing the Oracle GoldenGate database user password.

     This file can be deleted after the password is uploaded to Oracle Key Vault.

   • <db_user_domain>: The domain name of the database user.
   • <db_user_alias>: The alias of the database user.
   • <db_user_id>: The user ID of the database user.

   Optional Inputs:

   • <wallet_name>: The name of the wallet for which the endpoint should have appropriate access permissions (read, write, manage).
   • <object_version#>: The object version number. This value must be a positive non-zero number, and maintains the history of passwords per database user. The plugin will fetch only the password having the highest version#. Hence, it is necessary to have a higher value than the previous version# for the latest password that is registered in Oracle Key Vault.

     If x-OKV-Obj-Version:<object_version#> is not specified while registering the database user password secret, then Oracle Key Vault server will determine the next higher version value and assign it as the value of the x-OKV-Obj-Version custom attribute.

   For example, after including values in all parameters, the command at the beginning of this step can be specified as follows:

   okv managed-object secret register --type PASSWORD --object 
   /tmp/db_user_password.txt --activation-date now --wallet 
   goldengate_wallet --custom-attribute '[ "x-OGG-DBPwd-
   Domain:OracleGoldenGate","x-OGG-DBPwd-Alias:ggadmin","x-OGG-DBPwd-
   UserId:ggadmin@//dbms:1521/ORCLPDB1","x-OKV-Obj-Version:1" ]'

   Output similar to the following will be displayed:

   {
        "result": "Success",
        "value": {
         "uuid": "EIC34EBE-99D1-4F15-93D8-1B7513DD8634"
         }
   }
   

   It is mandatory to perform this step for all database user credentials consumed by Oracle GoldenGate.

   Apart from the output displayed above, additional confirmation can be viewed in Oracle Key Vault as follows:

   From the Reports tab, when you click Audit Trail in the left pane, the following records are displayed with the indicated values in the Operation column:

   • Register: This confirms that the Oracle GoldenGate database password was successfully registered as a secret.
   • Locate: To indicate that the endpoint attempted to locate the credentials.
   • Get: To indicate that the credentials were successfully fetched by the endpoint.

   Note:

   To debug any issues that may arise with the libokvoggdbpwd.so plugin library, in the okvclient.ora file, configure values in the following parameters on the Oracle Key Vault deployment endpoint:

   • _TRACE_DIR: Specify a directory path where trace files will be placed.
   • _TRACE_LEVEL: Set the value of this parameter to 16.

This topic describes the steps to enable Oracle GoldenGate to fetch the database user password (secret data) from Oracle Key Vault.

1. Place the shared library $OKV_HOME/goldengate_password_plugin/lib/libokvoggdbpwd.so in the path <Oracle GoldenGate Service Manager Home>/var/lib/plugins/.

   Oracle GoldenGate has no restrictions on the library file name. However, the plugin will only pick up the first file in the path. Hence, ensure that only the libokvoggdbpwd.so exists, and previously used libraries are deleted.

2. Start the plugin service.
   If the Pluginsrvr is not added as part of the deployment, then the following POST command adds it in a running state.
   In Bash UNIX shell:

   $ curl -k -u $SM_USERNAME:$SM_PASSWORD 
   $HOST_SERVER:$SM_PORT/services/v2/deployments/ServiceManager/services/pluginsrvr 
   -X POST -d '{ "config":"external", "critical":true, "status":"running", "enabled":true }'

   If the Pluginsrvr is added as part of the deployment in a stopped state, then the following PATCH command will start it.
   In Bash UNIX shell:

   $ curl -k -u $SM_USERNAME:$SM_PASSWORD 
   $HOST_SERVER:$SM_PORT/services/v2/deployments/ServiceManager/services/pluginsrvr -X PATCH -d '{ "enabled":true, "status":"running" }'

3. Activate the plugin copied under <Oracle GoldenGate Service Manager Home>/var/lib/plugins/ as a new service under Service Manager.
   In Bash UNIX shell:

   $ curl -ksvu $SM_USERNAME:$SM_PASSWORD 
   $HOST_SERVER:$SM_PORT/services/v2/deployments/ServiceManager/services/pluginsrvr 
   -XPOST --data '{ "$schema":"ogg:service", "config":"external", "enabled":true, "critical":true, "status":"running" }'

4. In the Service Manager, configure Oracle Key Vault environment variables that are required for the libokvoggdbpwd.so library.
   In the following command, ensure that you substitute the OKV_HOME environment variable value for <value of OKV_HOME env variable>,where OKV_HOME is the endpoint software location which is provisioned for Oracle GoldenGate process(es) to fetch the database user password from Oracle Key Vault.
   In Bash UNIX shell:

   $ curl -ksvu $SM_USERNAME:$SM_PASSWORD 
   $HOST_SERVER:$SM_PORT/services/v2/deployments/ServiceManager -X 
   PATCH -H 'Accept: application/json' -H 'X-Requested-With: 
   XMLHttpRequest' -H 'Content-Type: application/json' --data-raw '{ 
   "environment":[{"name":"OKV_HOME","value":"<value of OKV_HOME env variable>"}] }' --compressed --insecure

5. Restart the Service Manager.
   In Bash UNIX shell:

   $ curl -ksvu $SM_USERNAME:$SM_PASSWORD 
   $HOST_SERVER:$SM_PORT/services/v2/deployments/ServiceManager -X 
   PATCH -H 'Accept: application/json' -H 'X-Requested-With: 
   XMLHttpRequest' -H 'Content-Type: application/json' --data-raw '{ 
   "status":"restart" }' --compressed –insecure

6. Wait for about 20 seconds for the Service Manager to restart.
   To ensure that Oracle Key Vault environment variables are configured in the Service Manager, log in to the Web interface of the Service Manager deployment using $SM_USERNAME and $SM_PASSWORD, navigate to Deployments > ServiceManager > Configuration, and then check the Environment Variables. If the environment variables area is not displayed, click + next to Environment Variables and add the environment variable OKV_HOME and its value.
7. Ensure that libokvoggdbpwd.so is part of the available plugins.
   In Bash UNIX shell:

   $ curl -ksvu $SM_USERNAME:$SM_PASSWORD 
   $HOST_SERVER:$SM_PORT/services/v2/installation/plugins -XGET

8. Run the adminclient command line utility that is used by Oracle GoldenGate to set up the database login credentials with the NOPASSWORD option and test that the connection to the database is successful.
   The following example illustrates this configuration:

   OGG (not connected) 1> CONNECT http://127.0.0.1:9011 AS oggadmin

   Using default deployment 'Deployment'

   OGG (http://127.0.0.1:9011 Deployment) 2> ALTER CREDENTIALSTORE ADD USER ggadmin@//dbms:1521/ORCLPDB1 ALIAS ggadmin NOPASSWORD 2024-04-02T18:34:14Z INFO OGG-15114 Credential store altered.
   OGG (http://127.0.0.1:9011 Deployment) 3> DBLOGIN USERIDALIAS ggadmin Successfully logged into database.
   OGG (http://127.0.0.1:9011 Deployment as ggadmin@ORCLCDB) 4>

   For more information or any additional steps required from Oracle GoldenGate, refer to Oracle GoldenGate's Authenticate the Database Connection Using the Database Password Plugin documentation.

You can download the Key Management in Oracle DBMS_CRYPTO integration accelerator from the Oracle Key Vault management console.

1. Connect to the Oracle Key Vault management console.

   For example:

   https://192.0.2.254

   The login page to the Oracle Key Vault management console appears. Do not log in.
2. In the lower-right corner of the login page under Login, click Endpoint Enrollment and Software Download.
   The Enroll Endpoint & Download Software page appears.

   
   Description of the illustration 2110_dbms_crypto.png

3. At the top of the page, click the Download Integration Accelerator tab.
4. In the Download Integration Accelerator page, select Key Management for DBMS_CRYPTO package from the Integration Accelerator drop-down menu.
5. Click Download.
6. Save the okv_key_management_dbms_crypto.zip file to a desired location.

• Prerequisites for Using Key Management for Oracle DBMS_CRYPTO Integration Accelerator
  Before you start working with the Key Management for Oracle DBMS_CRYPTO Integration Accelerator, ensure that you meet these prerequisites.
• Preparing the Environment for Using Key Management for Oracle DBMS_CRYPTO Integration Accelerator
  Ensure that you prepare the Oracle Database environment with the necessary permissions to run the Key Management for Oracle DBMS_CRYPTO Integration Accelerator.
• Using Key Management for Oracle DBMS_CRYPTO Integration Accelerator in a PL/SQL Application
  You can now use the PL/SQL package okv_key_mgmt supplied by the integration accelerator in your PL/SQL applications.

As an Oracle Key Vault administrator, you can seamlessly transfer objects from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster, through a temporary repository.

This feature enables you to have a secure backup of your cluster, and simultaneously enables you to transfer your objects periodically to the target cluster.

This feature benefits organizations as the operation of transferring objects across Oracle Key Vault clusters is automated and simplified.

The following object types can be transferred from source to target clusters:

• Symmetric Keys
• Private Keys
• Public Keys
• Opaque Objects
• Certificates
• Certificate Requests
• Secrets

All attributes of the transferred objects, including KMIP and custom attributes, are preserved during the transfer process.

While you can transfer individual objects by specifying their UUID, you can transfer multiple objects using a wallet.

To perform the transfer operation, download the Key Transfer Package from the Oracle Key Vault management console.

1. Connect to the Oracle Key Vault management console.
   For example:

   https://192.0.2.254

   The login page is displayed. Do not log in.
2. In the lower-right corner under Login, click Endpoint Enrollment and Software Download.
   
   
   Description of the illustration 2111_downloading_key_transfer_package.png
   
   
3. At the top of the page, click the Download Integration Accelerator tab.
4. Select the okv_key_transfer_across_clusters.zip package from the Integration Accelerator drop-down menu.
5. Click Download.
6. Save the okv_key_transfer_across_clusters.zip file to a desired location.

The following prerequisites are required to transfer security objects from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster.

1. The source and target clusters must operate on the same version of Oracle Key Vault.
2. Verify that expect is installed and is available in your system path. Verify this by running:

   $ which expect

   If expect is not installed, then install the script:

   $ sudo yum install expect

   Add the path of the expect script to the PATH environment variable.
3. Endpoint setup:
   For the source and target clusters, ensure that an endpoint is provisioned, and that the endpoint has access to the required objects and wallets.
4. RESTful services utility setup:
   1. Ensure that the RESTful services utility is set up for the source and target clusters. Refer to the RESTful Services Administrator's Guide for setup instructions.
   2. Configure the RESTful services utility for both clusters to use their respective endpoints.
   3. In the RESTful services utility configuration file okvrestcli.ini, set the okv_client_config setting under the [Default] profile as indicated below:

      okv_client_config=<absolute path of the okvclient.ora file of the endpoint>

      Note:

      Ensure that all the paths specified in okvrestcli.ini are absolute. For example: log_property, okv_client_config, and so on.
5. Directory and file naming restrictions:
   While downloading, ensure that directories named as objects or pvt_keys do not exist at the path specified before downloading. When running the script, these directories:
   1. Are used for storing downloaded security object files. Key material in the downloaded objects is also stored in an encrypted state.
   2. Ensure that a file named object_register_details.json does not exist at the specified path. This default file stores temporary information.
6. Download the okv_key_transfer_across_clusters.zip file and extract all files that it contains.

   $ unzip okv_key_transfer_across_clusters.zip

   The okv_key_transfer_across_clusters.zip file contains:

   • okv_key_transfer.ini - Includes the following parameters and the absolute path of specified files or installations:
   1. SOURCE_OKV_RESTCLI_CONFIG: The okvrestcli.ini file in the source cluster.
   2. TARGET_OKV_RESTCLI_CONFIG: The okvrestcli.ini file in the target cluster.
   3. JAVA_HOME: The JDK/JRE installation.
   4. SOURCE_EP: The okvclient.ora file of the source cluster endpoint.
   5. TARGET_EP: The okvclient.ora file of the target cluster endpoint.
   6. LOG_DIR: The directory where logs are stored.
   • okv_key_transfer.sh: This script file transfers security objects across Oracle Key Vault clusters. It downloads objects from a source cluster and then uploads them to a target cluster.
   • README.txt: Instructions to setup and perform key transfer operation.

This topic describes the stages of the transfer process from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster.

1. Ensure that the JAVA_HOME environment variable points to the Java Development Toolkit (JDK) location.
2. Ensure that the okv_key_transfer.sh script has execution privileges: $ chmod u+x ./okv_key_transfer.sh

   $ chmod u+x ./okv_key_transfer.sh

This topic describes the steps to prepare the environment for using the Key Transfer Package.

1. Create a transfer key in the source cluster and copy the key to the target cluster. The transfer key wraps (encrypts) object types in the source cluster that are transferred to the target cluster, where they are unwrapped (decrypted). The okv_key_transfer.sh file creates the transfer key.
2. The objects (their values and attributes) are downloaded to an interim repository with the help of the source cluster’s endpoint software. The transfer key then encrypts downloaded object values. There is no limit to the number of times this step can be performed.
3. From the interim repository, the objects are uploaded to the target cluster through the endpoint software of the target cluster. Additionally, objects that were uploaded previously are not uploaded in the current run of the upload process. After the upload process, the files are deleted from the interim repository.
4. The transfer keys are destroyed.

The source and target endpoints must be on the same computer where the following steps are performed.

1. Use the RESTful utility and the endpoint utility to connect to the Oracle Key Vault server.
2. Run the following command to create the transfer key in the source and target clusters:

   ./okv_key_transfer.sh init

   The following text is displayed to indicate that the transfer keys are successfully created:

   Created keys in source and target cluster.

3. Download the files from the source cluster to the interim repository:

   ./okv_key_transfer.sh download --path <path> [--uuid <UUID>] [--wallet <wallet_name>]

   Object values are encrypted with the transfer keys to prevent any security risks.
4. Upload the downloaded files from the interim repository to the target cluster:

   ./okv_key_transfer.sh upload --path <path> [--uuid <UUID>] [--wallet <wallet_name>]

   The private keys are uploaded first followed by the objects.
5. Destroy the transfer key that you created during the setup of the transfer process:

   ./okv_key_transfer.sh cleanup

This topic describes the commands that you must run in various scenarios.

Log files are generated for the following operations:

• Object download: In the event of a failure, the object UUID and reason for the failure are recorded.
• Full wallet download : The log entry includes:
  • The number of objects in the wallet.
  • Failed objects (if any) and the reason for failure.
  • The number of objects downloaded successfully.
• Object Upload: In the event of a failure, the object UUID and reason for the failure are recorded.
• Full wallet upload: The log entry includes:
  • Failed objects (if any) and the reasons for failure.
  • The target wallet (if specified).
  • The number of objects uploaded successfully and skipped objects.

Destroy the transfer keys that wrap and unwrap object types.

$ ./okv_key_transfer.sh cleanup

Ensure that any remaining object files which were not uploaded are deleted from <path>.