24 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. - 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. - 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.
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. - Storing Oracle GoldenGate Passwords in Oracle Key Vault
This topic summarizes the process of storing Oracle GoldenGate passwords in Oracle Key Vault. - Downloading the Password Plugin
Learn how to download the password plug-in from the Oracle Key Vault management console. - Prerequisites
The following prerequisites are required to centralize the management of passwords that are used by Oracle GoldenGate processes. - Uploading Oracle GoldenGate Database User Passwords to Oracle Key Vault
Perform these steps to upload Oracle GoldenGate Database User Passwords to Oracle Key Vault. - 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.
Parent topic: Oracle Key Vault Integration Accelerator
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.
- The Oracle GoldenGate administrator uses the REST software to upload Oracle GoldenGate passwords to Oracle Key Vault.
- 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.
Prerequisites
The following prerequisites are required to centralize the management of passwords that are used by Oracle GoldenGate processes.
Uploading Oracle GoldenGate Database User Passwords to Oracle Key Vault
Perform these steps to upload Oracle GoldenGate Database User Passwords to Oracle Key Vault.
libokvoggdbpwd.so
plugin library must have read access privileges to the wallet where the passwords were uploaded.
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.
libokvoggdbpwd.so
.
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.
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. - Using Key Management for Oracle DBMS_CRYPTO Integration Accelerator
Learn how to use Key Management for DBMS_CRYPTO integration accelerator.
Parent topic: Oracle Key Vault Integration Accelerator
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.
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. - 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 packageokv_key_mgmt
supplied by the integration accelerator in your PL/SQL applications.
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.
-
Enroll Oracle Database as an endpoint to Oracle Key Vault 21.10 or later, on which you intend to run the sample Oracle DBMS_CRYPTO application.
Note:
For more information see, About Endpoint Enrollment and Provisioning - Ensure that you have Java 8 or later.
- Ensure that Oracle Database is patched with the latest Oracle JVM.
-
Set the
OKV_HOME
environment variable appropriately.Note:
The$OKV_HOME
is the destination directory for the endpoint software that you specified with the-d
option during the endpoint installation. - Check if the
okvclient.ora
file is available and created as part of the endpoint enrollment. Theokvclient.ora
file is usually located at$OKV_HOME/conf/okvclient.ora
. -
Ensure that
okv_jsdk.zip
is unzipped under$OKV_HOME
.In Bash UNIX shell:$ cd $OKV_HOME $ unzip -o okv_jsdk.zip
Note:
For information about downloading the Oracle Key Vault Java SDK, see Oracle Key Vault Developer's Guide - Extract the contents of
okv_key_management_dbms_crypto.zip
to a separate folder.The
okv_key_management_dbms_crypto.zip
file contains the following:-
setup_java_permissions.sql
: This SQL script sets up the required Java security permissions and privileges for the database user. KeyManager.java
: This program creates, fetches, and destroys a symmetric key in Oracle Key Vault server by making use of APIs from Oracle Key Vault Java SDK.okv_key_mgmt.pkb
: A PL/SQL wrapper that invokes the Oracle Key Vault Java SDK API (throughKeyManager.java
) to perform create, fetch, and destroy operations of symmetric keys in Oracle Key Vault.dbms_crypto_using_okv_keymgmt.sql
: Oracle DBMS_CRYPTO use case for demonstrating key management in Oracle Key Vault using Java SDK.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 thatendpt_pswd
is passed as an input tookv_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 asdbms_crypto_key
to thecreate_key()
andfetch_key()
functions in the SQL script.README.txt
: Instructions to set up and run the sample Oracle DBMS_CRYPTO application.
-
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.
okv_key_mgmt
package provides the following functions to integrate key management with Oracle Key Vault.
create_key
: Creates a symmetric key in Oracle Key Vault. This is a wrapper function callingKeyManager.java:createKey()
which makes use of the Oracle Key Vault Java SDK APIs to create a symmetric key in Oracle Key Vault.fetch_key
: Fetches a symmetric key from Oracle Key Vault. This is a wrapper function callingKeyManager.java:fetchKey()
which makes use of the Oracle Key Vault Java SDK APIs to fetch a symmetric key in Oracle Key Vault.destroy_key
: Destroys a symmetric key in Oracle Key Vault. This is a wrapper function callingKeyManager.java:destroyKey()
which makes use of the Oracle Key Vault Java SDK APIs to destroy a symmetric key in 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.
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 thefetch_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, you can seamlessly transfer objects from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster, through a temporary repository. - Downloading the Key Transfer Package
To perform the transfer operation, download the Key Transfer Package from the Oracle Key Vault management console. - Prerequisites
The following prerequisites are required to transfer security objects from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster. - Preparing the Environment For Using the Key Transfer Package
This topic describes the stages of the transfer process from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster. - Performing the Transfer Process
This topic describes the steps to prepare the environment for using the Key Transfer Package. - 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. - Commands and Log Details in Various Scenarios
This topic describes the commands that you must run in various scenarios. - Destroying the Wrap and Unwrap Keys
Destroy the transfer keys that wrap and unwrap object types.
Parent topic: Oracle Key Vault Integration Accelerator
About Transferring Objects Across Oracle Key Vault Clusters
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.
Note:
This feature is in a preview state, and may be modified in a future release.Parent topic: Transferring Objects Across Oracle Key Vault Cluster
Downloading the Key Transfer Package
To perform the transfer operation, download the Key Transfer Package from the Oracle Key Vault management console.
Parent topic: Transferring Objects Across Oracle Key Vault Cluster
Prerequisites
The following prerequisites are required to transfer security objects from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster.
Parent topic: Transferring Objects Across Oracle Key Vault Cluster
Preparing the Environment For Using the Key Transfer Package
This topic describes the stages of the transfer process from a source Oracle Key Vault cluster to a target Oracle Key Vault cluster.
Parent topic: Transferring Objects Across Oracle Key Vault Cluster
Performing the Transfer Process
This topic describes the steps to prepare the environment for using the Key Transfer Package.
- 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. - 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.
- 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.
- The transfer keys are destroyed.
Parent topic: Transferring Objects Across Oracle Key Vault Cluster
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.Note:
In a rerun of the above steps, only new files from the source cluster are uploaded to the target cluster. This shortens the upload time as objects that were uploaded in the previous run are skipped.Parent topic: Transferring Objects Across Oracle Key Vault Cluster
Commands and Log Details in Various Scenarios
This topic describes the commands that you must run in various scenarios.
Commands
- To download a single object using its
UUID:
Objects are saved based on object type:$ ./okv_key_transfer.sh download --path <path> --uuid <UUID>
- Private keys are saved in <path>/pvt_keys.
- Other objects are saved in <path>/objects.
- To download all objects from a
wallet:
Objects are saved based on object type:$ ./okv_key_transfer.sh download --path <path> --wallet <wallet_name>
- Private keys are saved in <path>/<wallet_name>pvt_keys.
- Other objects are saved in <path>/<wallet_name>/objects..
Note:
- Files are named in the format:
<UUID>_object_register_details.txt
<path>
must be an absolute path where the objects are downloaded.
- Uploading a single object using its
UUID
$ ./okv_key_transfer.sh upload --path <path> --uuid <UUID> [--wallet <wallet_name>]
- The
uuid
is the unique identifier for the object in the source cluster. - The source file is removed from the
<path>
after it is uploaded.
Note:
The object that was previously downloaded as part of a wallet by using the--wallet
option is stored in a wallet-specific subdirectory. In such a scenario, use <path-to-source-wallet-name> as the--path
value when uploading a specific object by UUID:$ ./okv_key_transfer.sh upload --path <path-to-source-wallet-name> --uuid <UUID>
- The
- Uploading multiple
objects:
$ ./okv_key_transfer.sh upload --path <path> [--wallet <wallet_name>]
- All private keys are uploaded first from <path>/pvt_keys.
- All other objects are uploaded later from <path>/objects.
- Remove the files from <path> after the upload is complete.
Note:
Objects that were previously downloaded from a wallet by using the
--wallet
option are stored in a wallet-specific subdirectory. In such a scenario, use <path-to-source-wallet-name> as the--path
value during upload:Where:- <path> is the absolute path to the directory that contains details of objects downloaded from the source cluster.
- <wallet_name> is an optional parameter specifying the wallet on the target cluster where the object is added.
If a wallet is not specified during upload, objects will be uploaded to the endpoint's default wallet. If a default wallet is not defined for the endpoint, objects will be uploaded but not to any wallet.
Logs
<LOG_DIR>/okv_key_transfer_logs.txt
file record the following details:
- The type of operation.
- Details of the object(s) involved.
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.
Parent topic: Transferring Objects Across Oracle Key Vault Cluster
Destroying the Wrap and Unwrap Keys
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>
.
Parent topic: Transferring Objects Across Oracle Key Vault Cluster