Oracle Key Vault

Hands-On Lab
Saikat Saha
Sr. Principal Product Manager

LAB CONFIGURATION ORACLE KEY VAULT

OVERVIEW
For the Oracle Key Vault (OKV) lab exercises, we will be using 3 Virtual Machines:
HOL9275-OKV-APPLIANCE Oracle Key Vault Server
HOL9275-OKV-DB11.2.0.4 Oracle Database 11.2.0.4 Endpoint
HOL9275-OKV-DB12.1.0.2 Oracle Database 12.1.0.2 Endpoint

Hosts and IP addresses:

Host
Oracle Key Vault Appliance
Oracle 11.2.0.4 database
Oracle 12.1.0.2 database

IP Addresses
192.168.1.210
192.168.1.215
192.168.1.102

Login Accounts:
Oracle Key Vault:

OKV_SYS_SEAN (OKV System Administrator)

OKV_KEY_KATE (OKV Key Administrator)
OKV_AUD_AUDREY (OKV Audit Manager)

Password: Manager_1
Password: Manager_1
Password: Manager_1

Database Endpoints:
(11.2.0.4 and 12.1.0.2)

OS user: root
OS user: oracle
SYSDBA

Password: Manager_1
Password: Manager_1
Password: Manager_1

The password for all user accounts is Manager_1.

Oracle Wallet password in the Database Endpoints: welcome1
3

Getting the System and the Database Up

You can skip the following steps if the lab system is already up and running.
1. Start the HOL 9275OKVAPPLIANCE VirtualBox
2. Start the Database Endpoint Virtual Boxes (HOL9275-OKV-DB11.2.0.4 and HOL 9275-OKVDB12.1.0.2) one at a time. Repeat steps below on both Virtual Boxes
3. Login as oracle / Manager_1
4. Open a terminal window
5. Start the database listener
$ lsnrctl start

6. Start the Oracle Database

$ sqlplus / as sysdba
SQL> startup

7. Make sure that the running database is registered with the listener
SQL> alter system register;
SQL> exit
$ lsnrctl status

8. Close the terminal window

You are now ready to begin the Oracle Key Vault lab.

LAB EXERCISE 01
ENROLL AND PROVISION AN ORACLE KEY VAULT ENDPOINT

LAB EXERCISE 01
ENROLL AND PROVISION AN ORACLE KEY VAULT ENDPOINT
In this exercise, we will be enrolling an Oracle Database 11.2.0.4 server as an Oracle Key Vault
endpoint. You will be performing most of the steps in this lab exercise from the Oracle Key Vault
management console. Go to the HOL9275-OKV-DB11.2.0.4 virtual machine and login as
oracle/Manager_1
1. Open a Firefox browser session by clicking on the browser icon on the top task bar, click on
the Oracle Key Vault Server Console Login bookmark, and go to the Oracle Key Vault
Management Console login page.

2. Oracle Key Vault System Administrator enrolls an endpoint in Oracle Key Vault. Login as
Oracle Key Vault System Administrator using following credentials,
OKV_SYS_SEAN/Manager_1

3. Click on Endpoints tab on top

4. Click on the Add button on right corner on the Endpoint page

10

5. Enter following information on the Register Endpoint Page:

Endpoint Name:
Type:
Platform:
Description:

CUSTOMER_DB
Oracle Database (default selection)
Linux (default selection)
Customer Database Oracle 11.2.0.4
IP:192.168.1.215
Administrator Email: Sean.Williams@example.com (Enter the endpoint administrators
email address)
Click on the Register button on the right of the page.

11

6. Following page will appear after successful enrollment of the Database 11.2.0.4.
In real life deployments, the enrollment token is communicated by the system
administrator out of band to the endpoint administrator. In this lab, we are simulating this
by copying the value as system administrator and pasting the value of the token as
endpoint administrator.
Copy the one-time Enrollment Token field value in the console by highlighting and pressing
Ctrl-C.

7. Logout of the system by clicking the Logout button at the right top corner of the
management console.
8. As an endpoint administrator without logging into the Oracle Key Vault management
console, click on Endpoint Enrollment and Software Download link on the Management
Console. This link is right below the login section.

12

9. Following Enroll Endpoint page will appear.

13

10. Paste the enrollment token on the Enrollment Token textbox and click on the Submit
Token button. If the entered token is valid, the message Valid Token will appear next to
the Submit Token button.

14

11. Click on the Enroll button on top right corner.

A progress bar will appear with the text processing.

15

12. Software download pop-up window will appear once request has been processed.

16

13. Click on the Save File radio button on the download pop-up and Click on the OK button.
The okvclient.jar file will be downloaded to Desktop or another location depending on
your browsers save files preference setting.

17

14. Open a terminal by clicking on the terminal icon on the top task bar. cd to Desktop
directory or the location where okvclient.jar file is downloaded in previous step.
cd Desktop

15. Use java -jar okvclient.jar d /home/oracle/okvutil command to install Oracle Key Vault
endpoint software. In this command d specifies the location where Oracle Key Vault
18

endpoint software will be installed. For this lab exercise, we will use /home/oracle/okvutil
as the installation directory.
Java is a pre-requisite to install endpoint software, in this database virtual environment,
java is already setup. In a new environment, you will have to set the PATH or the
JAVA_HOME environment variable to run java.

16. Endpoint software keeps credentials used to connect to Oracle Key Vault server in an
Oracle wallet file. This wallet file requires a password to open or can be set up as an autologin wallet. During installation of endpoint software, installer prompts either to enter a
password or to press enter for auto-login wallet. For this lab exercise, we will press enter
to use an auto-login wallet for the endpoint installation. If you chose to use a password,
note the password carefully because you will require this password whenever endpoint
software connects with Oracle Key Vault server.

17. After successful installation, following successful installation message will appear.

18. Switch to user root, su root, enter password Manager_1.

19

19. Go to /home/oracle/okvutil/bin directory and run root.sh as user root.

cd /home/oracle/okvutil/bin
./root.sh

20. Switch back to user oracle, type exit and run okvutil list command to check Oracle Key
Vault endpoint software has been enrolled and provisioned properly. If Endpoint software
is able to successfully connect to the Oracle Key Vault server, message
No objects found will appear for a new installation.
If you get Server connect failed message at this stage or any other message, your
endpoint software installation has some potential issues.

This step concludes the Oracle Key Vault first lab exercise.

20

LAB EXERCISE 02
ORACLE WALLET UPLOAD/DOWNLOAD TO/FROM ORACLE KEY VAULT

21

22

LAB EXERCISE 02
ORACLE WALLET UPLOAD/DOWNLOAD TO/FROM ORACLE KEY VAULT
In this lab exercise, we will upload an existing Oracle Wallet to Oracle Key Vault for long-term
retention using the same HOL9275-OKV-DB11.2.0.4 database endpoint. Then, we will download
the wallet and demonstrate that you can query encrypted data using the downloaded wallet.
DB11.2.0.4 has already been setup with Oracle Advanced Security Transparent Data Encryption
(TDE).
1. Open Firefox browser session and go to the bookmark Oracle Key Vault Console Login to
open Oracle Key Vault management console. Login as the key administrator using
following credential OKV_KEYS_KATE/Manager_1. Note that we are using a different login
this time. We are now logging in as a key administrator of Oracle Key Vault, previously we
had logged in as a system administrator. Key administrator defines the access control
settings in Oracle Key Vault whereas system administrator enrolls the endpoints. This
ensures separation of duty between administrators.

2. Click on Keys and Wallet tab on top of the management console. Click on the Create
button on the right of the Keys and Wallets page.

23

3. Following Create Wallet screen will appear.

Enter name of wallet as CUSTOMER_DB_WALLET and Description as Customer Database
Wallet and click on the Save button.

24

4. Successful wallet creation message will pop up and management console will appear as
below. Click on the details pencil icon.

5. Wallet overview page will appear as below. Click on the Add button on the Wallet Access
Setting section of this page.

6. In the Wallet Access Settings section,

Select Endpoints in the Type dropdown
Click on CUSTOMER_DB endpoint in Endpoints section
Click on Read and Modify radio button in Select Access Level section
Click on Manage Wallet check box
25

Click on the Save button

7. Click on Wallet Name CUSTOMER_DB_WALLET from the wallets page, since this is a newly
created virtual wallet in Oracle Key Vault, it will display No content found under Wallet
Contents section.

26

8. Minimize the browser and open a terminal. Now we will upload the contents of the wallet
file ewallet.p12 in /etc/oracle/wallets/orcl directory to Oracle Key Vault using okvutil
upload command.
cd /home/oracle/okvutil/bin
./okvutil upload -t WALLET -l /etc/oracle/wallets/orcl -g CUSTOMER_DB_WALLET
In this upload command, -t defines the type of file being uploaded, -l defines the location
of the file being uploaded and g defines the virtual wallet in Oracle Key Vault where
contents of the wallet file will be uploaded.

It will prompt for wallet password, enter wallet password which is welcome1. If upload is
succeeded it will give a message that Upload succeeded.

9. Go back to the browser session of Oracle Key Vault management console and refresh the
browser session. Now click on the wallet CUSTOMER_DB_WALLET or All items page,
console will display the wallet contents that has been uploaded in previous step.

27

10. Now we will download the wallet from Oracle Key Vault to demonstrate that you can query
encrypted data using the downloaded wallet. If a wallet file exists in the same directory
location specified with -l option, the existing wallet file will be automatically backed up
during the download process.
cd /home/oracle/okvutil/bin
./okvutil download -t WALLET -l /etc/oracle/wallets/orcl -g CUSTOMER_DB_WALLET

11. This will prompt for new wallet password and confirm the password. You can also press
Enter to create an Auto-Login wallet. For this lab exercise, enter a password and confirm,
use welcome1 as password. Download succeeded message will appear.

28

12. In order to check that encrypted data can be queried using this newly downloaded wallet,
create a new session of sqlplus
sqlplus / as sysdba

13. We have to now close previous wallet, provide wallet password welcome1.
alter system set encryption wallet close identified by welcome1;

14. Open the newly downloaded wallet

alter system set encryption wallet open identified by welcome1;
29

15. Query encrypted data

select * from banking.customersENC;

This demonstrates that you can query encrypted data using newly downloaded wallet.
This step concludes lab exercise 2.

30

LAB EXERCISE 03
TDE DIRECT CONNECTION WITH ORACLE KEY VAULT

31

32

LAB EXERCISE 03
TDE DIRECT CONNECTION WITH ORACLE KEY VAULT
For this lab exercise, we will be using the DB12.1.0.2 database endpoint. Login to the HOL-OKVDB12.1.0.2 virtual machine using credential oracle/Manager_1

1. Open a Firefox browser session by clicking the browser icon on the top task bar. Go to the
bookmark Oracle Key Vault Admin Home to login to the Oracle Key Vault management
console.

2. Login as system administrator using credential OKV_SYS_SEAN/Manager_1

33

3. Click on Endpoints tab, this will show the Endpoint that we had created in the previous lab
exercise. We will enroll and provision another endpoint for the DB12.1.0.2 database
server.

4. Click on the Add button on top right corner. Following page will appear.

34

5. Enter following data and click on Register button

Endpoint Name: HR_DB
Type: Oracle Database (use the default dropdown)
Platform: Linux (use the default dropdown)
Description: HR Application Database Oracle 12.1.0.2
IP:192.168.1.102
Administrator Email: sean.williams@example.com

6. Once successfully enrolled, successful enrollment message will appear and the endpoint
page will look like below. Copy the enrollment token from this page by highlighting and
Ctrl-C.

7. Logout of this page. Click on the Endpoint Enrollment and Software Download link on the
Management Console page below the login section.

35

8. Following page appears

36

9. Paste the enrollment token and click Submit Token button. Valid Token message will
appear if this is a valid token.
Click on the Enroll button on top right corner.

10. Progress bar will appear momentarily

11. Download okvclient.jar file popup will appear as below

Click on Save File radio button on the pop up and click OK.
The okvclient.jar will be copied to the location specified in your browser save files to
preferences settings. In this lab exercise, this is copied to the Desktop.

37

12. Minimize the Browser and open up a terminal now by clicking on the Terminal icon on top
of the virtual machine.

13. Go to the Desktop directory

cd Desktop
38

14. Use java -jar okvclient.jar -d /home/oracle/okvutil command to install okv endpoint
software.
In this lab, java is already set as part of the environment setup. If you are using a new
environment, you have set either the PATH or the JAVA_HOME environment variables
appropriately to run java -jar command.

15. Endpoint software keeps credentials used to connect to Oracle Key Vault server in an
Oracle wallet file. This wallet file requires a password to open or can be set up as an autologin wallet. During installation of endpoint software, installer prompts either to enter a
password or to press enter for auto-login wallet. For this lab exercise, we will press enter
to use an auto-login wallet for the endpoint installation. If you chose to use a password,
note the password carefully, you will require this password whenever endpoint software
connects with Oracle Key Vault server.
Endpoint software successful installation message will appear.

16. Now we will switch to user root.

su root Use password Manager_1 when prompted.
39

17. Go to /home/oracle/okvutil/bin directory and run root.sh script.

cd /home/oracle/okvutil/bin
./root.sh

Installation Successful message will display.

18. Go back to the browser. Click on the Oracle on top left to go to the login page and login as
OKV_KEYS_KATE key administrator using password Manager_1. Note that we are using
a different login this time. We are now logging in as a key administrator of Oracle Key
Vault, previously we had logged in as a system administrator. This ensures separation of
duty between administrators.

40

19. Click on the Keys and Wallets tab on top.

20. Click on the Create button to create a virtual wallet in Oracle Key Vault

41

21. Enter information regarding the wallet and click save

Name: HR_DB_WALLET
Description: HR Application Database Wallet

22. Page will appear as below after successful creation of wallet

23. Click on the Details pencil icon for HR_DB_WALLET

24. Click on the Add button in Wallet Access Settings section

42

25. Enter following information

Type Dropdown: Select Endpoint
Select HR_DB_WALLET
Click on Read and Modify radio button
Click on the Manage wallet check box.
Click on the Save button

26. Now go back to the terminal and switch back to user oracle
su oracle
cd to /home/oracle/okvutil/bin

43

27. Upload the existing Oracle Wallet, it is recommended to upload existing wallet to Oracle
Key Vault so that Key Vault has the copy of the wallet file which contains all historical TDE
master keys.
./okvutil upload -t WALLET -l /etc/oracle/wallets/orcl -g HR_DB_WALLET

This will prompt for the source wallet password, use welcome1 as the password for the
source wallet.

28. Now open a sqlplus session

sqlplus / as sysdba

29. Before migrating the TDE master key from wallet to Oracle Key Vault, we need to close the
existing wallet file.
administer key management set keystore close identified by welcome1;

44

30. Successful closing will show up as

31. Close the sqlplus session. Open a new terminal to open sqlnet.ora configuration file.
vi $ORACLE_HOME/network/admin/sqlnet.ora

45

32. Existing sqlnet.ora file will look like below

33. Change METHOD=FILE to METHOD=HSM

Move cursor to F of FILE and press c and w to change the word FILE in VI editor. Then
type HSM (upper case) and then save the file by pressing escape button first and then
typing wq!. Press Enter to save the file.

46

34. Open a new sqlplus session

sqlplus / as sysdba;

35. To check if the changes made in sqlnet.ora are effective. WRL_TYPE should show both FILE
and HSM and both in closed state
select wrl_type, status from v$encryption_wallet;

36. Now use the migration command to move TDE master key from wallet file to OKV
administer key management set encryption key identified by null migrate using
welcome1 with backup;

If successful, keystore altered message will appear

37. When you are migrating TDE master key from wallet file to Oracle Key Vault, you are
essentially rotating into Oracle Key Vault. This affixes TDE to direct connection with OKV
*and* immediately creates a new key in OKV (which you will see in the console in a
subsequent step).
47

Go back to the browser and login as key administrator using credential

okv_keys_kate/Manager_1
Click on All Items button on left side
Page will appear as below

38. Click on Owner

Click on HR_DB

39. All keys belonging to HR_DB endpoint will be filtered. Newly created TDE master key is
displayed here.

48

40. Imagine six months have passed since you have migrated TDE to a direct connection with
OKV, and now the time has come to rotate the TDE master key. Below you will execute the
relevant TDE command to perform a TDE master key rotation. This is what you would do
to perform regular key rotations on an ongoing basis during the years to come.
Now we will perform a re-key operation on TDE and will show that the new key is shown in
OKV
Go back to the terminal with sqlplus. Use following command
administer key management set encryption key identified by null;

49

41. Refresh the previous page in browser or go to all items page in OKV management console.
Filter by owner HR_DB, you will see a new TDE master key has been created and displayed.

This concludes the lab exercise 03 of Oracle Key Vault hands-on-lab.

50