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.

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

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.

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 run 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 run 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, run 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.
   

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.

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

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.

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.