10 Enrolling Endpoints for Oracle Key Vault

After an endpoint is registered in Oracle Key Vault, an endpoint administrator enrolls and provisions the endpoint to manage security objects in Key Vault.

• About Endpoint Enrollment and Provisioning
  Endpoints are Key Vault clients that use the server to store and manage security objects, share them with trusted peers, and retrieve them.
• Finalizing Enrollment and Provisioning
  To enroll and provision a registered endpoint an endpoint administrator must download and then install the okvclient.jar file.
• Environment Variables and Endpoint Provisioning Guidance
  Environment variables such as JAVA_HOME and OKV_HOME must be correctly set so that Oracle Key Vault can access its utilities.
• Endpoints That Do Not Use the Oracle Key Vault Client Software
  Third-party KMIP endpoints do not use the Oracle Key Vault software okvutil and liborapkcs.so.
• Transparent Data Encryption Endpoint Management
  Oracle Key Vault can manage TDE keys by using the same PKCS#11 interface that TDE uses to communicate with an external keystore.
• Endpoint okvclient.ora Configuration File
  Oracle Key Vault endpoint libraries and utilities use the okvclient.ora configuration file, which stores the configuration parameters associated with the endpoint.

10.1 About Endpoint Enrollment and Provisioning

Endpoints are Key Vault clients that use the server to store and manage security objects, share them with trusted peers, and retrieve them.

These clients can be systems like Oracle database servers, Oracle middleware servers, operating systems, and other information systems.

An Oracle Key Vault system administrator first adds (or registers) the endpoint to Key Vault, and 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.

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

Table 10-1 Summary of Endpoint Enrollment

Step#	Task	Performed by	Endpoint Status (as seen on Oracle Key Vault Management Console)
1.	System administrator creates an endpoint. If this is an Oracle database, a key administrator creates a virtual wallet. System administrator adds or registers the endpoint to Oracle Key Vault. An enrollment token for the endpoint is generated. System administrator sends the enrollment token to the endpoint administrator to complete the enrollment process.	Users with the System Administrator role and Key Administrator role on Oracle Key Vault	Registered
2.	Verify the enrollment token. Submit enrollment token to download endpoint software okvclient.jar to the endpoint.	Endpoint administrator using the Oracle Key Vault management console	Enrolled
3.	Install okvclient.jar on the endpoint.	Endpoint administrator on endpoint	Enrolled

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

okvclient.jar contains the following:

• A Transport Layer Security (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 such as the Oracle 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. Each Oracle RAC-enabled database corresponds to one virtual wallet in Oracle Key Vault. Each Oracle RAC instance of that database corresponds to an endpoint in Oracle Key Vault. All endpoints for each database share the same wallet as their default wallet. You must download one distinct okvclient.jar for each instance.

10.2 Finalizing Enrollment and Provisioning

To enroll and provision a registered endpoint an endpoint administrator must download and then install the okvclient.jar file.

• Step 1: Enroll the Endpoint and Download the Software
  You must have the endpoint's enrollment token before you can download the endpoint software okvclient.jar.
• Step 2: Prepare the Endpoint Environment
  You must ensure that you have the right version of the Java Development Toolkit (JDK) and that the Oracle environment variables are set.
• Step 3: Install the Oracle Key Vault Software onto the Endpoint
  To upgrade to the latest endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint.
• Step 4: Perform Post-Installation Tasks
  The post-installation procedures include optionally configuring a TDE connection for the endpoint, checking the installation contents, and deleting the okvclient.jar file.

10.2.1 Step 1: Enroll the Endpoint and Download the Software

You must have the endpoint's enrollment token before you can 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.

1. Log in to the endpoint server as the endpoint administrator.
2. 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.

3. In the lower right corner of the login page, click the Endpoint Enrollment and Software Download button, which is below the Login button.
   The Enroll Endpoint & Download Software page appears.

   
   Description of the illustration ep_sw_download_page1.png

4. At the top of the page, click the Enroll Endpoint & Download Software tab.
   The next two steps depend on how the endpoint was added to or registered with Oracle Key Vault.
5. If the endpoint was registered by an Oracle Key Vault system administrator, then do the following:
   1. Enter the endpoint's enrollment token in Enrollment Token, and click Submit Token.

      If the token is valid, then a valid token message appears to the right of the Submit Token button. The Endpoint Type, Endpoint Platform, Email and Description fields are automatically populated with the values that were entered during endpoint registration.

      If the token is invalid, then an invalid token message appears. Check the token and retry the download procedure.

   2. Click Enroll at the top right corner of the page.
6. If the endpoint was registered by self-enrollment, then do the following:
   1. Bypass the step of validating the token because self-enrolled endpoints have no enrollment token.
   2. From the Endpoint Type list, select the type of endpoint: Oracle Database, Oracle (non-database), or Other. If you are using Transparent Data Encryption (TDE), then you must enter Oracle Database.
   3. From the Endpoint Platform list, select the platform: Linux, Solaris SPARC, Solaris x64, AIX, HPUX, Windows.
   4. In the Email field, enter the email address of the endpoint administrator, for notification purposes. This field is optional but recommended.
   5. In the Description field, enter meaningful and identifying information for the endpoint. This field is also optional but strongly recommended.
   6. Click Enroll at the top right corner of the page.
7. In the directory window that appears, follow the prompt to save the okvclient.ora endpoint software file.
   You must navigate to the directory where you want to save the file.
8. Save the file to a secure directory with appropriate permissions in place so that it cannot be read or copied by others.
9. Verify that the file has been downloaded.
   If the download fails, then you must obtain a new enrollment token from the key administrator for the endpoint and repeat these steps, starting with Step 5. 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.

At this stage, you are ready to install the Oracle Key Vault okvclient.jar software file on the endpoint, starting with preparing the endpoint environment.

10.2.2 Step 2: Prepare the Endpoint Environment

You must ensure that you have the right version of the Java Development Toolkit (JDK) and that the Oracle environment variables are set.

1. Ensure that you have the necessary administrative privileges to install software on the endpoint.
2. 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.
3. Run the shell utility oraenv or source oraenv command to set the correct environment variables on Oracle Database servers.
4. Check that the environment variables ORACLE_BASE and ORACLE_HOME are correctly set.
   If you used oraenv to set these variables, then 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.

10.2.3 Step 3: Install the Oracle Key Vault Software onto the Endpoint

To upgrade to the latest endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint.

1. Ensure that you are logged in to the endpoint server as the endpoint administrator.
2. Navigate to the directory in which you saved the okvclient.jar file.
3. Confirm that the target directory exists, and that it is empty.
4. Run the java command to install the okvclient.jar file.

   java -jar okvclient.jar -d /home/oracle/okvutil -v
   

   In this specification:

   • -d specifies the directory location for the endpoint software and configuration files, in this case /home/oracle/okvutil.

   • -v writes the installation logs to the /home/oracle/okvutil/log/okvutil.deploy.log file at the server endpoint.

   -o is an optional argument that enables you to overwrite the symbolic link reference to okvclient.ora when okvclient.jar is deployed in a directory other than the original directory. This argument is used only when you re-enroll an endpoint.

   If you are installing the okvclient.jar file on a Windows endpoint system that has Oracle Database release 11.2.0.4 only, then include the -db112 option. (This option is not necessary for any other combination of endpoint platform or Oracle Database version.) For example:

   java -jar okvclient.jar -d /home/oracle/okvutil -v -db112

5. When you are prompted for a password, then perform either of the following two steps.
   The optional password goes into two places: okvutil and in ADMINISTER KEY MANAGEMENT. With okvutil, only users who know that password can upload or download content to and from Oracle Key Vault. With ADMINISTER KEY MANAGEMENT, it becomes the password that you must use in the IDENTIFIED BY password clause. If you choose not to give a password, then okvutil upload and download commands will not prompt for a password, and the password for ADMINISTER KEY MANAGEMENT becomes NULL.NULL is used for an auto-login wallet.
   The choices for handling the password are as follows:
   • If you want to create a password-protected wallet, at minimum enter a password between 8 and 30 characters and then press Enter. For better security, Oracle recommends that you include uppercase letters, lowercase characters, special characters, and numbers in the password. The following special characters are allowed: (.), comma (,), underscore (_), plus sign (+), colon (:), space.

     Enter new Key Vault endpoint password (<enter> for auto-login): Key_Vault_endpoint_password
     Confirm new endpoint password: Key_Vault_endpoint_password
     

     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.

   • Alternatively, enter no password and then press Enter.

     No password will be required when the endpoint connects to Oracle Key Vault with okvutil. With the ADMINISTER KEY MANAGEMENT statement, the password becomes NULL.

   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.

10.2.4 Step 4: Perform Post-Installation Tasks

The post-installation procedures include optionally configuring a TDE connection for the endpoint, checking the installation contents, and deleting the okvclient.jar file.

1. Optionally, configure a TDE connection for the endpoint.
   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.
   • On Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations: Log in as the root and then execute either of the following commands:

     $ sudo bin/root.sh
     

     Or:

     $ su -
     # bin/root.sh
     

     This command creates the directory tree /opt/oracle/extapi/64/hsm/oracle/1.0.0, changes ownership and permissions, then copies the PKCS#11 library into this directory.

   • On Windows installations: Run the following command:

     bin\root.bat

     This command copies the liborapkcs.dll file to the C:\oracle\extapi\64\hsm\oracle\1.0.0 directory.

2. Use a command such as namei or ls -l to confirm that a softlink was created in $ORACLE_BASE/okv/$ORACLE_SID/okvclient.ora to point to the real file in the /conf subdirectory of the installation target directory.
   If the ORACLE_BASE environment variable has not been set, then the softlink was created in $ORACLE_HOME/okv/$ORACLE_SID.
3. 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.

   $ ./okvutil list

   If the endpoint is able to connect to Key Vault, then the No objects found message appears. If a Server connect failed message appears, then you must troubleshoot the installation for possible issues. Check that environment variables are correctly set. To get help on the endpoint software, execute the following command:

   java -jar okvclient.jar -h
   
   

   Output similar to the following appears:

   Production on Fri Apr 12 15:03:01 PDT 2019
   Copyright (c) 1996, 2019 Oracle. All Rights Reserved.
   Usage:
     java -jar okvclient.jar [-h | -help] [[-v | -verbose] [-d <destination directory>] [-o]]
   
   Options:
     -h or -help : Display command help.
     -v or -verbose : Turn on the verbose mode. Logs will be written to files under
                      <destination directory>/log/ directory.
     -d <destination directory> : Specify the software installation directory.
     -o : Overwrite the current symbolic link to okvclient.ora.
   

4. After you complete the installation, securely delete the okvclient.jar endpoint software file.

10.3 Environment Variables and Endpoint Provisioning Guidance

Environment variables such as JAVA_HOME and OKV_HOME must be correctly set so that Oracle Key Vault can access its utilities.

• How the Location of JAVA_HOME Location Is Determined
  The default location for the okvclient.ora file is the $OKV_HOME/conf directory.
• 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.
• Setting OKV_HOME for Non-Database Utilities to Communicate with Oracle Key Vault
  For non-database utilities, you must set the environment variable OKV_HOME to point to the destination directory for the endpoint software.
• Environment Variables in sqlnet.ora File
  You must consider several points while using the srvctl utility on Oracle Database endpoints.

10.3.1 How the Location of JAVA_HOME Location Is Determined

The default location for the okvclient.ora file is the $OKV_HOME/conf directory.

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

The endpoint software installation process uses the following 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, then the installation process looks for it in the java.home system property of the Java Virtual Machine (JVM).

After the JAVA_HOME path is determined, the installation process adds it to the okvclient.ora configuration file to be used by all okvutil commands.

You can force okvutil to use a different JAVA_HOME setting by using one of the following 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

10.3.2 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 okvclient.ora file is a configuration file in the $OKV_HOME/conf directory .

In addition to the $OKV_HOME/conf file, the installation process creates a soft link to okvclient.ora for an existing database. The location of the soft link depends on the following:

• If the $ORACLE_BASE environment 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 environment variable is set but 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.

10.3.3 Setting OKV_HOME for Non-Database Utilities to Communicate with Oracle Key Vault

For non-database utilities, you must set the environment variable OKV_HOME to point to the destination directory for the endpoint software.

You must manually set OKV_HOME because the installation process does not set this variable automatically. Setting OKV_HOME enables utilities to communicate with Oracle 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 such as RMAN. For example, if you spawn a new xterm window, then you will need to set OKV_HOME in this environment before running RMAN.

10.3.4 Environment Variables in sqlnet.ora File

You must consider several 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.

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

• The operating system and srvctl utility should have $ORACLE_SID, $ORACLE_HOME and $ORACLE_BASE set to the same values.

10.4 Endpoints That Do Not Use the Oracle Key Vault Client Software

Third-party KMIP endpoints do not use the Oracle Key Vault software okvutil and liborapkcs.so.

In this case you must manually set the Transport Layer Security (TLS) authentication as follows:

1. Extract the ssl directory from the okvclient.jar file.

   jar xvf okvclient.jar ssl
   

2. 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

10.5 Transparent Data Encryption Endpoint Management

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 Oracle Key Vault for storing and retrieving TDE master encryption 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, you can directly upload the keys in the wallet to Oracle 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 Oracle 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 TDE ignores the WITH BACKUP clause in an Oracle Key Vault online key deployment, even if it is required for the ADMINISTER KEY MANAGEMENT statement.

Oracle Database 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 10-1 shows examples of setting an encryption key.

Example 10-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 and later

10.6 Endpoint okvclient.ora Configuration File

Oracle Key Vault endpoint libraries and utilities use the okvclient.ora configuration file, which stores the configuration parameters associated with the endpoint.

The okvclient.ora file consists of key-value pairs separated by an equal sign (=). You can set the following parameters in the endpoint configuration file:

• SERVER=node1_IP:node1_port/node1_DN,node2_IP:node2_port/node2_DN,...

  This parameter specifies the IP address and port number of the Oracle 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=standby_server_IP:standby_server port

  This is the standby server. If primary-standby is configured, then this parameter shows the standby IP address.

• READ_SERVER=node1_IP:node1_port/node1_DN,node2_IP:node2_port/node2_DN,...

  This parameter specifies the list of read-only servers.

• SSL_WALLET_LOC=directory

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

• SERVER_POLL_TIMEOUT=timeout_value

  You can use the SERVER_POLL_TIMEOUT parameter 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 clients first establish a non-blocking TCP connection to Oracle Key Vault to quickly detect unreachable servers.

  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.

The CONF_ID value in an okvclient.ora file is a unique internal value that helps an Oracle database to find its virtual wallet in Oracle Key Vault. Do not modify this value.