Oracle Key Vault Integration Accelerator

Oracle Key Vault provides accelerators to quickly spin up integration of use-cases with Key Vault. The accelerators can be used as provided or extended to suit application needs.

You can download an integration accelerator from the Oracle Key Vault management console. Oracle Key Vault provides an integration accelerator for:

Centralizing the Management of Oracle GoldenGate Passwords

Starting with the 21.11 release, Oracle Key Vault provides the GoldenGate Password Plugin. You can use this feature to store Oracle GoldenGate passwords in Oracle Key Vault.

About Centralizing the Management of Oracle GoldenGate Passwords

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.

Note: Oracle Key Vault systems should be up and running for Oracle GoldenGate systems to fetch passwords from Oracle Key Vault.

Storing Oracle GoldenGate Passwords in Oracle Key Vault

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

At a high level, the process of storing Oracle GoldenGate passwords in Oracle Key Vault can be summarized as follows:

  1. The Oracle GoldenGate administrator uses the RESTful services utility 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.

Note: This password security through Oracle Key Vault also offers protection to Oracle GoldenGate implementations that replicate non-Oracle databases.

Downloading the Password Plugin

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

To configure the passwords, 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 download_integration_accelerator.png follows

    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.

Prerequisites

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.

Uploading Oracle GoldenGate Database User Passwords to Oracle Key Vault

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

Uploading database user passwords may be performed by using a separate endpoint that has read, write, and manage access privileges to the wallet where passwords are uploaded.

At a minimum, the endpoint where Oracle GoldenGate processes fetches passwords by using the libokvoggdbpwd.so plugin library must have read access privileges to the wallet where the passwords were uploaded.

  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 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.

Configuring the Oracle Key Vault Shared Library as a Password Plugin for Oracle GoldenGate

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

Perform the steps in this topic to enable Oracle GoldenGate to fetch the database user password (secret data) from Oracle Key Vault by using the shared library libokvoggdbpwd.so.

Set the SM_USERNAME (Service Manager username), SM_PASSWORD (Service Manager password), HOST_SERVER (URL of GoldenGate deployment), and SM_PORT (Service Manager port#) variables in your environment to run the following commands.

  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
2025-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.

Key Management for Oracle DBMS_CRYPTO Integration Accelerator

Starting with release 21.10, Oracle Key Vault provides the Key Management for Oracle DBMS_CRYPTO integration accelerator to manage encryption keys used with DBMS_CRYPTO operations in Oracle Key Vault.

Oracle DBMS_CRYPTO package provides a PL/SQL interface to perform encrypt and decrypt operations. PL/SQL applications need to securely manage encryption keys used with DBMS_CRYPTO operations. Using this integration accelerator, you can manage the symmetric keys used with Oracle DBMS_CRYPTO operations in Oracle Key Vault. This integration accelerator package provides a PL/SQL wrapper built over an Oracle Key Vault JAVA SDK program.

Downloading Key Management for Oracle DBMS_CRYPTO Integration Accelerator

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 2110_dbms_crypto.png follows

    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.

Using Key Management for Oracle DBMS_CRYPTO Integration Accelerator

Learn how to use Key Management for DBMS_CRYPTO integration accelerator.

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.

Related Topics

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.

  1. Ensure that the JAVA_HOME environment variable points to the Java Development Toolkit (JDK) location.

  2. Set the CLASSPATH to contain the Oracle Key Vault Java SDK jar $OKV_HOME/jsdk/lib/okvjsdk.jar.

    Set the CLASSPATH in Bash UNIX:

    export CLASSPATH=$CLASSPATH:$OKV_HOME/jsdk/lib/okvjsdk.jar

  3. Ensure that the current directory ‘.’ is also part of CLASSPATH. If not, then add the current directory at the beginning of CLASSPATH.

    In Bash UNIX shell, set as follows:

    export CLASSPATH=.:$CLASSPATH

  4. Compile the KeyManager.java file.

    Set the current directory to the directory where you extracted the okv_key_management_dbms_crypto.zip file.

    Compile the KeyManager.java in Bash UNIX:

    cd folder_path
javac KeyManager.java

  5. Log in to Oracle Database as the sys user and set up the database user.

    Determine the default table space default_tablespace of the database user db_username using the following query:

    SQL> select default_tablespace from dba_users where username = db_username;

    Note: Ensure db_username is in upper case.

    Grant the following permissions to db_username:

    SQL> grant execute on sys.dbms_crypto to db_username;
SQL> grant create session to db_username;
SQL> grant create procedure, create table to db_username;
SQL> alter user db_username quota 100M on default_tablespace;
SQL> commit;
SQL> exit;

  6. Ensure that you add the $ORACLE_HOME/bin directory to the PATH environment variable.

  7. Load the Java class file KeyManager.class and the dependent JAR file okvjsdk.jar to Oracle Database as the database user db_username, database user password db_pswd, and database name db_name.

    loadjava -user db_username/db_pswd@db_name -verbose $OKV_HOME/jsdk/lib/okvjsdk.jar
cd folder_path
loadjava -user db_username/db_pswd@db_name -verbose KeyManager.class

  8. Log in to the database as the sys user and run the following SQL file by passing the database user db_username and actual value of OKV_HOME as arguments.

    SQL> @folder_path/setup_java_permissions.sql db_username OKV_HOME;

  9. Log in to the database as the sys user and grant permissions required to allow the database user db_username to establish a secure socket connection with Oracle Key Vault:

    SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', 'Oracle Key Vault IP Address:Port#', 'connect,resolve' );
SQL> commit;
SQL> exit;

    Note: In a multi-master cluster deployment, grant the permission for each cluster node using the IP address and port-number. Ensure that the input db_username is in upper case for these commands.

    The IP address and port-number information is available in the $OKV_HOME/conf/okvclient.ora file.

    For example, the endpoint configuration file $OKV_HOME/conf/okvclient.ora for a 3-node Oracle Key Vault cluster with IP addresses 100.100.100.101, 100.100.100.102 and 100.100.100.103 for the respective nodes is similar to the following:

    SERVER=100.100.100.101:5696/
CN=server_cert,OU=Key_Vault,O=Oracle,L=Redwood_City,ST=California,C=us,100.100.100.102:5696/
CN=node_2_cert,OU=Key_Vault,O=Oracle,L=Redwood_City,ST=California,C=us
READ_SERVER=100.100.100.103:5696/CN=node_3_cert,OU=Key_Vault,O=Oracle,L=Redwood_City,ST=California,C=us

    Extract the IP address and port details from the previous configuration file and run SQL commands as the sys user for the previous example cluster as follows:

    SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', '100.100.100.101:5696', 'connect,resolve' );
SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', '100.100.100.102:5696', 'connect,resolve' );
SQL> exec dbms_java.grant_permission( db_username, 'SYS:java.net.SocketPermission', '100.100.100.103:5696', 'connect,resolve' );
SQL> commit;
SQL> exit;

    Ensure that you change these permissions whenever there are changes to the Oracle Key Vault cluster node configuration, such as adding or deleting cluster nodes.

    For example, when a new cluster node 100.100.100.104 is added:

    SQL> exec dbms_java.grant_permission( db_username,'SYS:java.net.SocketPermission', '100.100.100.104:5696', 'connect,resolve' );
SQL> commit;
SQL> exit;

    When the cluster node 100.100.100.103 is removed:

    SQL> exec dbms_java.revoke_permission( db_username, 'SYS:java.net.SocketPermission','100.100.100.103:5696', 'connect,resolve' );
SQL> commit;
SQL> exit;

  10. Log in to the database with your database user name and password and grant the following permissions to the database user db_username to enable the database user to load the endpoint wallet under $OKV_HOME/ssl file when establishing a secure connection with Oracle Key Vault.

    SQL> exec dbms_java.grant_policy_permission( db_username, db_username, 'oracle.security.pki.OracleWalletPermission', 'load' );
SQL> exec dbms_java.grant_permission( db_username, 'db_username:oracle.security.pki.OracleWalletPermission', 'load', '' );
SQL> commit;
SQL> exit;

    Note: Ensure that the input db_username is in upper case for these commands.

  11. Connect to the database with your database user name and password and load the package okv_key_mgmt.pkb.

    SQL> @folder_path/okv_key_mgmt.pkb;
SQL> exit;

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.

The okv_key_mgmt package provides the following functions to integrate key management with Oracle Key Vault.

You can modify PL/SQL applications that perform symmetric key based crypto operations using DBMS_CRYPTO to fetch and use the keys from Oracle Key Vault using okv_key_mgmt package. This way, you can simplify the key management for your PL/SQL applications.

Review the supplied sample application dbms_crypto_using_okv_keymgmt.sql included with the integration accelerator to learn how to use key management functions of the okv_key_mgmt package.

You can run the sample application dbms_crypto_using_okv_keymgmt.sql included with the Key Management for DBMS_CRYPTO integration accelerator package.

  1. Log in to database with your user name and password to the configured database.

  2. Run the dbms_crypto_using_okv_keymgmt.sql file using the following command:

    SQL> @folder_path/dbms_crypto_using_okv_keymgmt.sql;

    Note:

    This SQL script works only for auto-login wallet of the installed Oracle Key Vault endpoint software. If your endpoint is password-protected, then set the password of your endpoint in the endpt_pswd variable that is present in this SQL script. Additionally, ensure that endpt_pswd is passed as an input to okv_key_mgmt package functions in the SQL script as follows:

    • -- create key : okv_key_mgmt.create_key(key_name, endpt_pswd);

    • -- fetch key : okv_key_mgmt.fetch_key(key_name, endpt_pswd);

    • -- destroy key : okv_key_mgmt.destroy_key(key_id, endpt_pswd);

    If you want to give a custom name for the key created in Oracle Key Vault, then set the name value in the key_name variable that is present in this SQL script. By default, the key name is passed as dbms_crypto_key to the create_key() and fetch_key() functions in the SQL script.

The Key Management for DBMS_CRYPTO integration accelerator provides basic functions to demonstrate the management of keys for PL/SQL application in Oracle Key Vault. You can modify the supplied Java SDK program KeyManager.java and PL/SQL wrapper package okv_key_mgmt.pkb to extend its functionality to cover more advanced usage.

Note: The modified version of the fetch_key() function and a new function destroy_key() are included in the okv_key_mgmt package starting with Oracle Key Vault 21.11. If you are using Oracle Key Vault 21.10, and you want to include the locate_key() function into the okv_key_mgmt package, then perform the steps in the topic Extending the Functionality of Key Management for Oracle DBMS_CRYPTO Integration Accelerator.

Transferring Objects Across Oracle Key Vault Cluster

Starting with the Oracle Key Vault 21.11 release, Oracle Key Vault includes a preview of the Key Transfer Across Oracle Key Vault Clusters Integration Accelerator. You can use this feature to transfer security objects from one Oracle Key Vault cluster to another.

About Transferring Objects Across Oracle Key Vault Clusters

As an Oracle Key Vault administrator, after a one-time setup, you can easily transfer security objects from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster using a temporary repository.

You can use this feature to transfer security objects to a highly protected target cluster intended for supporting business continuity.

You can transfer the following object types from the source cluster to the target cluster:

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

You can transfer individual objects by specifying their UUID, or transfer multiple objects at once using a wallet.

Note: This feature is in a preview state and may be modified in a future release.

Downloading the Key Transfer Package

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 2111_downloading_key_transfer_package.png follows

    Description of the illustration 2111_downloading_key_transfer_package.png

  3. At the top of the page, click the Download Integration Accelerator tab.

  4. In the Download Integration Accelerator page, select the Key Transfer Across OKV Clusters (Preview) 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.

Prerequisites

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 be 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 both 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 both 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 are used for storing downloaded security object files. Key material in the downloaded objects is also stored in an encrypted state.

    • Ensure that a file named object_register_details.json does not exist in the specified path. This default file stores temporary information regarding objects which are subsequently downloaded.

  6. Extract the contents of okv_key_transfer_across_clusters.zip into a separate folder.

    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:

      • SOURCE_OKV_RESTCLI_CONFIG: The absolute path of the okvrestcli.ini file from the RESTful services utility setup for the source cluster.

      • TARGET_OKV_RESTCLI_CONFIG: The absolute path of the okvrestcli.ini file from the RESTful services utility setup for the target cluster.

      • JAVA_HOME: The absolute path to the Java Runtime Environment (JRE) installation.

      • SOURCE_EP: The absolute path of the okvclient.ora file from the endpoint setup for the source cluster.

      • TARGET_EP: The absolute path of the okvclient.ora file from the endpoint setup for the target cluster.

      • LOG_DIR: The absolute path of the directory where logs should be stored.

    • okv_key_transfer.sh: Main script that you use for transferring security objects across Oracle Key Vault clusters by first downloading them from the source cluster and then uploading them to the target cluster. 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.

Preparing the Environment For Using the Key Transfer Package

Perform these steps to prepare the environment for using the Key Transfer Package.

  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

Performing the Transfer Process

Performing the transfer process involves the following stages:

  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. Perform this step only once.

  2. The objects (their values and attributes) are downloaded to an interim repository using 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. 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. There is no limit to the number of times this step can be performed.

  4. Destroy the transfer keys when you no longer need to use this setup to transfer objects. Perform this step when key transfer is no longer required.

To redo the transfer process, ensure that you perform the above steps in order from Step 1 - 4.

Transferring Keys from the Source to the Target Cluster

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

Note: You may be prompted to enter the password if the endpoints are password-protected.

  1. 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.

  2. Download the objects from the source cluster to the interim repository:

    ./okv_key_transfer.sh download --path <path> (--uuid <UUID> | --wallet <wallet_name>)

    In the above code, the path refers to the location of the interim repository.

    Object values are encrypted with the transfer keys to prevent any security risks. You can download individual objects by specifying their UUID, and multiple objects by specifying a wallet from the source cluster.

  3. Upload the downloaded files from the interim repository to the target cluster:

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

    For uploading individual objects, ensure that you specify their UUID.

    When uploading individual or multiple objects:

    • The interim repository path is mandatory.

    • Specifying the target wallet is optional. However, the upload will happen to the target wallet if its details are specified.

  4. Destroy the transfer key that you created during the setup of the transfer process:

    ./okv_key_transfer.sh cleanup

    Perform this step only once when the setup to transfer objects is no longer needed.

Note: In the rerun of steps 2 and 3, while all objects are downloaded, only objects which have not been uploaded previously or were missing in the target cluster are added. This ensures that only new objects are uploaded, thereby avoiding duplication.

Commands and Log Details in Various Scenarios

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

Commands

Logs

The log files that are in the <LOG_DIR>/okv_key_transfer_logs.txt file record the following details:

Log files are generated for the following operations:

Destroying the Wrap and Unwrap Keys

Destroy the transfer keys that wrap and unwrap object types.

This command destroys the keys in the source and target clusters.

./okv_key_transfer.sh cleanup

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