How to migrate your local TDE wallet to Oracle Key Vault .
Here and here are the links to the 21C document that I used for to go through this process.
I am assuming that you installed OKV by this point.
Below are the steps.
1) Add the database/host to OKV as an endpoint.
Remember in OKV, each endpoint is unique, but a wallet is shared between endpoints.
I navigate to the endpoint tab and click on the "Add" button.
I fill in the information for my database (TDETEST from my previous post). This is the CDB, as I am using a UNITED wallet for all PDBs that are a member of my CDB. Once filled in I click on the "Register" button.
2) Download the OKV client install file
Now that the database/host is registered in OKV (the combination of the 2 is the endpoint), I need to download the jar file which will configure the setting on the database host.
The download is initiated by logging out of the OKV console, and clicking on the "Endpoint Enrollment and Software Download" link on the logon screen. I highlighted it below.
- Click on the "Submit Token" button, and it will validate the token
- Click on "Enroll" to begin the download of the install file. If SMTP was configured, you can also have the software install e-mailed to the endpoint administrator.
3) Transfer the .jar file to the database host and install it.
The pre-requisites are in the install guide. The oracle environment during the install mustbe set to the database you are configuration ($ORACLE_HOME, $ORACLE_BASE, $ORACLE_SID)
My target directory is going to be "/home/oracle/app/oracle/admin/tdetest/wallet/okv" and I copied my .jar file to /home/oracle/app/oracle/admin/tdetest (which I renamed to tdetest_okv.jar).
Execute java passing the location of the jar file, followed by -d "install location"
[oracle@oracle-server okvtest]$ java -jar /home/oracle/app/oracle/admin/tdetest/tdetest_okv.jar -d /home/oracle/app/oracle/admin/tdetest/wallet/okv
Detected JAVA_HOME: /home/oracle/db_19c/jdk
Enter new Key Vault endpoint password (<enter> for auto-login):
Confirm new Key Vault endpoint password:
The endpoint software for Oracle Key Vault installed successfully.
Deleted the file : /home/oracle/app/oracle/okvfiles/okvtest/okvtest_install.jar
[oracle@oracle-server okvtest]$
If this is the first time OKV is being installed on the server, you need to execute the root.sh script (located in the /bin directory within the install location) as root. If it has already been executed, you can skip this step.
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 permissionsFinally, verify that we can connect OKV by executing "okvutil list". If successful, you will receive "no objects found". This script is located in the /bin directory within the install.
oracle@oracle-server bin]$ ./okvutil list
Enter Oracle Key Vault endpoint password:
No objects found
4) Review how OKV connects to the database.
- WALLET_ROOT is set in the database, and within WALLET_ROOT there is an "/okv" directory where the endpoint software must be installed.
- On the OS itself, a library is installed (as root if it's not already there) to take care of the encryption
- A link is created to a config file for this endpoint. This link is located in $ORACLE_BASE/admin/$ORACLE_SID and links to 2 files that were part of the install. okvclient.lck, and okvclient.ora.
NOTE: okvclient.ora is the configuration file where parameters are set for the endpoint.
5) Create wallet in OKV and associate it with the endpoint(s)
Now that OKV is installed and configured on the client we can create a wallet in OKV to upload the keys into. I am going to start by logging back into OKV and navigating to the wallets tab and clicking on "Create" to create a new wallet.
The screen belows comes up, and I enter the name of the new wallet to hold the keys for my CDB. I then click on save to save the new wallet.
6) Upload the keys from the local wallet into OKV
Now we upload the keys from the local wallet into OKV.
The command is
"okvutil upload -t WALLET -l {wallet location on host} -g {key vault wallet name} -v 2
NOTE: the Key Vault wallet name is case sensitive
[oracle@oracle-server bin]$ ./okvutil upload -t WALLET -l /home/oracle/app/oracle/admin/tdetest/wallet/tde -g tdetest -v 2
okvutil version 21.1.0.0.0
Endpoint type: Oracle Database
Configuration file: /home/oracle/app/oracle/admin/tdetest/wallet/okv/conf/okvclient.ora
Server: 10.0.0.150:5696
Standby Servers:
Uploading from /home/oracle/app/oracle/admin/tdetest/wallet/tde
Enter source wallet password:
Enter Oracle Key Vault endpoint password:
ORACLE.SECURITY.ID.ENCRYPTION.
ORACLE.SECURITY.KB.ENCRYPTION.
ORACLE.SECURITY.KT.ENCRYPTION.AQDBKozP1k8Mvwq4sH7ptKYAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.KM.ENCRYPTION.AQDBKozP1k8Mvwq4sH7ptKYAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.DB.ENCRYPTION.AQDBKozP1k8Mvwq4sH7ptKYAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.KT.ENCRYPTION.AYURdnq5XU8Rv7IipWqWgHoAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.KM.ENCRYPTION.AYURdnq5XU8Rv7IipWqWgHoAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.DB.ENCRYPTION.AYURdnq5XU8Rv7IipWqWgHoAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.DB.ENCRYPTION.MASTERKEY.BF507489CE7703B4E0536800000A8180
ORACLE.SECURITY.KM.ENCRYPTION.AXLqsppXAU9kv9JLJCcfGYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.DB.ENCRYPTION.AXLqsppXAU9kv9JLJCcfGYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.KT.ENCRYPTION.AXLqsppXAU9kv9JLJCcfGYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.DB.ENCRYPTION.MASTERKEY.BF5072A8540A032BE0536800000AB0DD
ORACLE.SECURITY.KM.ENCRYPTION.AXDVlynThU8bvwblg7vruGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.DB.ENCRYPTION.AXDVlynThU8bvwblg7vruGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.KT.ENCRYPTION.AXDVlynThU8bvwblg7vruGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.DB.ENCRYPTION.MASTERKEY.BF50708B8BEB0266E0536800000A7B90
ORACLE.SECURITY.DB.ENCRYPTION.MASTERKEY
Uploaded 4 TDE keys
Uploaded 0 SEPS entries
Uploaded 0 other secrets
Uploaded 6 opaque objects
Uploading private persona
Uploading certificate request
Uploading trust points
Uploaded 1 private keys
Uploaded 1 certificate requests
Uploaded 0 user certificates
Uploaded 0 trust points
Upload succeeded
Within the upload, I can see where the TDE master keys are being uploaded for my PDBs by looking at the PDB guids.
PDB PDB_ID
SQL> column name format a40
SQL> select name,guid from v$pdbs;
NAME GUID
---------------------------------------- --------------------------------
PDB$SEED BF5039AF39966A70E0536800000A09E1
TDEPDB1 BF50708B8BEB0266E0536800000A7B90
TDEPDB2 BF5072A8540A032BE0536800000AB0DD
TDEPDB3 BF507489CE7703B4E0536800000A8180
And I can look in the wallet in OKV (filtering by Symmetric key) and see the contents that was uploaded from the local wallet. In this screen I can identify the PDB key because I used tags when I created the keys.
7) Add secret to allow use of "External Store".
1) I am going to add the OKV password to the keystore as a secret to allow me to use the "EXTERNAL STORE" instead of the password.
ADMINISTER KEY MANAGEMENT ADD SECRET '0KV2021!' FOR CLIENT 'OKV_PASSWORD' TO LOCAL AUTO_LOGIN KEYSTORE '/home/oracle/app/oracle/admin/tdetest/wallet/tde_seps';
- The keystore must be in a subdirectory of the WALLET_ROOT location called "tde_seps" in order to be found.
- The "FOR CLIENT" entry must be 'OKV_PASSWORD' to be found.
- It must be AUTO_LOGIN so that it can be opened and used.
2) I am going to add the OKV password to the keystore as a secret to allow me to auto logon to the OKV Keystore.
ADMINISTER KEY MANAGEMENT ADD SECRET '0KV2021!' FOR CLIENT 'HSM_PASSWORD' TO AUTO_LOGIN KEYSTORE '/home/oracle/app/oracle/admin/tdetest/wallet/tde';
3) I need to change the TDE_CONFIGURATION (which is dynamic).
'ALTER SYSTEM SET TDE_CONFIGURATION = "KEYSTORE_CONFIGURATION=OKV|FILE" SCOPE = BOTH;
4) I am going to bounce the database, and ensure that both my file and OKV wallets open up properly.
Type WRL_PARAMETER Status WALLET_TYPE WALLET_OR KEYSTORE FULLY_BAC CON_ID
---------- -------------------------------------------------- -------------------- -------------------- --------- -------- --------- ----------
FILE /home/oracle/app/oracle/admin/tdetest/wallet//tde/ OPEN AUTOLOGIN SINGLE NONE YES 1
OKV OPEN_NO_MASTER_KEY OKV SINGLE NONE UNDEFINED 1
FILE OPEN AUTOLOGIN SINGLE UNITED YES 2
OKV OPEN_NO_MASTER_KEY OKV SINGLE UNITED UNDEFINED 2
FILE OPEN AUTOLOGIN SINGLE UNITED YES 3
OKV OPEN_NO_MASTER_KEY OKV SINGLE UNITED UNDEFINED 3
FILE OPEN AUTOLOGIN SINGLE UNITED YES 4
OKV OPEN_NO_MASTER_KEY OKV SINGLE UNITED UNDEFINED 4
FILE OPEN AUTOLOGIN SINGLE UNITED YES 5
OKV OPEN_NO_MASTER_KEY OKV SINGLE UNITED UNDEFINED 5
10 rows selected.
8) Combine the local wallet File and OKV.
Next I need to migrate the keys using the local wallet. Note this will rekey the database.
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "0KV2021!" MIGRATE USING "F1LE2021!" WITH BACKUP;
I am going to bounce the database and ensure it comes up with both Keystores opened.
Type WRL_PARAMETER Status WALLET_TYPE WALLET_OR KEYSTORE FULLY_BAC CON_ID
---------- -------------------------------------------------- ------------------------------ -------------------- --------- -------- --------- ----------
FILE /home/oracle/app/oracle/admin/tdetest/wallet//tde/ OPEN AUTOLOGIN SECONDARY NONE YES 1
OKV OPEN OKV PRIMARY NONE UNDEFINED 1
FILE OPEN AUTOLOGIN SINGLE UNITED YES 2
OKV OPEN OKV SINGLE UNITED UNDEFINED 2
FILE OPEN AUTOLOGIN SECONDARY UNITED YES 3
OKV OPEN OKV PRIMARY UNITED UNDEFINED 3
FILE OPEN AUTOLOGIN SECONDARY UNITED YES 4
OKV OPEN OKV PRIMARY UNITED UNDEFINED 4
FILE OPEN AUTOLOGIN SECONDARY UNITED YES 5
OKV OPEN OKV PRIMARY UNITED UNDEFINED 5
That's all there is to it !
The most important notes I found during this process
- WALLET_ROOT and TDE_CONFIGURATION should be used in 19c.
- The password for OKV
- add secret to the wallet in WALLET_ROOT/tde_seps using client 'OKV_PASSWORD'
- add secret to the wallet in WALLET_ROOT/tde using client 'HSM_PASSWORD'
- OKV must be installed in WALLET_ROOT/okv