Gian's Database Security Blog

How to configure Oracle TDE, straight to OKV

Published by

giansartor

on

More often than not, when I am talking with customers about TDE key management with Oracle Key Vault, TDE is already in place and the conversation is focused around migrating the keys and the keystore to OKV. But what about those new databases that aren’t yet encrypted? Or, perhaps you are new to TDE and you decided to rollout TDE and OKV at the same time; do you need to configure TDE with a local wallet first and then migrate the keys and the keystore or is there an easier way?

It is entirely possible and perhaps preferred to do TDE straight to OKV because the process is a little more streamlined with a few less steps, and arguably a little more secure because you’re not leaving old TDE master keys lying around in wallets on the database filesystem.

The instructions below will focus on the TDE configuration and assume you already have your Oracle Key Vault server installed and configured.

Start by creating the directory structure for your wallet_root:

oracle@ora23ai-0108 wallet]$ pwd
/u01/app/oracle/admin/orcl/wallet

[oracle@ora23ai-0108 wallet]$ mkdir tde okv tde_seps

[oracle@ora23ai-0108 wallet]$ ll
total 0
drwxr-xr-x. 2 oracle oinstall 6 Jan  9 19:36 okv
drwxr-xr-x. 2 oracle oinstall 6 Jan  9 19:36 tde
drwxr-xr-x. 2 oracle oinstall 6 Jan  9 19:36 tde_seps
[oracle@ora23ai-0108 wallet]$

Next, set the wallet_root parameter and restart the database:

// set wallet_root for the database //
SQL> alter system set wallet_root='/u01/app/oracle/admin/orcl/wallet' scope=spfile;

System altered.

SQL>

// restart the database //
SQL> shutdown immediate
Database closed.
Database dismounted.
ORACLE instance shut down.
SQL> startup
ORACLE instance started.

Total System Global Area 4949275264 bytes
Fixed Size		    9187968 bytes
Variable Size		 1056964608 bytes
Database Buffers	 3875536896 bytes
Redo Buffers		    7585792 bytes
Database mounted.
Database opened.
SQL> show parameter root

NAME				     TYPE	 VALUE
------------------------------------ ----------- ------------------------------
wallet_root			     string	 /u01/app/oracle/admin/orcl/wallet

At this point, login to your OKV console and complete the following list of tasks. Alternatively, use the OKV RESTful services interface to comple them:

  1. Register one or more Endpoints
    • Copy the new Enrollment Token to your notepad
  2. Create a Virtual Wallet
  3. Set the new Virtual Wallet as the default wallet for the Endpoint
  4. Enroll the Endpoint using the Enrollment Token
  5. Download the okvclient.jar file
  6. Copy the jar file to the “okv” directory under the wallet_root

Next, install the OKV client as well as the PKCS library:

[oracle@ora23ai-0108 okv]$ java -version
java version "21.0.5" 2024-10-15 LTS
Java(TM) SE Runtime Environment (build 21.0.5+9-LTS-239)
Java HotSpot(TM) 64-Bit Server VM (build 21.0.5+9-LTS-239, mixed mode, sharing)

[oracle@ora23ai-0108 okv]$ pwd
/u01/app/oracle/admin/orcl/wallet/okv

[oracle@ora23ai-0108 okv]$ ls
okvclient.jar

[oracle@ora23ai-0108 okv]$ java -jar okvclient.jar
Detected JAVA_HOME: /usr/lib/jvm/jdk-21.0.5-oracle-x64
Enter new Key Vault endpoint password (<enter> for auto-login): <endpoint_password>
Confirm new Key Vault endpoint password: <endpoint_password>
The endpoint software for Oracle Key Vault installed successfully.
Deleted the file : /u01/app/oracle/admin/orcl/wallet/okv/okvclient.jar

[oracle@ora23ai-0108 okv]$ cd bin
[oracle@ora23ai-0108 bin]$ ls
ep_healthcheck.sh  okveps.x64  okv_ssh_ep_lookup_authorized_keys  okvutil  root.sh

[oracle@ora23ai-0108 bin]$ pwd
/u01/app/oracle/admin/orcl/wallet/okv/bin

[oracle@ora23ai-0108 bin]$ sudo su -
Last login: Thu Jan  9 19:55:49 GMT 2025 on pts/0

[root@ora23ai-0108 ~]# /u01/app/oracle/admin/orcl/wallet/okv/bin/root.sh
Creating directory: /opt/oracle/extapi/64/hsm/oracle/1.0.0/
Copying PKCS library to /opt/oracle/extapi/64/hsm/oracle/1.0.0/
Setting PKCS library file permissions
Installation successful.

[root@ora23ai-0108 ~]# exit
logout

Check the Virtual Wallet contents in OKV. It should only have the template file in there right now, nothing else.

[oracle@ora23ai-0108 bin]$ ./okvutil list
Enter Oracle Key Vault endpoint password:
Unique ID                               Type            Identifier
ACEA4BA4-3483-4A62-A0E9-65999FC11FCF	Template	Default template for DB1923_0108

Create the local autologin keystores to store the endpoint password. Use the same password for this command that you used when you installed the endpoint software earlier:

[oracle@ora23ai-0108 ~]$ sqlplus / as sysdba

SQL*Plus: Release 19.0.0.0.0 - Production on Thu Jan 9 20:00:12 2025
Version 19.23.0.0.0

Copyright (c) 1982, 2023, Oracle.  All rights reserved.


Connected to:
Oracle Database 19c Enterprise Edition Release 19.0.0.0.0 - Production
Version 19.23.0.0.0

SQL> administer key management add secret '<endpoint_password>' for client 'OKV_PASSWORD' to local auto_login keystore '/u01/app/oracle/admin/orcl/wallet/tde';

keystore altered.

SQL> administer key management add secret '<endpoint_password>' for client 'OKV_PASSWORD' to local auto_login keystore '/u01/app/oracle/admin/orcl/wallet/tde_seps';

keystore altered.

SQL> !ls -l /u01/app/oracle/admin/orcl/wallet/tde
total 4
-rw-------. 1 oracle oinstall 3606 Jan  9 20:06 cwallet.sso

SQL> !ls -l /u01/app/oracle/admin/orcl/wallet/tde_seps
total 4
-rw-------. 1 oracle oinstall 3606 Jan  9 20:06 cwallet.sso

Set the tde_configuration parameter in the database:

SQL> alter system set tde_configuration = "keystore_configuration=OKV|FILE" scope=BOTH;

System altered.

SQL> show parameter tde

NAME				     TYPE	 VALUE
------------------------------------ ----------- ------------------------------
one_step_plugin_for_pdb_with_tde     boolean	 FALSE
tde_configuration		     string	 keystore_configuration=OKV|FILE

SQL> !cat wstatus.sql
set lines 200
column WRL_PARAMETER format a40
select * from v$encryption_wallet;

SQL> @wstatus.sql

WRL_TYPE	     WRL_PARAMETER			      STATUS			     WALLET_TYPE	  WALLET_OR KEYSTORE FULLY_BAC	   CON_ID
-------------------- ---------------------------------------- ------------------------------ -------------------- --------- -------- --------- ----------
FILE		     /u01/app/oracle/admin/orcl/wallet/tde/   OPEN_NO_MASTER_KEY	     LOCAL_AUTOLOGIN	  SINGLE    NONE     UNDEFINED		1
OKV							      OPEN_NO_MASTER_KEY	     OKV		  SINGLE    NONE     UNDEFINED		1
FILE							      OPEN_NO_MASTER_KEY	     LOCAL_AUTOLOGIN	  SINGLE    UNITED   UNDEFINED		2
OKV							      OPEN_NO_MASTER_KEY	     OKV		  SINGLE    UNITED   UNDEFINED		2
FILE							      OPEN_NO_MASTER_KEY	     LOCAL_AUTOLOGIN	  SINGLE    UNITED   UNDEFINED		3
OKV							      OPEN_UNKNOWN_MASTER_KEY_STATUS OKV		  SINGLE    UNITED   UNDEFINED		3

6 rows selected.

We are now ready the create the initial master keys for the CDB and PDB’s:

SQL> administer key management set key force keystore identified by Oracle123 with backup container = all;

keystore altered.

SQL> @wstatus.sql

WRL_TYPE	     WRL_PARAMETER			      STATUS			     WALLET_TYPE	  WALLET_OR KEYSTORE FULLY_BAC	   CON_ID
-------------------- ---------------------------------------- ------------------------------ -------------------- --------- -------- --------- ----------
FILE		     /u01/app/oracle/admin/orcl/wallet/tde/   OPEN_NO_MASTER_KEY	     LOCAL_AUTOLOGIN	  SINGLE    NONE     UNDEFINED		1
OKV							                  OPEN			           OKV		  SINGLE    NONE     UNDEFINED		1
FILE							              OPEN_NO_MASTER_KEY	   LOCAL_AUTOLOGIN	  SINGLE    UNITED   UNDEFINED		2
OKV							      OPEN			     OKV		  SINGLE    UNITED   UNDEFINED		2
FILE							      OPEN_NO_MASTER_KEY	     LOCAL_AUTOLOGIN	  SINGLE    UNITED   UNDEFINED		3
OKV							      OPEN_UNKNOWN_MASTER_KEY_STATUS OKV		  SINGLE    UNITED   UNDEFINED		3

6 rows selected.

Finally we can validate that there are still no TDE master keys in the local keystores on the filesystem:

[oracle@ora23ai-0108 tde]$ orapki wallet display -wallet .
Oracle PKI Tool Release 19.0.0.0.0 - Production
Version 19.4.0.0.0
Copyright (c) 2004, 2024, Oracle and/or its affiliates. All rights reserved.

Requested Certificates:
Subject:        CN=oracle
User Certificates:
Oracle Secret Store entries:
ORACLE.SECURITY.CL.ENCRYPTION.OKV_PASSWORD
ORACLE.SECURITY.ID.ENCRYPTION.
ORACLE.SECURITY.KB.ENCRYPTION.
ORACLE.SECURITY.KM.ENCRYPTION.OKV_PASSWORD
Trusted Certificates:
[oracle@ora23ai-0108 tde]$

And that there are two TDE master keys in our Virtual Wallet in OKV:

[oracle@ora23ai-0108 bin]$ ./okvutil list
Enter Oracle Key Vault endpoint password:
Unique ID                               Type            Identifier
830F5D45-44F4-4843-BA78-1E6181178E7C	Symmetric Key	TDE Master Encryption Key: MKID 06606A7FBFA80B4F1FBF58D77A70C8203F
ACEA4BA4-3483-4A62-A0E9-65999FC11FCF	Template	Default template for DB1923_0108
F8F08BF0-160D-42D3-8DBD-1F473DDEF649	Symmetric Key	TDE Master Encryption Key: MKID 0604DB3A22A1454F42BF51DF65ABD99236
[oracle@ora23ai-0108 bin]$

Hopefully you found that easy and straightforward to follow and it’s all working as expected in your own system.

Leave a comment

I am a technology professional working as a Master Principal Solution Engineer at Oracle. For the last 15 years of my career, I have focused almost exclusively Database Security. The views and opinions expressed in this blog are the authors and don’t necessarily reflect those of Oracle.

Connect with me

Recent posts