Streamlining TDE Key Management with Oracle Key Vault and Secure Endpoint Deployment

 

Intro

Streamlining TDE Key Management with Oracle Key Vault and Secure Endpoint Deployment

One of the core pillars of database security is robust encryption key management. Yet many organizations still store Transparent Data Encryption (TDE) keys locally, a practice that introduces significant risk because keys can be lost through disk corruption, system failure, or accidental mismanagement. Managing those keys manually across multiple Oracle and MySQL databases only compounds the challenge and increases the potential breach surface.

Oracle Key Vault (OKV) offers a modern alternative by centralizing the storage and lifecycle management of encryption keys, certificates, and secrets in a secure, policy‑driven environment that communicates with each database over KMIP. Using OKV translates to reduced development time, improved security posture, and compliance with data‑protection standards. While there are associated costs for using the service, the benefits of enhanced security and streamlined operations often outweigh the expenses.

To accelerate adoption at scale, OKV exposes a RESTful API that lets you automate installation and registration of endpoint software, dramatically shortening the time required to bring hundreds of database servers under centralized key management. For added protection, you can restrict the API to trusted IP ranges during rollout and disable the reset functionality once onboarding is complete, further narrowing the attack surface.

The remainder of this post walks through a practical, script‑driven workflow that installs the endpoint client, registers it with OKV, and provisions a default wallet, laying the foundation for secure, compliant, and easily auditable encryption across your Oracle estate.

In this article, I will elaborate on how we can perform the EP installation via RESTful API calls.

Configure the OKV RESTful service

First, create a directory  /u01/app/oracle/okvapi to download the okvresetcli package. Additionally, create a wallet directory that will be used to download the OKV wallet files.

Proceed to download the REST API package using the curl command.

mkdir -p /u01/app/oracle/okvapi

[oracle@ora-01 okvapi]$ curl -O -k https://10.0.0.180:5695/okvrestclipackage.zip
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 4134k  100 4134k    0     0  96.1M      0 --:--:-- --:--:-- --:--:-- 96.1M

Once the download is complete, extract the package. This will create the required directory structure and files, including the configuration file that needs to be updated with OKV server details.

[oracle@ora-01 okvapi]$ ls -lrth
total 4.1M
-rw-r--r--. 1 oracle oinstall 4.1M Jun 13 14:36 okvrestclipackage.zip
[oracle@ora-01 okvapi]$ unzip okvrestclipackage.zip
Archive:  okvrestclipackage.zip
   creating: lib/
   creating: bin/
  inflating: bin/okv
  inflating: bin/okv.bat
   creating: conf/
  inflating: conf/okvrestcli_logging.properties
  inflating: conf/okvrestcli.ini
  inflating: lib/okvrestcli.jar
[oracle@ora-01 okvapi]$ 

Next, update the okvrestcli.ini file located in the conf directory with the appropriate OKV server details. Additionally, ensure that the client_wallet parameter is included and correctly set.

[oracle@ora-01 conf]$ cat okvrestcli.ini
#Provide absolute path for log_property, okv_client_config properties
[Default]
log_property=/u01/app/oracle/okvapi/conf/okvrestcli_logging.properties
server=10.0.0.180
okv_client_config=./conf/okvclient.ora
user=admin
client_wallet=/u01/app/oracle/okvapi/wallet

Create the wallet for the OKV RESTful API

If the client_wallet directory is already specified in the configuration file, the next step is to download the wallet from the Oracle Key Vault (OKV) server. This wallet is essential for secure communication between the client and OKV.

Before download, make sure to export the init location and execute "/u01/app/oracle/okvapi/bin/okv admin client-wallet add --client-wallet /u01/app/oracle/okvapi/wallet --wallet-user admin"

Step 1: Set the Configuration File Path

export JAVA_HOME=/u01/app/oracle/product/19.0.0/dbhome_1/jdk
export OKV_RESTCLI_CONFIG=/u01/app/oracle/okvapi/conf/okvrestcli.ini

Step 2: Initialize the Client Wallet

Run the following command to create the client wallet:

/u01/app/oracle/okvapi/bin/okv admin client-wallet add \
  --client-wallet /u01/app/oracle/okvapi/wallet \
  --wallet-user admin

You will be prompted to enter the password. Upon success, you should see:

export JAVA_HOME=/u01/app/oracle/product/19.0.0/dbhome_1/jdk
export OKV_RESTCLI_CONFIG=/u01/app/oracle/okvapi/conf/okvrestcli.ini
[oracle@ora-01 okvapi]$ /u01/app/oracle/okvapi/bin/okv admin client-wallet add --client-wallet /u01/app/oracle/okvapi/wallet --wallet-user admin
Password:
{
  "result" : "Success"
}
[oracle@ora-01 okvapi]$

Important Note:

This command will fail if the RESTful service is not enabled in OKV. By default, the REST service is disabled to maintain security.

Example of failure message:

[oracle@dbsdpl55 bin]$ /u01/app/oracle/okvapi/bin/okv admin client-wallet add --client-wallet /u01/app/oracle/okvapi/wallet --wallet-user admin
Password:
{
  "result" : "Failure",
  "message" : "REST service is disabled"
}
[oracle@dbsdpl55 bin]$

Solution

For testing purposes, you may temporarily enable the REST service for all IP addresses. However, in a production environment, it is strongly recommended to enable the service only for specific, trusted targets. Once the installation and configuration are complete, you can disable the REST service again to maintain a secure setup.

Verifying the OKV RESTful API Installation

Use the following commands to verify the REST CLI and retrieve server details:

[oracle@ora-01 okvapi]$ $OKV_HOME/bin/okv
{
  "restCLIVersion" : "21.10.0.0.0"
}

[oracle@ora-01 okvapi]$  $OKV_HOME/bin/okv server info get
{
  "result" : "Success",
  "value" : {
    "caCertificateExpirationDate" : "2028-05-19 18:59:37",
    "cpuCores" : "2",
    "deploymentType" : "Cluster",
    "diskInGB" : "3695",
    "fraInGB" : "160",
    "installDate" : "2025-05-20 18:59:54",
    "memoryInKB" : "16365128",
    "platformCertificatesExpirationDate" : "2027-03-12 02:48:20",
    "serverCertificateExpirationDate" : "2026-05-20 19:03:31",
    "serverTime" : "2025-06-13 14:41:53",
    "version" : "21.10.0.0.0"
  }
}

This confirms that the OKV RESTful API is correctly installed and communicating with the server.

Configuring Endpoint (EP) via REST API

To configure OKV using RESTful calls, follow the steps below:

Prerequisites

Before provisioning the endpoint, ensure the following directory structure exists under the wallet_root:

mkdir -p /u01/app/oracle/admin/ORCL/wallet_root/tde        # Location for TDE keys
mkdir -p /u01/app/oracle/admin/ORCL/wallet_root/okv        # Location for OKV endpoint
mkdir -p /u01/app/oracle/admin/ORCL/wallet_root/tde_seps   # Location for External SSO Key

Step-by-Step Configuration

1. Create the Endpoint

/u01/app/oracle/okvapi/bin/okv admin endpoint create --endpoint EP_ORCL --description "$HOSTNAME, $(hostname -i)" --type ORACLE_DB --platform LINUX64 -- Create end point 

Sample Output:

export OKV_RESTCLI_CONFIG=/u01/app/oracle/okvapi/conf/okvrestcli.ini
export JAVA_HOME=/u01/app/oracle/product/19c/dbhome_1/jdk

[oracle@ora-01 wallet_root]$ /u01/app/oracle/okvapi/bin/okv admin endpoint create --endpoint EP_ORCL --description "$HOSTNAME, $(hostname -i)" --type ORACLE_DB --platform LINUX64
{
  "result" : "Success",
  "value" : {
    "status" : "PENDING",
    "locatorID" : "CBB0383C-CC14-4EA4-BF75-01981C522F74"
  }
}
[oracle@ora-01 wallet_root]$

After creating the endpoint, verify its status in the OKV console; it should display as "REGISTERED". To complete the endpoint setup, you must proceed with the provisioning step.

2. Set the Default Wallet for the Endpoint

/u01/app/oracle/okvapi/bin/okv manage-access wallet set-default \
  --wallet WLT_ORCL \
  --endpoint EP_ORCL

3. Provision the Endpoint

/u01/app/oracle/okvapi/bin/okv admin endpoint provision \
  --endpoint EP_ORCL \
  --location /u01/app/oracle/admin/ORCL/wallet_root/okv \
  --auto-login FALSE

Post-Configuration

Once the endpoint is created, you can verify its status in the OKV console. The endpoint status should change to "ENROLLED" after successful provisioning. This completes the REST-based configuration of an Oracle Database endpoint with OKV.

Conclusion

Configuring Oracle Key Vault (OKV) using RESTful API provides a secure, automated, and centralized approach to managing encryption keys for Oracle databases. By following the steps outlined for setting up the configuration, creating the required directories, defining the endpoint, associating the default wallet, and provisioning the endpoint, you establish a robust foundation for TDE and other security integrations.

Always ensure the RESTful service is enabled securely, especially in production environments, by restricting access to trusted IPs. Once the configuration is verified and functional, you can disable the REST service to further harden your setup.

This approach not only simplifies key lifecycle management but also enhances compliance and operational security across your Oracle infrastructure.