Enrolling and Upgrading Endpoints for Oracle Key Vault

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

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 manager. The endpoint manager 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.

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 manager 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 manager using the Oracle Key Vault management console Enrolled
3. Install okvclient.jar on the endpoint. Endpoint manager 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:

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

Finalizing Enrollment and Provisioning

To enroll and provision a registered endpoint, an endpoint manager 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.

After registering the endpoint, the Oracle Key Vault system administrator sends this endpoint’s enrollment token to the endpoint manager by email or other out-of-band method. Perform the following steps as an endpoint manager.

  1. Log in to the endpoint server.

  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 after the Login button.

    The Enroll Endpoint & Download Software page appears.

    Description of 2110_endpoint_download1.png follows

    Description of the illustration 2110_endpoint_download1.png

  4. If the endpoint was registered by an Oracle Key Vault system administrator, then do the following:

    a. Enter the endpoint’s enrollment token in Enrollment Token, and click Submit Token.

     If the token is valid, then a valid token message appears after 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.

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

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. Perform the following steps as an endpoint manager.

  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. Shut down the Oracle database server.

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

You can install the endpoint using the downloaded okvclient.jar file. For Oracle AI Database 26ai running on the linux-x64 platform, install the software with the "-arch db26ai" option to support Oracle 26ai databases running in FIPS mode using OpenSSL libraries and the new version of the local auto login wallet. This option is currently supported only on linux-x64 platform.

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

    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 shut down.

  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.

    For Oracle Database 21c and earlier: java -jar okvclient.jar -d /home/oracle/okv_home -v.

    For Oracle AI Database 26ai on a linux-x64 platform: java -jar okvclient.jar -d /home/oracle/okv_home -v -arch db26ai.

    Note: The new endpoint software binaries for Oracle AI Database 26ai are available only on a linux-x64 platform.

    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.

    • -arch db26ai is an optional argument to install the endpoint software for Oracle 26ai databases running in FIPS mode using OpenSSL libraries and also support the new version of the local auto login wallet. This option is currently supported only on the Linux-x64 platform.

    For Oracle AI Database 26ai running on a linux-x64 platform, the endpoint software needs to be upgraded with the -arch db26ai option to upgrade the software to support the new Oracle AI Database 26ai architecture.

    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. Use of following special characters is recommended: period (.), comma (,), underscore (_), plus sign (+), colon (:), and exclamation mark (!).

      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. If the endpoint software is installed with the -arch db26ai option, then it also contains binaries such as libnnzora.so, legacy.so and fips.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.

Step 4: Perform Postinstallation Tasks

The postinstallation 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 the root.bat script.

    Note: For Oracle Database release 21c and earlier:

    • You must run root.sh or the 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 the root.bat script only after installation of the Oracle Key Vault endpoints for all of TDE-enabled databases on the same host machine is complete.
    • Ensure that all TDE-enabled Oracle databases on this host are shut down.

    For Oracle Database release 26ai:

    • Oracle recommends to install the PKCS#11 library by passing the --okv_pkcs11_library_location option to the root.sh script. This option enables Oracle Key Vault to install the PKCS#11 library in the fixed custom path which is different from the legacy location. The custom path is of the format /opt/oracle/extapi/64/pkcs11/okv/<okv_version>/lib. For example, for the Oracle Key Vault 21.XX release, it is /opt/oracle/extapi/64/pkcs11/okv/21.XX.0.0.0/lib.

    • Run the root.sh script once for each different endpoint software version on the same host.

    • It is not required to shut down all Oracle databases on this host as the --okv_pkcs11_library_location installs the PKCS#11 library in a new path for each endpoint release.

    Note: Installing the liborapkcs.so file in the legacy path is also supported for the Oracle AI Database 26ai but it is not recommended.

    For Oracle Database 21c and earlier:

    • On Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations: Log in as the root user and then run the following command:

      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.

    • For Oracle Database release 26ai On Oracle Linux x64 installation, log in as the root user and then run either of the following commands:

      sudo bin/root.sh --okv_pkcs11_library_location

      OR

      $ su -
# bin/root.sh --okv_pkcs11_library_location

      This command creates the directory tree //opt/oracle/extapi/64/pkcs11/okv/<okv_version>/lib, changes ownership and permissions, then copies the PKCS#11 library and its dependencies into this 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. For Oracle database release 21c and earlier:

    Start the Oracle databases if the upgrade of the Oracle Key Vault endpoints for all TDE-enabled databases on this host machine is complete.

    For Oracle AI Database release 26ai:

    Perform the following additional steps in the database. These are needed for the database to start using the PKCS#11 library from the custom path and also to transition the database to upgrade the liborapkcs.so file without encountering downtime in future.

    1. Log in to the CDB root as a user who has been granted the ALTER SYSTEM privilege.

    2. As a user with the ALTER SYSTEM privilege, set the static initialization parameter PKCS11_LIBRARY_LOCATION to point to the upgraded liborapkcs.so file. For example:

      ALTER SYSTEM SET PKCS11_LIBRARY_LOCATION = '/opt/oracle/extapi/64/

pkcs11/okv/21.16.0.0.0/lib/liborapkcs.so' SCOPE = SPFILE SID = '*';

      After a database restart, your database is now ready to switch to new PKCS#11 libraries without database downtime.

    After you upgrade Oracle Key Vault to a new release (for example 21.XX.0.0.0), the root.sh script in the upgraded endpoint can be used to copy liborapkcs.so to the new path /opt/oracle/extapi/64/pkcs11/okv/21.XX.0.0.0/lib. The database can switch to the new library using the SWITCHOVER command without any downtime.

    For example, ADMINISTER KEY MANAGEMENT SWITCHOVER TO LIBRARY '/opt/oracle/extapi/64/pkcs11/okv/21.16.0.0.0/lib/liborapkcs.so' FOR ALL CONTAINERS.

  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 Oracle Key Vault, then the No objects found message appears. If a Server connect failed message appears, then 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:

    Oracle Key Vault Release 21.16.0.0.0 (2025-06-13 13:15:38 UTC)
Production on Fri Jun 13 13:46:15 UTC 2025
Copyright (c) 2014, 2024 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.

  -arch db26ai : Install the software for the Oracle db26ai database.

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.

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:

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:

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.

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:

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.

Environment Variables in sqlnet.ora File

You must consider several points while using the srvctl utility on Oracle Database endpoints.

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

Downloading the Certificate Chain Of Trust for Oracle Key Vault Intermediate CA Certificate

To download the Certificate Chain of Trust for the Oracle Key Vault intermediate CA certificate:

  1. Log in to the Oracle Key Vault system as a system administrator or the endpoint manager.

  2. On the Endpoint Details page, download the CA certificate trust chain. If you are logged in as the system administrator, then you can also download the trust chain if you click System and select Service Certificates.

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. The following example shows sample commands for 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

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:

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.

Related Topics

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:

Upgrading Endpoint Software

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

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. Perform the following steps as an endpoint manager.

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. Shut down the Oracle database server.

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 re-enroll the endpoint.

  1. Log in to the endpoint server as the endpoint manager.

  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 2110_download_endpoint_software.png follows

  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

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

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

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

    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 shut down.

  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.

    For Oracle Database 21c and earlier: java -jar okvclient.jar -d /home/oracle/okv_home -v.

    For Oracle AI Database 26ai on a linux-x64 platform: java -jar okvclient.jar -d /home/oracle/okv_home -v -arch db26ai.

    Note: The new endpoint software binaries for Oracle AI Database 26ai are available only on a linux-x64 platform.

    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.

    • -arch db26ai is an optional argument to install the endpoint software for Oracle 26ai databases running in FIPS mode using OpenSSL libraries and also support the new version of the local auto login wallet. This option is currently supported only on the Linux-x64 platform.

    For Oracle AI Database 26ai running on a linux-x64 platform, the endpoint software needs to be upgraded with the -arch db26ai option to upgrade the software to support the new Oracle AI Database 26ai architecture.

    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. Use of following special characters is recommended: period (.), comma (,), underscore (_), plus sign (+), colon (:), and exclamation mark (!).

      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. If the endpoint software is installed with the -arch db26ai option, then it also contains binaries such as libnnzora.so, legacy.so and fips.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

Step 4: Perform Postinstallation 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 the root.bat script.

    Note: For Oracle Database release 21c and earlier:

    • You must run root.sh or the 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 the root.bat script only after installation of the Oracle Key Vault endpoints for all of TDE-enabled databases on the same host machine is complete.
    • Ensure that all TDE-enabled Oracle databases on this host are shut down.

    For Oracle Database release 26ai:

    • Oracle recommends to install the PKCS#11 library by passing the --okv_pkcs11_library_location option to the root.sh script. This option enables Oracle Key Vault to install the PKCS#11 library in the fixed custom path which is different from the legacy location. The custom path is of the format /opt/oracle/extapi/64/pkcs11/okv/<okv_version>/lib. For example, for the Oracle Key Vault 21.XX release, it is /opt/oracle/extapi/64/pkcs11/okv/21.XX.0.0.0/lib.

    • Run the root.sh script once for each different endpoint software version on the same host.

    • It is not required to shut down all Oracle databases on this host as the --okv_pkcs11_library_location installs the PKCS#11 library in a new path for each endpoint release.

    Note: Installing the liborapkcs.so file in the legacy path is also supported for the Oracle AI Database 26ai but it is not recommended.

    For Oracle Database 21c and earlier:

    • On Oracle Linux x86-64, Solaris, AIX, and HP-UX (IA) installations: Log in as the root user and then run the following command:

      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.

    • For Oracle Database release 26ai On Oracle Linux x64 installation, log in as the root user and then run either of the following commands:

      sudo bin/root.sh --okv_pkcs11_library_location

      OR

      $ su -
# bin/root.sh --okv_pkcs11_library_location

      This command creates the directory tree //opt/oracle/extapi/64/pkcs11/okv/<okv_version>/lib, changes ownership and permissions, then copies the PKCS#11 library and its dependencies into this 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. For Oracle database release 21c and earlier:

    Start the Oracle databases if the upgrade of the Oracle Key Vault endpoints for all TDE-enabled databases on this host machine is complete.

    For Oracle AI Database release 26ai:

    Perform the following additional steps in the database. These are needed for the database to start using the PKCS#11 library from the custom path and also to transition the database to upgrade the liborapkcs.so file without encountering downtime in future.

    1. Log in to the CDB root as a user who has been granted the ALTER SYSTEM privilege.

    2. As a user with the ALTER SYSTEM privilege, set the static initialization parameter PKCS11_LIBRARY_LOCATION to point to the upgraded liborapkcs.so file. For example:

      ALTER SYSTEM SET PKCS11_LIBRARY_LOCATION = '/opt/oracle/extapi/64/

pkcs11/okv/21.16.0.0.0/lib/liborapkcs.so' SCOPE = SPFILE SID = '*';

      After a database restart, your database is now ready to switch to new PKCS#11 libraries without database downtime.

    After you upgrade Oracle Key Vault to a new release (for example 21.XX.0.0.0), the root.sh script in the upgraded endpoint can be used to copy liborapkcs.so to the new path /opt/oracle/extapi/64/pkcs11/okv/21.XX.0.0.0/lib. The database can switch to the new library using the SWITCHOVER command without any downtime.

    For example, ADMINISTER KEY MANAGEMENT SWITCHOVER TO LIBRARY '/opt/oracle/extapi/64/pkcs11/okv/21.16.0.0.0/lib/liborapkcs.so' FOR ALL CONTAINERS.

  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 Oracle Key Vault, then the No objects found message appears. If a Server connect failed message appears, then 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:

    Oracle Key Vault Release 21.16.0.0.0 (2025-06-13 13:15:38 UTC)
Production on Fri Jun 13 13:46:15 UTC 2025
Copyright (c) 2014, 2024 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.

  -arch db26ai : Install the software for the Oracle db26ai database.

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 re-enroll the endpoint.

  1. Log in to the endpoint server as the endpoint manager.

  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 by using the steps for an unenrolled endpoint. To enable the upgrade endpoint software to work, Oracle recommends that you extract the jar file to the existing endpoint directory. For example:

    java -jar /path/to/okvclient.jar -d /path/to/existing/ep/files -v

    If you are upgrading an endpoint that is used for Oracle AI Database 26ai on a linux-x64 platform, you must specify the -arch db26ai option to upgrade the endpoint. For example:

    java -jar /path/to/okvclient.jar -d /path/to/existing/ep/files -v -arch db26ai

    Note: The new endpoint software binaries for Oracle AI Database 26ai are available only on the linux-x64 platform.

  8. When the endpoint has been successfully upgraded, the following message appears:

    The endpoint software for Oracle Key Vault upgraded successfully

Related Topics