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.
