8 Enrolling Endpoints for Oracle Key Vault

After a Key Vault system administrator registers an endpoint, an endpoint administrator must enroll and provision the endpoint to manage security objects using Key Vault.

8.1 About Endpoints for Oracle Key Vault

Endpoints are clients of Oracle Key Vault that use the appliance to store and manage their security objects, share them with trusted peers, and retrieve them when needed. These clients can be systems like Oracle database servers, Oracle middleware servers, operating systems, and other information systems.

A Key Vault system administrator first adds (or registers) the endpoint to Key Vault, then sends the endpoint's enrollment token (generated during registration) to the endpoint administrator.The endpoint administrator verifies the enrollment token before enrolling and provisioning the endpoint. An enrolled endpoint can upload, download, and manage security objects using Key Vault.

See Also:

Parent topic: Enrolling Endpoints for Oracle Key Vault

8.2 Overview of Endpoint Enrollment and Provisioning

Endpoint enrollment is a three step process performed by two kinds of administrative users summarized in the following table.

Table 8-1 Summary of Endpoint Enrollment

Step#	Task(s)	Performed by	Endpoint Status (as seen on Key Vault Management Console)
1.	Add/register the endpoint to Key Vault. An enrollment token for the endpoint is generated. Send the enrollment token to the endpoint administrator to complete the enrollment process.	Key Vault system administrator on Key Vault	Registered
2.	Verify enrollment token. Submit enrollment token to download endpoint software `okvclient.jar` to the endpoint.	Endpoint administrator via Key Vault User Interface	Enrolled
3.	Install `okvclient.jar` at the endpoint.	Endpoint administrator on endpoint	Enrolled

Endpoint enrollment ensures that only authorized endpoints can communicate with Key Vault because the utilities needed to communicate are bundled with the endpoint software okvclient.jar.

okvclient.jar contains the following:

A TLS certificate and private key that the endpoint uses to authenticate itself to Oracle Key Vault
A TLS certificate for Oracle Key Vault that serves as the root CA
Endpoint libraries and utilities
Additional information like the Key Vault IP address that is used by okvutil to create the okvclient.ora configuration file

In an Oracle Real Application Clusters (RAC) environment, you must enroll and provision each Oracle RAC node as an endpoint.

See Also:

"Types of Endpoint Enrollment" for more information about adding an endpoint to Key Vault
"Endpoint okvclient.ora Configuration File"

Parent topic: Enrolling Endpoints for Oracle Key Vault

8.3 Finalizing Enrollment and Provisioning

To enroll and provision a registered endpoint an endpoint administrator must complete two tasks.

Parent topic: Enrolling Endpoints for Oracle Key Vault

8.3.1 Task 1: Enroll Endpoint and Download Software

You will need the endpoint's enrollment token to download the endpoint software okvclient.jar.

After registering the endpoint the Key Vault system administrator sends this endpoint's enrollment token to the endpoint administrator by email or other out-of-band method.

To learn more about endpoint registration please see the See Also section following Task 1.

To download the endpoint software:

Log in to the endpoint server as the endpoint administrator.
Connect to the Oracle Key Vault management console.

For example:

https://192.0.2.254
The login page to the Oracle Key Vault management console appears.

Do not log in.

Figure 8-1 Key Vault Management Console Login Screen

Description of "Figure 8-1 Key Vault Management Console Login Screen"
Click the highlighted link Endpoint Enrollment and Software Download below Login.

The Enroll Endpoint & Download Software page appears with two tabs:
- Enroll Endpoint & Download Software
- Download Endpoint Software Only
Figure 8-2 Enroll Endpoint & Download Software Page

Description of "Figure 8-2 Enroll Endpoint & Download Software Page"

Note that Figure 8-2 has been trimmed and contains the following text between Download Endpoint Software and the Cancel, Reset, and Enroll buttons on the right:

“To enroll an endpoint, enter your endpoint Enrollment Token and click 'Submit Token'. Update the endpoint details if necessary and click 'Enroll' to complete the enrollment. Download the endpoint package when prompted."
Click Enroll Endpoint & Download Software.

The next step depends on how the endpoint was added (or registered with) to Key Vault:
- If the endpoint was registered by a Key Vault System Administrator do the following:
  - Enter the endpoint's enrollment token in Enrollment Token, and click Submit Token.
    
    If the token is valid, a valid token message appears to the right of Submit Token.
    
    The fields Endpoint Type, Endpoint Platform, Email and Description get automatically populated with the values entered during endpoint registration.
    
    If the token is invalid, an invalid token message appears. Check the token and retry.
- If the endpoint was registered by self-enrollment do the following:
  - Self-enrolled endpoints have no enrollment token, so skip the step of validating the token.
  - Enter values for the following fields:
    1. Endpoint Type: Can be Oracle Database, Oracle (non-database), or Other. If you are using TDE, you must enter Oracle Database.
    2. Endpoint Platform: One of Linux, Solaris SPARC, Solaris x64, AIX, HP-UX, Windows.
    3. Email: Email address of the endpoint administrator for notification purposes. This is optional but recommended.
    4. Description: This is optional but strongly recommended for ease of identification in reports. Enter meaningful and identifying information for the endpoint.
Click Enroll on top right.

A directory window appears and prompts you to save the endpoint software file: okvclient.jar.

Navigate to the folder where you want to save the file.
Save the file in a secure directory with appropriate permissions in place so it cannot be read or copied by others.
Verify that the file has been downloaded. If the download fails for any reason, you must obtain a new enrollment token from the key administrator for the endpoint and repeat Steps 6 and 7. Note that if you did not download the file to the endpoint system, you must use an out-of-band method to copy the file to that system and install it there.
Now you are ready to install okvclient.jar file on the endpoint as described in Task 2: Install Oracle Key Vault Software on the Endpoint.

See Also:

Parent topic: Finalizing Enrollment and Provisioning

8.3.2 Task 2: Install Oracle Key Vault Software on the Endpoint

To install the software okvclient.jar on the endpoint:

Ensure that you have the necessary administrative privileges to install software on the endpoint.
Ensure that you have JDK 1.5 or later installed, and that the PATH environment variable includes the java executable (in the JAVA_HOME/bin directory).

Oracle Key Vault supports JDK versions 1.5, 1.6, 7, and 8.
Run the Shell utility ORAENV or source ORAENV command to set the correct environment variables on Oracle Database servers.
Check that the environment variables ORACLE_BASE and ORACLE_HOME are correctly set.

If you used ORAENV to set these variables, you must verify that ORACLE_BASE points to the root directory for Oracle Databases, and that ORACLE_HOME points to a sub-directory under ORACLE_BASE where an Oracle Database is installed.
Navigate to the directory in which you saved the okvclient.jar file.
Run the java command to install the okvclient.jar file.
```
java -jar okvclient.jar -d /home/oracle/okvutil -v
```
Note:
For a new installation, ensure that the directory location specified in the -d argument does not contain a subdirectory named ssl. If you are upgrading an existing deployment, the original ssl subdirectory is used.

If you are re-enrolling the endpoint, add the -o argument to the command.
```
java -jar okvclient.jar -d /home/oracle/okvutil -v -o
```
In the above commands:
- The -d argument specifies the directory location for the endpoint software and configuration files, in this case /home/oracle/okvutil.
  
  The environment variable $OKV_HOME refers to the directory where the endpoint software is installed, in this case /home/oracle/okvutil.
- The -v argument writes the installation logs to the $OKV_HOME/log/okvutil.deploy.log file at the server endpoint.
- The -o argument overwrites the symlink reference to okvclient.ora.
  
  Note:
  -o is an optional argument that allows you to overwrite the symlink reference to okvclient.ora, when okvclient.jar is deployed in a directory other than the original directory. This argument is used only when re-enrolling an endpoint.
The installation process prompts for a password. You can enter a password to create a password-protected wallet or create an auto-login wallet without a password as described below:
- A password-protected wallet is an Oracle wallet file that store the endpoint's credentials to access Oracle Key Vault. This password will be required whenever the endpoint connects to Oracle Key Vault.
  
  Create a password-protected wallet by entering a password between 8 and 30 characters. Then press Enter.
- Create an auto-login wallet by simply clicking Enter.
  
  No password will be required when the endpoint connects to Oracle Key Vault. An auto-login wallet enables endpoint provisioning without human intervention.
```
Enter new Key Vault endpoint password (<enter> for auto-login): Key_Vault_endpoint_password
Confirm new endpoint password: Key_Vault_endpoint_password
```
The installation proceeds and completes with the following message:
```
The Oracle Key Vault endpoint software installed successfully.
```
A successful installation of the endpoint software creates the following directories:
- bin: contains the okvutil program, the root.sh and root.bat scripts, and the binary files okveps.x64 and okveps.x86
- conf: contains the configuration file okvclient.ora
- jlib: contains the Java library files
- lib: contains the file liborapkcs.so
- log: contains the log files
- ssl: contains the TLS-related files and wallet files. The wallet files contain the endpoint credentials to connect to Oracle Key Vault.
  
  The ewallet.p12 file refers to a password-protected wallet. The cwallet.sso file refers to an auto-login wallet.
On UNIX platforms, the liborapkcs.so file contains the library that the Oracle database uses to communicate with Oracle Key Vault. On Windows platforms, the liborapkcs.dll file contains the library that the Oracle database uses to communicate with Oracle Key Vault.
If you are planning to use a TDE direct connection, then run root.sh on Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations. The liborapkcs.so file is copied to the following directory: /opt/oracle/extapi/64/hsm/oracle/1.0.0

On Windows installations, run root.bat. The liborapkcs.dll file is copied to C:\oracle\extapi\64\hsm\oracle\1.0.0

Log in as the root user and run the root.sh script. On Windows installations, run root.bat.
```
$ sudo bin/root.sh
```
```
bin\root.bat
```
Or:
```
$ su -
# bin/root.sh
```
On Windows platforms, you are prompted for the version of the RDBMS in use when you execute root.bat. Switch out of user root after completing this step.
Run the okvutil list command to verify that the endpoint software installed correctly, and that the endpoint can connect to the Oracle Key Vault server.
If the endpoint is able to connect to Key Vault, a No objects found message appears:
```
$ ./okvutil list
No objects found
```
If a Server connect failed message appears at any time, you must troubleshoot the installation for possible issues. First check that environment variables are correctly set.

You can get help on the endpoint software with the -h option:

java -jar okvclient.jar -h

The following output appears:

Oracle Key Vault Release 12.2.0.6.0 (2017-12-15 15:36:49.839 PDT)
Production on Fri Dec 15 19:55:31 PDT 2017
Copyright (c) 1996, 2017 Oracle. All Rights Reserved.
Usage: java -jar okvclient.jar [-h | -help] [[-v | -verbose] [-d <destination directory>] [-o]]

After installation Oracle recommends that you securely delete the endpoint software file okvclient.jar.

See Also:

"Glossary" for definitions of environment variables
"Special Notes About Endpoint Provisioning" to check environment and setup
"Using an Online Master Key with Oracle Key Vault" for TDE

Parent topic: Finalizing Enrollment and Provisioning

8.4 Special Notes About Endpoint Provisioning

The default location for the okvclient.ora file is the $OKV_HOME/conf directory. When the installation completes, the JAVA_HOME path is added to the okvclient.ora configuration file for future use by okvutil.

When you provision endpoints you must know how the installation process determines the location of Java home and the okvclient.ora file.

For Oracle Database endpoints, if you are using the srvctl utility and setting environment variables in sqlnet.ora you must set them in both the operating system and the srvctl environment.

How the Location of JAVA_HOME Location is Determined

The endpoint software installation process uses two rules to determine the Java home location:

If a user-defined JAVA_HOME environment variable exists, the installation process uses this value.
If JAVA_HOME is not set, the installation process looks for it in the java.home system property of the Java Virtual Machine (JVM).

Once the JAVA_HOME path is determined, it is added to the configuration file okvclient.ora to be used by all okvutil commands.

You can force okvutil to use a different JAVA_HOME setting using one of these methods:

Set the JAVA_HOME environment variable in the shell where you run okvutil:

setenv JAVA_HOME path_to_Java_home

Or:

export JAVA_HOME = path_to_Java_home

Set the JAVA_HOME property directly in the okvclient.ora configuration file.
```
JAVA_HOME=path_to_Java_home
```

Location of the OKVCLIENT.ORA File and Environment Variables

$OKV_HOME is the destination directory for the endpoint software specified with the -d option during installation. The file okvclient.ora is a configuration file in the directory $OKV_HOME/conf.

In addition to $OKV_HOME/conf, a soft link to okvclient.ora is set up for an existing database. The location of the soft link depends on the following:

If the $ORACLE_BASE variable is set, then the installation process creates a symbolic link to the okvclient.ora configuration file (in $OKV_HOME/conf) in the $ORACLE_BASE/okv/$ORACLE_SID location.

If the okvclient.ora file already exists in the $ORACLE_BASE/okv/$ORACLE_SID location, then the installation process accepts the existing soft link to okvclient.ora as a a valid soft link.
If the $ORACLE_BASE/okv/$ORACLE_SID directory is not set, then the installation process tries to create it.
If the $ORACLE_HOME variable is set and the $ORACLE_BASE variable is not set, then the installation process creates a symbolic link for the $ORACLE_HOME/okv/$ORACLE_SID location to point to the configuration file in the $OKV_HOME/conf directory.

Setting OKV_HOME for Non-database Utilities to Communicate with Key Vault

For non-database utilities you must set the environment variable OKV_HOME to point to the destination directory for the endpoint software, because the installation process does not set this variable automatically. OKV_HOME must be set for these utilities to communicate with Key Vault. These include utilities such as Oracle Recovery Manager (RMAN) that access Oracle Key Vault for keys.

You must set OKV_HOME in all environments where you will run utilities like RMAN. For example, if you spawn a new xterm, you will need to set OKV_HOME in this environment before running RMAN.

Environment Variables in SQLNET.ORA

You must consider the following points while using the srvctl utility on Oracle Database endpoints:

If you are using the srvctl utility, and if you want to include environment variables in the sqlnet.ora configuration file, then you must set these environment variables in both the operating system and the srvctl environment.
The operating system (OS) and Server Control (srvctl) should have $ORACLE_SID, $ORACLE_HOME and $ORACLE_BASE set to the same values.

If the Endpoint Does Not Use the Oracle Key Vault Client Software

Third party KMIP endpoints do not use the Key Vault software okvutil and liborapkcs.so. In this case you must manually set the TLS authentication as follows:

Extract the ssl directory from the okvclient.jar file, as follows:
```
jar xvf okvclient.jar ssl
```
Use the following files to set up the TLS authentication:
- ssl/key.pem: endpoint private key
- ssl/cert.pem: endpoint certificate
- ssl/cert_req.pem: certificate request corresponding to cert.pem
- ssl/CA.pem: trust anchor for verifying the Oracle Key Vault server certificate

Parent topic: Enrolling Endpoints for Oracle Key Vault

8.5 Transparent Data Encryption Endpoint Management

TDE has supported storing TDE master encryption keys in Oracle wallets, beginning with Oracle Database 10g Release 2, and in Hardware Security Modules (HSMs), beginning with Oracle Database 11g Release 1.

Oracle Key Vault can manage TDE keys by using the same PKCS#11 interface that TDE uses to communicate with an external keystore. Therefore, you do not need to patch the database to use Key Vault for storing and retrieving TDE master keys. Oracle Key Vault supplies the PKCS#11 library to communicate with Oracle Key Vault.

Oracle Key Vault improves upon TDE key management. For example, the keys in the wallet can be uploaded directly to Key Vault for long-term retention, to be shared with other database endpoints within the same endpoint group. Therefore, you do not need to store the wallet indefinitely after migration. Migration in this context means that the database is configured to use Key Vault for wallet backup, and that the administrator intends to migrate to an Online Master Key (formerly knows as TDE direct connect).

You can continue to use the wallet, and upload wallet copies to Key Vault as part of every TDE key administration SQL operation, involving a WITH BACKUP SQL clause. (However, be aware that the WITH BACKUP clause is ignored by TDE in an Oracle Key Vault online key deployment, even if it is required for the ADMINISTER KEY MANAGEMENT statement.)

Example 8-1 shows examples of setting an encryption key.

Oracle Database, and thus TDE are endpoints for Oracle Key Vault. Endpoint enrollment and installation ensure that the PKCS#11 library is installed in the correct location for TDE to pick up and use. When the PKCS#11 library is installed, all other configurations and operations are in effect.

Example 8-1 Setting an Encryption Key

ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY secret_passphrase -- For Oracle Database 11g Release 2

ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY secret_passphrase WITH BACKUP; -- For Oracle Database 12c

Parent topic: Enrolling Endpoints for Oracle Key Vault

8.6 Endpoint okvclient.ora Configuration File

Oracle Key Vault endpoint libraries and utilities use a configuration file called okvclient.ora, where the configuration parameters associated with the endpoint are stored. The okvclient.ora file consists of key-value pairs separated by an equal sign (=). The following parameters, showing sample data, can be set in the endpoint configuration file:

SERVER=192.0.2.254:5696

This parameter specifies the IP address and port number of the Key Vault server, separated by a colon. If the port number is not specified, then it defaults to the standard KMIP port 5696.
STANDBY_SERVER=192.0.2.114:5696

This is the standby server. If high availability is configured, then this parameter shows the standby IP address. Otherwise, it shows the IP address as 127.0.0.1.
SSL_WALLET_LOC=/home/oracle/okvutil/ssl/

This parameter specifies the location of the wallet containing TLS credentials for the endpoint.
SERVER_POLL_TIMEOUT=300

The SERVER_POLL_TIMEOUT parameter allows you to specify a timeout for a client's attempt to connect to an Oracle Key Vault server, before trying the next server in the list. The default value is 300 (milliseconds).

In Oracle Key Vault 12.2.0.6.0, clients first establish a non-blocking TCP connection to Oracle Key Vault to quickly detect unreachable servers. Oracle Key Vault 12.2.0.6.0 introduces the SERVER_POLL_TIMEOUT parameter in the okvclient.ora file, after which Oracle Key Vault would attempt to connect to the next server. The default value is 300 (milliseconds).

After the first attempt, the client makes a second and final attempt to connect to the server but this time waits for twice as long as the duration specified by the SERVER_POLL_TIMEOUT parameter. This is done to overcome possible network congestion or delays.

Parent topic: Enrolling Endpoints for Oracle Key Vault

8.7 Oracle Key Vault okvutil Endpoint Utility Reference

After installing the endpoint software, endpoint administrators can use the command-line utility okvutil to communicate with Key Vault to upload and download security objects.

Parent topic: Enrolling Endpoints for Oracle Key Vault

8.7.1 About the okvutil Utility

the command-line utility okvutil enables you to locate, upload, and download security objects to and from Key Vault. You can also use okvutil to change the wallet password and collect system diagnostics.

The okvutil utility uses the TLS credentials provisioned for the endpoint to authenticate to Oracle Key Vault.

Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference

8.7.2 okvutil Command Syntax

The okvutil utility syntax provides short and long options for specifying commands.

Syntax

okvutil command arguments [-v verbosity_level]

Parameters

Table 8-2 okvutil Command Syntax

Parameter	Description
command	Refers to any of the following commands: `upload`, `list`, `download`, `changepwd`, `diagnostics`
arguments	Refers to the arguments that you pass for the accompanying command.
`-v, --verbose`	Refers to verbosity level. Possible values are 0,1, and 2. Verbosity level 2 provides the highest the level of detail that is printed to standard output during command execution. The meaning of verbosity values are as follows: `-v 0` disables verbose mode. `-v 1` includes debug messages. `-v 2` includes more detailed debug messages.
`-h`, `--help`	Use option to get help with any `okvutil` command. For example: okvutil command --help

Short and Long Forms of Specifying Options

You can specify the options in either a short form or a long form.

Note:

Endpoint platforms AIX and HP-UX (IA) support only short form options currently

Short form: Only use one hyphen and the single-letter option name. For example:
```
-l /home/username
-t wallet
```
Long form: Provide two hyphens and the full option name. For example:
```
--location /home/username 
--type wallet
```

The examples in this guide use the short form.

How Password Prompts for okvutil Work

The okvutil commands prompt for passwords in the following situations:

If you created a password-protected wallet during endpoint installation to access Oracle Key Vault.
If you specify an Oracle wallet file or Java keystore file using the -l option, okvutil prompts you to provide the password for the wallet or keystore that okvutil is trying to upload to Oracle Key Vault.

Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference

8.7.3 okvutil upload Command

The okvutil upload command uploads security objects to Key Vault such as: Oracle wallets including auto-login wallets, Java keystores, credential files, user-defined keys, and other types of key storage files.

You can upload Oracle wallets from all currently supported releases of Oracle Database and other Oracle software products that use Oracle wallets. The okvutil upload command opens the wallet or Java keystore and uploads each item found as an individual security object into Oracle Key Vault. If you are uploading credential files, then Key Vault uploads them as whole files called opaque objects.

Syntax

Short format:

okvutil upload [-o] -l location -t type [-g group] [-d description] [-v verbosity_level]

Long format:

okvutil upload [--overwrite] --location location --type type [--group group] [--description description] [--verbose verbosity_level]

Parameters

Table 8-3 okvutil upload Command Options

Parameter	Description
`-o`, `--overwrite`	If there are conflicts with the existing data in the Oracle Key Vault virtual wallet, then Key Vault replaces the existing data with new data that is sent by the endpoint. If there are no conflicts, then the overwrite operation is not necessary and is not performed. Use care if you plan to specify this option.
`-l`, `--location`	Specifies the location of an Oracle wallet file, Java keystore, or a text file containing user-defined and hex-encoded TDE master encryption identifier and key. For an Oracle wallet, the location is the directory that contains the `.p12` or `.sso` files. If you are uploading a credential file as an opaque object, then ensure that this file is no larger than 120 kilobytes (KB).
`-t,` `--type`	Specifies the data type of the object being uploaded to Oracle Key Vault. It must be a value from the following list: `WALLET` for an Oracle wallet `JKS` for a Java keystore `JCEKS` for a Java Cryptography Extension keystore (JCEKS) `SSH` for an SSH key file, to be uploaded as an opaque object. The maximum size is 120 KB. `KERBEROS` for a Kerberos keytab, to be uploaded as an opaque object. The maximum size is 120 KB. `TDE_KEY_BYTES` for a user-defined key to be used as a TDE master encryption key. `OTHER` for opaque objects, which are other files that store secrets. The maximum size is 120 KB. The `WALLET`, `JKS`, and `JCEKS` types contain multiple objects. Oracle Key Vault uploads each of these objects individually. The `SSH`, `KERBEROS`, `TDE_KEY_BYTES`, and `OTHER` types, being opaque objects, are uploaded as single files. This setting is not case-sensitive.
`-g`, `--group`	Is the name of a Key Vault virtual wallet to which the certificate store or secret store (or both) are added. This name is case-sensitive. The virtual wallet must already exist, and the user must have authorization to access it. If you omit this setting, then the default group, if there is one, is used. If there is no default group and you omit the `-g`, `--group` option, then the data uploaded will not be placed in a group.
`-d`, `--description`	Enables you to add a description, up to 2000 bytes. It is valid only if the `-t` `type`, `--type` parameter is set to `SSH`, `KERBEROS`, `TDE_KEY_BYTES`, or `OTHER`. Optional. Enclose this description in double quotation marks. If there are spaces within this description, then include escape characters with the quotation marks. For example: `-d \"text with spaces\"`
`-v`, `--verbose`	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Uploading a Java Keystore Using the -v2 Option

The okvutil upload command enables you to upload a Java keystore.

The following example shows you how to use the okvutil upload command to upload a Java keystore. The -v 2 option enables the command to list the items that are uploaded.

The okvutil command prompts if necessary for passwords to connect to Oracle Key Vault and to open the Oracle wallet file.

$ okvutil upload -l ./fin_jceks.jck -t JCEKS -g fin_wal -v 2

okvutil version 12.2.0.0.0
Configuration file: /tmp/fin_okv/conf/okvclient.ora
Server: 192.0.2.254:5696
Standby Server: 127.0.0.1:5696
Uploading from /tmp/fin_okv/keystores/jks/keystore.jks
Enter source Java keystore password:
Uploading private key
Uploading trust point
Uploading trust point
Uploading private key
Uploading private key
 
Uploaded 3 private keys
Uploaded 0 secret keys
Uploaded 2 trust points
 
Upload succeeded

For more information about uploading a Java Keystore, see Uploading JKS or JCEKS Keystores.

Uploading a Password-Protected Wallet File

The okvutil upload command uploads a password-protected wallet file.

The following example shows you how to upload a password-protected wallet file when there is no password for the endpoint to connect to Oracle Key Vault.

$ okvutil upload -l . -t WALLET -g FinanceWallet 
Enter source wallet password: password

Upload succeeded

For more information about uploading wallet files, see Uploading Oracle Wallets.

Uploading a User-defined key to use as a TDE master encryption key

The okvutil upload command enables you to upload a user-defined key to use as a TDE master encryption key.

The following example shows you how to upload a user-defined key.

$ okvutil upload -l /tmp/tde_key_bytes.txt -t TDE_KEY_BYTES -g "FIN_DATABASE_VIRTUAL_WALLET" -d \"This key was created for Financial database use on 1st Jan 2018\"

For more information about uploading an user-defined key, see Uploading the User-Defined Key.

See Also:

"Add Security Objects to a Virtual Wallet"
"Uploading Oracle Wallets"
Oracle Database Security Guide for detailed information about the orapki utility

Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference

8.7.4 okvutil list Command

The okvutil list command gets the available security objects that are uploaded. When used without options or with the -g group option, it displays the unique ID, object type, and a descriptor for each item it lists from Oracle Key Vault.

Syntax

Short format:

okvutil list [-l location -t type | -g group] [-v verbosity_level]

Long format:

okvutil list [--location location --type type | --group group] [--verbose verbosity_level]

Parameters

Table 8-4 okvutil list Command Options

Parameter	Description
`-l`, `--location`	Specifies the location of an Oracle wallet file or a Java keystore. For an Oracle wallet, the location is the directory that contains the `.p12` or `.sso` files. For all other types, the location is the path name of the file itself. If you omit the `-l`, `--location` option, then the default location is Oracle Key Vault. In this case, the `okvutil list` command lists all the available keys in the server. If you use this setting, then you must also include the `-t`, `--type` setting, described next.
`-t`, `--type`	Specifies one of the following types: `WALLET` for an Oracle wallet `JKS` for the Java keystore `JCEKS` for the Java Cryptography Extension keystore (JCEKS) `OKV_PERSISTENT_CACHE` for the persistent cache of Oracle Key Vault The `WALLET`, `JKS`, and `JCEKS` types are containers for security objects which Oracle Key Vault lists individually. The `SSH`, `KERBEROS`, and `OTHER` are opaque objects, and are listed as single files. This setting is not case-sensitive.
`-g`, `--group`	Lists the content from a single virtual wallet. This option only applies when you omit the `-l`, `--location` option to list the objects stored in Oracle Key Vault.
`-v`, `--verbose`:	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Example: Listing Security Objects for the Current Endpoint

The okvutil list command enables you to see the security objects associated with the current endpoint.

Example 8-2 gets all the authorized security objects for the current endpoint. In the last three lines, the DB Connect Password entries refer to the password that was used to log in to the instance (for example, the password for user psmith on the database instance inst01).

Example: Listing the Contents of an Oracle Wallet File

The okvutil list command enables you to see the contents of an Oracle wallet file.

Example 8-3 shows the contents of an Oracle wallet file.

Example 8-2 Listing Security Objects for the Current Endpoint

$ okvutil list
Enter Oracle Key Vault endpoint password: password

Unique ID                               Type           Identifier
F63E3F4A-C8FB-5560-E043-7A6BF00AA4A6    Symmetric Key  TDE Master Key: 062C4F5BAC53E84F2DBF95B96CE577B525
F63E3F4A-C8FC-5560-E043-7A6BF00AA4A6    Symmetric Key   TDE Master Key: 069A5253CF9A384F61BFDD9CC07D8A6B07
F63E3F4A-C8FD-5560-E043-7A6BF00AA4A6    Opaque Object   -
F63E3F4A-C8FE-5560-E043-7A6BF00AA4A6    Symmetric Key   TDE Master Key: 06A66967E70DB24FE6BFD75447F518525E
F63E3F4A-C8FF-5560-E043-7A6BF00AA4A6    Symmetric Key   TDE Master Key: 0636D18F2E3FF64F7ABF80900843F37456
F63E3F4A-C900-5560-E043-7A6BF00AA4A6    Opaque Object   -
F63E3F4A-C901-5560-E043-7A6BF00AA4A6    Symmetric Key   TDE Master Key: 0611E6ABD666954F2FBF8359DE172BA787
F63E3F4A-C902-5560-E043-7A6BF00AA4A6    Symmetric Key   TDE Master Key: 0657F27D64D1C04FAEBFE00B5105B3CBAD
F63E3F4A-C91B-5560-E043-7A6BF00AA4A6    Opaque Object   Certificate Request
F63E3F4A-C91C-5560-E043-7A6BF00AA4A6    Certificate     X509 DN:OU=Class 1 Public Primary Certification Authority,O=VeriSign\, Inc.,C=US 
F63E3F4A-C903-5560-E043-7A6BF00AA4A6    Secret Data     DB Connect Password: psmith@inst01
F63E3F4A-C904-5560-E043-7A6BF00AA4A6    Secret Data     DB Connect Password: jdaley@inst02
F63E3F4A-C905-5560-E043-7A6BF00AA4A6    Secret Data     DB Connect Password: tjones@inst03

Example 8-3 Listing the Contents of an Oracle Wallet File

$ okvutil list -t WALLET -l /home/oracle/wallets
Enter target wallet password: Oracle_wallet_password

Dumping secret store of wallet:
ORACLE.SECURITY.DB.ENCRYPTION.MASTERKEY
ORACLE.SECURITY.DB.ENCRYPTION.Aa4JEUaCeE8qv0Dsmmwe5S4AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
ORACLE.SECURITY.ID.ENCRYPTION.
ORACLE.SECURITY.KB.ENCRYPTION.
ORACLE.SECURITY.TS.ENCRYPTION.BZuIPES7+k/tv0ZwOlDeIp4CAwAAAAAAAAAAAAAAAAAAAAAAAAAA
Dumping cert store of wallet:
 
There are 1 Certificate Requests in the list
 
Certificate request:
        DN: CN=oracle
        Type: NZDST_CERT_REQ
        PUB key size: 2048
 
There are 0 Certificates in the list
 
There are 0 TPs in the list

Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference

8.7.5 okvutil download Command

The okvutil download command downloads security objects from Oracle Key Vault to the endpoint such as: Oracle wallets including auto-login wallets, Java keystores, credential files, and other types of key storage files.

You can only download the contents of a virtual wallet into a keystore (a container such as an Oracle wallet or a JCEKS keystore that can hold multiple security objects), and not into a credential file.

Note that some keystores only support the storage of certain types of security objects. An error occurs if you upload a DSA key from a Java keystore and later try to download it to a different type of keystore like an Oracle wallet.

Syntax

Short format:

okvutil download -l location -t type [-g group | -i object_id] [-o] [-v verbosity_level]

Long format:

okvutil download --location location --type type [--group group | --item object_id] [--overwrite] [--verbose verbosity_level]

Parameters

Table 8-5 okvutil download Command Options

Parameter	Description
`-l`, `--location`	Specifies the file location to store the items that you want to download. Ensure that you have permission to create wallets in this location. Ensure that the file you download is no more than 120 KB. This setting is mandatory.
`-t`, `--type`	Specifies the data type of the object being downloaded to Oracle Key Vault. It must be a value from the following list: `WALLET` for an Oracle wallet `JKS` for a Java keystore `JCEKS` for a Java Cryptography Extension keystore (JCEKS) `SSH` for an SSH key file, to be downloaded as an opaque object. `KERBEROS` for a Kerberos keytab, to be downloaded as an opaque object. `OTHER` for opaque objects, which are other files that store secrets. The `WALLET`, `JKS`, and `JCEKS` types contain multiple objects. Oracle Key Vault downloads each of these objects individually. The `SSH`, `KERBEROS`, and `OTHER` types, being opaque objects, are downloaded as single files. This setting is not case-sensitive. This setting is mandatory.
`-g, --group`	Is the name of a virtual wallet from which you download an item for the `WALLET`, `JKS`, and `JCEKS` types. The virtual wallet must already exist, and the user must have authorization to access it. The `okvutil` utility downloads the entire virtual wallet specified by the `-g` option, and stores it in a new wallet. There must be no existing wallet at the specified location. The `okvutil` utility will create one. `okvutil` prompts you to create and enter a password for the new wallet. Record that password for the future. Remember that the group name is case-sensitive. If the type is `WALLET`, `JKS`, or `JCEKS`, then you can either include or omit the `group` setting. If the type is `SSH`, `KERBEROS`, or `OTHER`, then you must include the `object_id` option, but not include the `group` setting.
`-i`, `--item`	Refers to the unique ID of the object that you want to download, such as secrets (for example, `-i oracle.security.client.password1` for the first secure external password store (SEPS) entry inside a wallet).
`-o`, `--overwrite`	Downloads data into an existing `WALLET`, `JKS`, or `JCEKS` file specified by `-l`, which must exist. If a conflict arises between the data to download and the data that already exists in the container, then the new data overwrites the old data. The `-o`, `--overwrite` option does not apply to the other types (`SSH`, `KERBEROS`, and `OTHER`). Use care if you plan to specify this option. If you omit the `o` or `overwrite` option when you download wallets that already exist in the current directory, then the original wallet file is renamed to either `ewallet.p12.timestamp.bak` or `owallet.sso.timestamp.bak` before the new wallet file is downloaded. For files that are not wallets (such as Java keystore files), an error appears, and you will need to rename the file or move it to a new location before performing the download.
`-v`, `--verbose`	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Example: Downloading a Virtual Wallet to a Java Keystore

The okvutil download command enables you to download a virtual wallet to a Java keystore.This is useful if you are sharing the same Java key store across multiple application servers and want to use the same wallet.

Example 8-4 downloads the Key Vault virtual wallet FinanceWallet to a Java keystore.

See Also:

You can find the available object IDs by running the okvutil list command, described in "okvutil list Command"
"Downloading Oracle Wallets"

Example 8-4 Downloading a Virtual Wallet to a Java Keystore

$ okvutil download -l ./fin/okv/work -t JCEKS -g FinanceWallet

The command will prompt for a new password for the Java Keystore as below:

Enter new Java keystore password:
Confirm new Java keystore password:
Download succeeded

Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference

8.7.6 okvutil changepwd Command

The okvutil changepwd command enables you to change the password associated with the credentials used to connect to Oracle Key Vault. Use this command if you used a password-protected wallet to store the Oracle Key Vault endpoint user credentials. The new password need not be the same password for the JCKS or wallet file when it was uploaded.

Syntax

Short format:

okvutil changepwd -l location -t type [-v verbosity_level]

Long format:

okvutil changepwd --location location --type type [--verbose verbosity_level]

Parameters

Table 8-6 okvutil changepwd Command Options

Parameter	Description
`-l`, `--location`	Specifies the directory location of the wallet whose password you want to change.
`-t`, `--type`	Specifies the data type. Enter `WALLET`.
`-v, --verbose`	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug).

Example: Changing an Oracle Key Vault Endpoint Password

the okvutil changepwd enables you to change the password of an endpoint.

Example 8-5 shows how to change the endpoint password. When you are prompted to create the new password, enter a password that is between 8 and 30 characters.

Example 8-5 Changing an Oracle Key Vault Endpoint Password

$ okvutil changepwd -l ./home/oracle/okvutil/ssl -t WALLET
Enter wallet password: current_endpoint_password
Enter new wallet password: new_endpoint_password
Confirm new wallet password: new_endpoint_password

Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference

8.7.7 okvutil diagnostics Command

The okvutil diagnostics command enables you to collect diagnostic and environmental information on an endpoint to troubleshoot deployment issues. The information is gathered in a diagnostics.zip file, which can be given to Oracle support for further analysis and debugging.

The information gathered includes information on:

The Shell environment variables: OKV_HOME, ORACLE_HOME, ORACLE_BASE, ORACLE_SID, PATH, CLASSPATH
Configuration and IP address of the Key Vault server from okvclient.ora
Directory listing of OKV_HOME and its sub-directories
Key Vault log files from the endpoint
Listing of symbolic links created by the Key Vault endpoint installer
Network settings and ping results

No sensitive user information like user credentials or security objects are collected.

Syntax

Short format:

okvutil diagnostics [-v verbosity_level]

Long format:

okvutil diagnostics  [--verbose verbosity_level]

Parameters

Table 8-7 okvutil diagnostics Command Options

Parameter	Description
`-v, --verbose`	Refers to the verbosity level from 0 (none), 1 (debug), 2 (detailed debug)

Example: Collecting System Diagnostics

the okvutil diagnostics command enables you to collect system diagnostics in a zip file.

Example 8-6 shows you how to execute the command. Wait until you see the message Diagnostics complete message to see the diagnostics.zip file in the same directory.

Example 8-6 Collecting System Diagnostics

$ okvutil diagnostics 
Diagnostics collection complete.
ls
diagnostics.zip

Parent topic: Oracle Key Vault okvutil Endpoint Utility Reference

8.8 Upgrading Endpoint Software on an Enrolled Endpoint

You would upgrade the endpoint software on an enrolled endpoint any time you upgraded to a new release of Oracle Key Vault so you have the latest software on both the Oracle Key Vault server and the endpoint. This is highly recommended for optimum performance.

Oracle Key Vault servers are capable of working with endpoint software from the prior major release, but may not work properly with endpoint software that are older.

To upgrade the software on an already enrolled endpoint you only need to download and install the software okvclient.jar on the endpoint. You do not need to re-enroll the endpoint.

To upgrade endpoint software on an enrolled endpoint:

Log in to the endpoint server as the endpoint administrator.
Connect to the Oracle Key Vault management console.

For example:

https://192.0.2.254
The login page to the Oracle Key Vault management console appears. Do not log in.

Figure 8-3 Key Vault Management Console Login Screen

Description of "Figure 8-3 Key Vault Management Console Login Screen"
Click Endpoint Enrollment and Software Download.

The Enroll Endpoint & Download Software page appears with two tabs: Enroll Endpoint & Download Software and Download Endpoint Software Only.
Click Download Endpoint Software Only.

The Download Endpoint Software Only page appears.

Figure 8-4 has been trimmed with the result that some part of the message is truncated. The entire message follows:

To download only the endpoint software, select platform and click 'Download'. This applies if you've already enrolled and would like to download endpoint software only in case of an upgrade.

Figure 8-4 Download Endpoint Software Only

Description of "Figure 8-4 Download Endpoint Software Only"
Select the Platform from the drop down list and click Download.

A directory window appears, and prompts you to save the endpoint software file: okvclient.jar. Navigate to the folder where you want to save the file.
Save the file.
Verify that the file is downloaded.
Now you are ready for Task 2: Install Oracle Key Vault Software on the Endpoint.

Parent topic: Enrolling Endpoints for Oracle Key Vault