1. Administrator's Guide
  2. Enrolling and Upgrading Endpoints for Oracle Key Vault

13 Enrolling and Upgrading 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.

13.1 About Endpoint Enrollment and Provisioning

Endpoints are Oracle 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.

If you plan to configure the extraction of symmetric keys from Oracle Key Vault to false (to prevent them from being extracted), it is important that you first upgrade the endpoint to Oracle Key Vault release 21.4.

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 13-1 Summary of Endpoint Enrollment

Step# Task Performed by Endpoint Status (as seen on Oracle Key Vault Management Console)

1.

  1. System administrator or user with Manage Endpoint privilege creates an endpoint.

  2. If this is an Oracle database, a key administrator creates a virtual wallet.

  3. System administrator adds or registers the endpoint to Oracle Key Vault. An enrollment token for the endpoint is generated.

  4. 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, or user with the Manage Endpoint privilege

Registered

2.

  1. Verify the enrollment token.

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

Related Topics

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

13.2 Finalizing Enrollment and Provisioning

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

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

13.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 Oracle 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. Click the Endpoint Enrollment and Software Download button, which is below the Login button.
    The Enroll Endpoint & Download Software page appears.

    Description of 21_endpoint_download_fresh.png follows
    Description of the illustration 21_endpoint_download_fresh.png

  4. 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 below the Enrollment Token field. 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.
  5. In the directory window that appears, follow the prompt to save the okvclient.jar endpoint software file.
    You must navigate to the directory where you want to save the file.
  6. Save the file to a secure directory with appropriate permissions in place so that it cannot be read or copied by others.
  7. 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 4. 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.

Related Topics

Parent topic: Finalizing Enrollment and Provisioning

13.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.6 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.6, 7, and 8. The 64-bit version of Java is required.
  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.
  5. Shut down the database if you are installing the endpoint software for an Oracle database configured for online TDE master encryption key management.
  6. As an endpoint administrator, shutdown the Oracle database server.

Parent topic: Finalizing Enrollment and Provisioning

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

You can install the endpoint using downloaded okvclient.jar file.

Note:

To upgrade to the latest endpoint software for an enrolled endpoint, you can download the endpoint software without having to re-enroll the endpoint.
  1. Ensure that you are logged in to the endpoint server as the endpoint administrator.

    Note:

    If you are installing the endpoint software for an Oracle database configured for online TDE master encryption key management, then shut down the database.
  2. Ensure that the Oracle database is shutdown.
  3. Navigate to the directory in which you saved the okvclient.jar file.
  4. Confirm that the target directory exists, and that it is empty.
  5. Run the java command to install the okvclient.jar file.
    java -jar okvclient.jar -d /home/oracle/okv_home -v

    In this specification:

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

    • -v writes the installation logs to the /home/oracle/okv_home/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.

    Note:

    If you are installing the okvclient.jar file on an Oracle Database Windows endpoint system, then make sure that the java command to install okvclient.jar file is run with administrator privileges and $ORACLE_BASE/okv/$ORACLE_SID/ or $ORACLE_HOME/okv/$ORACLE_SID is a valid path on NTFS or ReFS filesystem. Failing to do so may cause installation to fail because on Windows platform administrator privileges are required to create $ORACLE_BASE/okv/$ORACLE_SID/okvclient.ora or $ORACLE_HOME/okv/$ORACLE_SID softlink during installation and softlink creation is only supported on NTFS or ReFS filesystem.
  6. 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.
    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.
    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 file okveps.x64

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

    Note:

    Oracle recommends that you use the password-protected wallet.

Parent topic: Finalizing Enrollment and Provisioning

13.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. Update the PKCS#11 library 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.
    If an endpoint uses online TDE master encryption key management by Oracle Key Vault, then you must install the PKCS#11 library by using root.sh or root.bat script.

    Note:

    • You must run root.sh or root.bat script to install the Oracle Key Vault PKCS#11 library only once on a host machine that has multiple TDE-enabled Oracle databases that use Oracle Key Vault for master encryption key management.
    • Ensure that you execute the root.sh or root.bat script only after the installation of the Oracle Key Vault endpoints for all of the TDE-enabled databases on the same host machine is complete.
    • Ensure that all of the TDE-enabled Oracle databases on this host are shutdown.
    • On Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations: Log in as the root user 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. Start the Oracle databases if the installation of upgrade of the Oracle Key Vault endpoints for all of the TDE-enabled databases on this host machine is complete.
  4. 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.

Parent topic: Finalizing Enrollment and Provisioning

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

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

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

Restart the endpoint database after you set the JAVA_HOME variable in okvclient.ora.

You may need to periodically manually update the value of the JAVA_HOME environment variable setting in the okvclient.ora file. This can happen when a newer version of Java is installed and the previous version of Java is removed. To do this, first shut down the endpoint database, so that okvclient.ora is not overwritten by the database processes. Then, manually update the value of JAVA_HOME in okvclient.ora.

Parent topic: Environment Variables and Endpoint Provisioning Guidance

13.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 soft link to the okvclient.ora configuration file (in $OKV_HOME/conf) in the $ORACLE_BASE/okv/$ORACLE_SID location.

    If a soft link to okvclient.ora 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 soft link for the $ORACLE_HOME/okv/$ORACLE_SID location to point to the configuration file in the $OKV_HOME/conf directory.

Parent topic: Environment Variables and Endpoint Provisioning Guidance

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

Parent topic: Environment Variables and Endpoint Provisioning Guidance

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

Parent topic: Environment Variables and Endpoint Provisioning Guidance

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

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

13.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 encryption key (formerly knows as TDE direct connect).

You can continue to use the wallet, and upload wallet copies to Oracle 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 13-1 shows examples of setting an encryption key.

Example 13-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 or later

Related Topics

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

13.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 (=). At minimum, 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 and the server DN separated by a slash. 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.

  • PKCS11_PERSISTENT_CACHE_FIRST=value sets the persistent master encryption key cache operation mode.

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 any settings in the okvclient.ora file. Instead, set endpoint configuration parameters through the Oracle Key Vault management console. Depending on your privileges, you can set these for individual endpoints or globally, for all endpoints.

Several okvclient.ora parameters can be modified through the Oracle Key Vault management console. You should modify the parameters only in the Oracle Key Vault management console. Depending on your privileges, you can set these parameters for individual endpoints or globally, for all endpoints.

  • PKCS11_CACHE_TIMEOUT=value specifies the duration in minutes for which the master encryption key is available after it is cached in the in-memory cache. In the Oracle Key Vault management console, this setting is PKCS 11 In-Memory Cache Timeout ( in minutes ) in the Endpoint Settings page.

  • PKCS11_PERSISTENT_CACHE_TIMEOUT=value specifies the duration in minutes for which the master encryption key is available after it is cached in the persistent master encryption key cache. In the Oracle Key Vault management console, this setting is PKCS 11 Persistent Cache Timeout ( in minutes ) in the Endpoint Settings page.

  • PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW=value specifies the duration in minutes to extend the period of time for which the master encryption key is available after it is cached in the persistent master encryption key cache. In the Oracle Key Vault management console, this setting is PKCS 11 Persistent Cache Refresh Window ( in minutes ) in the Endpoint Settings page.

  • PKCS11_CONFIG_PARAM_REFRESH_INTERVAL=value sets the frequency at which a long-running process will re-read the okvclient.ora configuration file. In the Oracle Key Vault management console, this setting is PKCS11 Configuration Parameter Refresh Interval ( in minutes ) in the Endpoint Settings page.

  • SERVER_POLL_TIMEOUT=value specifies 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 the Oracle Key Vault management console, this setting is Server Poll Timeout ( in milliseconds ) in the Endpoint Settings page.

Related Topics

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

13.7 okvclient.ora Parameters That Must Not Be Modified

The okvclient.ora configuration file contains configuration parameters that you must not modify.

These parameters are automatically populated when you add the endpoint to Oracle Key Vault. Do not modify them. They are as follows:

  • 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 and the server DN separated by a slash. 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. Do not modify this parameter. Oracle Key Vault populates this setting when the endpoint node is added.

  • SERVER_DN=CN=server_certification,OU=product,O=company,L=city,ST=state_or_province,C=country
  • GEN_TIMESTAMP=timestamp_information

    This parameter shows the time and date format used in the endpoint.

  • UPDATE_TIMESTAMP=updated_timestamp

    This parameter shows the date, time, and timezone for when the configuration file was last updated.

  • SW_TYPE=software_type

    This parameter shows the endpoint software type, for example, ENROLLED_ENDPOINT_SOFTWARE.

  • JAVA_HOME=path

    This parameter shows the directory that is defined by the JAVA_HOME environment variable.

  • OKV_JVM_LIB_PATH=path

    This parameter shows the directory that is defined by the OKV_JVM_LIB_PATH environment variable.

  • EP_TYPE=type

    This parameter indicates the type of the endpoint, such as Oracle Database.

  • OKV_HOSTNAME=host_name

    This parameter indicates the host server where Oracle Key Vault resides.

  • SSL_WALLET_LOC=directory

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

  • _NOT_STRICT_PKCS11=value

    This parameter indicates the strict PKCS standard setting for use with Oracle ACFS.

  • PKCS11_NO_KMIP_OBJECT_ACCESS_CHECK=value

    This parameter indicates whether the endpoint will perform access checks.

  • _TRACE_DIR=.

    This parameter indicates the location where the PKCS trace files are generated. The . character, the default, means the current directory.

  • _TRACE_LEVEL=0

    This parameter determines the tracing level that is set for the PKCS traces. 0, the default, disables tracing. Enter a value up to 16 to enable full tracing.

  • NUM_AFFINITY_RW_NODES=

    This parameter defines the number of read-write nodes that are in the cluster and have the same subgroup as the endpoint.

  • NUM_AFFINITY_RO_NODES=

    This parameter defines the number of read-only nodes that are in the cluster and have the same subgroup as the endpoint.

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

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

13.8 Upgrading Endpoint Software

You can upgrade the endpoint software from the Oracle Key Vault management console login window.

Parent topic: Enrolling and Upgrading Endpoints for Oracle Key Vault

13.8.1 Step 1: Prepare the Endpoint Environment

Ensure that you have the correct privileges and that the endpoint has the correct configuration, such as Oracle environment variables.

These steps assume that the endpoint has already been enrolled in a previous release of Oracle Key Vault.
  1. Ensure that you have the necessary administrative privileges to install software on the endpoint.
  2. Ensure that you have JDK 1.6 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.6, 7, and 8. The 64-bit version of Java is required.
  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.
  5. Shut down the database if you are installing the endpoint software for an Oracle database configured for online TDE master encryption key management.
  6. As an endpoint administrator, shutdown the Oracle database server.

Parent topic: Upgrading Endpoint Software

13.8.2 Step 2: Download the Oracle Key Vault Software onto the Endpoint

You download the okvclient.jar file to local computer.

You can download the endpoint software without having to reenroll the endpoint.
  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 under Login, click Endpoint Enrollment and Software Download.

    The Enroll Endpoint & Download Software page appears.

  4. At the top of the page, click the Download Endpoint Software Only tab. Description of 21_download_endpoint_software.png follows
    Description of the illustration 21_download_endpoint_software.png
  5. In the Download Endpoint Software Only page, select the endpoint platform from the Platform drop down menu and click Download.
  6. Save the file okvclient.jar to a desired location.

Related Topics

Parent topic: Upgrading Endpoint Software

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

You must be the endpoint administrator to install the Oracle Key Vault software onto the endpoint.

  1. Ensure that you are logged in to the endpoint server as the endpoint administrator.

    Note:

    If you are installing the endpoint software for an Oracle database configured for online TDE master encryption key management, then shut down the database.
  2. Ensure that the Oracle database is shutdown.
  3. Navigate to the directory in which you saved the okvclient.jar file.
  4. Confirm that the target directory exists, and that it is empty.
  5. Run the java command to install the okvclient.jar file.
    java -jar okvclient.jar -d /home/oracle/okv_home -v

    In this specification:

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

    • -v writes the installation logs to the /home/oracle/okv_home/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.

    Note:

    If you are installing the okvclient.jar file on an Oracle Database Windows endpoint system, then make sure that the java command to install okvclient.jar file is run with administrator privileges and $ORACLE_BASE/okv/$ORACLE_SID/ or $ORACLE_HOME/okv/$ORACLE_SID is a valid path on NTFS or ReFS filesystem. Failing to do so may cause installation to fail because on Windows platform administrator privileges are required to create $ORACLE_BASE/okv/$ORACLE_SID/okvclient.ora or $ORACLE_HOME/okv/$ORACLE_SID softlink during installation and softlink creation is only supported on NTFS or ReFS filesystem.
  6. 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.
    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.
    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 file okveps.x64

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

    Note:

    Oracle recommends that you use the password-protected wallet.

Related Topics

Parent topic: Upgrading Endpoint Software

13.8.4 Step 4: Perform Post-Installation Tasks

After you complete the installation, you can update the library used by TDE and then verify that the endpoint software was installed correctly.

  1. Update the PKCS#11 library 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.
    If an endpoint uses online TDE master encryption key management by Oracle Key Vault, then you must install the PKCS#11 library by using root.sh or root.bat script.

    Note:

    • You must run root.sh or root.bat script to install the Oracle Key Vault PKCS#11 library only once on a host machine that has multiple TDE-enabled Oracle databases that use Oracle Key Vault for master encryption key management.
    • Ensure that you execute the root.sh or root.bat script only after the installation of the Oracle Key Vault endpoints for all of the TDE-enabled databases on the same host machine is complete.
    • Ensure that all of the TDE-enabled Oracle databases on this host are shutdown.
    • On Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations: Log in as the root user 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. Start the Oracle databases if the installation of upgrade of the Oracle Key Vault endpoints for all of the TDE-enabled databases on this host machine is complete.
  4. 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.

Parent topic: Upgrading Endpoint Software

13.8.5 Upgrading Endpoint Software on an Enrolled Endpoint

You should upgrade the endpoint software on an enrolled endpoint any time you upgraded to a new release of Oracle Key Vault.

This ensures that you have the latest software on both the Oracle Key Vault server and the endpoint. Oracle highly recommends this for optimum performance. Oracle Key Vault servers can work with endpoint software from the previous major release, but may not work properly with endpoint software that is older. To upgrade the software on an already enrolled endpoint you can download and install the software okvclient.jar on the endpoint. You do not need to reenroll the endpoint.
  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.


    Description of 21_new_login.png follows
    Description of the illustration 21_new_login.png

  3. In the lower-right corner of the login screen, under Login, click Endpoint Enrollment and Software Download.
  4. In the Enroll Endpoint & Download Software page, click Download Endpoint Software Only.
    The Download Endpoint Software Only page appears.
  5. Select the Platform from the drop-down list and then 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.
  6. Save the file to an appropriate directory.
  7. Verify that the file is downloaded.
    After you complete these steps, you can install the Oracle Key Vault software on the endpoint, using the same steps that can be used for an unenrolled endpoint. Oracle recommends that you extract the jar file in the existing endpoint directory because the upgrade endpoint software will not work otherwise. For example: 
    java -jar /path/to/okvclient.jar -d /path/to/existing/ep/files -v
  8. When the endpoint has been successfully upgraded, the following message appears:
    The endpoint software for Oracle Key Vault upgraded successfully

Related Topics

Parent topic: Upgrading Endpoint Software