Intro
Streamlining TDE Key Management with Oracle Key Vault and Secure Endpoint Deployment
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
/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:
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"
}
}
Configuring Endpoint (EP) via REST API
Prerequisites
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
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]$
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.
