10 Enrolling Endpoints for Oracle Key Vault
After an endpoint is registered in Oracle Key Vault, an endpoint administrator enrolls and provisions the endpoint to manage security objects in Key Vault.
- About Endpoint Enrollment and Provisioning
Endpoints are Oracle Key Vault clients that use the server to store and manage security objects, share them with trusted peers, and retrieve them. - Finalizing Enrollment and Provisioning
To enroll and provision a registered endpoint an endpoint administrator must download and then install theokvclient.jar
file. - Environment Variables and Endpoint Provisioning Guidance
Environment variables such asJAVA_HOME
andOKV_HOME
must be correctly set so that Oracle Key Vault can access its utilities. - Endpoints That Do Not Use the Oracle Key Vault Client Software
Third-party KMIP endpoints do not use the Oracle Key Vault softwareokvutil
andliborapkcs.so
. - Transparent Data Encryption Endpoint Management
Oracle Key Vault can manage TDE keys by using the same PKCS#11 interface that TDE uses to communicate with an external keystore. - Endpoint okvclient.ora Configuration File
Oracle Key Vault endpoint libraries and utilities use theokvclient.ora
configuration file, which stores the configuration parameters associated with the endpoint.
10.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.
An Oracle Key Vault system administrator first adds (or registers) the endpoint to Key Vault, and then sends the endpoint's enrollment token (generated during registration) to the endpoint administrator. The endpoint administrator verifies the enrollment token before enrolling and provisioning the endpoint. An enrolled endpoint can upload, download, and manage security objects using Key Vault.
Endpoint enrollment is a three-step process performed by two kinds of administrative users summarized in the following table.
Table 10-1 Summary of Endpoint Enrollment
Step# | Task | Performed by | Endpoint Status (as seen on Oracle Key Vault Management Console) |
---|---|---|---|
1. |
|
Users with the System Administrator role and Key Administrator role on Oracle Key Vault, or user with the Manage Endpoint privilege |
Registered |
2. |
|
Endpoint administrator using the Oracle Key Vault management console |
Enrolled |
3. |
Install |
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 theokvclient.ora
configuration file
In an Oracle Real Application Clusters (RAC) environment, you must enroll and provision each Oracle RAC node as an endpoint. Each Oracle RAC-enabled database corresponds to one virtual wallet in Oracle Key Vault. Each Oracle RAC instance of that database corresponds to an endpoint in Oracle Key Vault. All endpoints for each database share the same wallet as their default wallet. You must download one distinct okvclient.jar
for each instance.
10.2 Finalizing Enrollment and Provisioning
To enroll and provision a registered endpoint an endpoint administrator must download and then install the okvclient.jar
file.
- Step 1: Enroll the Endpoint and Download the Software
You must have the endpoint's enrollment token before you can download the endpoint softwareokvclient.jar
. - Step 2: Prepare the Endpoint Environment
You must ensure that you have the right version of the Java Development Toolkit (JDK) and that the Oracle environment variables are set. - Step 3: Install the Oracle Key Vault Software onto the Endpoint
To upgrade to the latest endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint. - Step 4: Perform Post-Installation Tasks
The post-installation procedures include optionally configuring a TDE connection for the endpoint, checking the installation contents, and deleting theokvclient.jar file
.
Parent topic: Enrolling Endpoints for Oracle Key Vault
10.2.1 Step 1: Enroll the Endpoint and Download the Software
You must have the endpoint's enrollment token before you can download the endpoint software okvclient.jar
.
okvclient.jar
software file on the endpoint, starting with preparing the endpoint environment.
Related Topics
Parent topic: Finalizing Enrollment and Provisioning
10.2.2 Step 2: Prepare the Endpoint Environment
You must ensure that you have the right version of the Java Development Toolkit (JDK) and that the Oracle environment variables are set.
Parent topic: Finalizing Enrollment and Provisioning
10.2.3 Step 3: Install the Oracle Key Vault Software onto the Endpoint
To upgrade to the latest endpoint software for an enrolled endpoint, you can download the endpoint software without having to reenroll the endpoint.
Parent topic: Finalizing Enrollment and Provisioning
10.2.4 Step 4: Perform Post-Installation Tasks
The post-installation procedures include optionally configuring a TDE connection for the endpoint, checking the installation contents, and deleting the okvclient.jar file
.
Parent topic: Finalizing Enrollment and Provisioning
10.3 Environment Variables and Endpoint Provisioning Guidance
Environment variables such as JAVA_HOME
and OKV_HOME
must be correctly set so that Oracle Key Vault can access its utilities.
- How the Location of JAVA_HOME Location Is Determined
The default location for theokvclient.ora
file is the$OKV_HOME/conf
directory. - Location of the okvclient.ora File and Environment Variables
$OKV_HOME
is the destination directory for the endpoint software specified with the-d
option during installation. - Setting OKV_HOME for Non-Database Utilities to Communicate with Oracle Key Vault
For non-database utilities, you must set the environment variableOKV_HOME
to point to the destination directory for the endpoint software. - Environment Variables in sqlnet.ora File
You must consider several points while using thesrvctl
utility on Oracle Database endpoints.
Parent topic: Enrolling Endpoints for Oracle Key Vault
10.3.1 How the Location of JAVA_HOME Location Is Determined
The default location for the okvclient.ora
file is the $OKV_HOME/conf
directory.
When you provision endpoints you must know how the installation process determines the location of Java home and the okvclient.ora
file.
The endpoint software installation process uses the following rules to determine the Java home location:
-
If a user-defined
JAVA_HOME
environment variable exists, the installation process uses this value. -
If
JAVA_HOME
is not set, then the installation process looks for it in thejava.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 runokvutil
:setenv JAVA_HOME path_to_Java_home
Or:
export JAVA_HOME = path_to_Java_home
-
Set the
JAVA_HOME
property directly in theokvclient.ora
configuration file.JAVA_HOME=path_to_Java_home
Parent topic: Environment Variables and Endpoint Provisioning Guidance
10.3.2 Location of the okvclient.ora File and Environment Variables
$OKV_HOME
is the destination directory for the endpoint software specified with the -d
option during installation.
The okvclient.ora
file is a configuration file in the $OKV_HOME/conf
directory .
In addition to the $OKV_HOME/conf
file, the installation process creates a soft link to okvclient.ora
for an existing database. The location of the soft link depends on the following:
-
If the
$ORACLE_BASE
environment variable is set, then the installation process creates a symbolic link to theokvclient.ora
configuration file (in$OKV_HOME/conf
) in the$ORACLE_BASE/okv/$ORACLE_SID
location.If the
okvclient.ora
file already exists in the$ORACLE_BASE/okv/$ORACLE_SID
location, then the installation process accepts the existing soft link tookvclient.ora
as a a valid soft link. -
If the
$ORACLE_BASE/okv/$ORACLE_SID
directory is not set, then the installation process tries to create it. -
If the
$ORACLE_HOME
environment variable is set but the$ORACLE_BASE
variable is not set, then the installation process creates a symbolic link for the$ORACLE_HOME/okv/$ORACLE_SID
location to point to the configuration file in the$OKV_HOME/conf
directory.
Parent topic: Environment Variables and Endpoint Provisioning Guidance
10.3.3 Setting OKV_HOME for Non-Database Utilities to Communicate with Oracle Key Vault
For non-database utilities, you must set the environment variable OKV_HOME
to point to the destination directory for the endpoint software.
You must manually set OKV_HOME
because the installation process does not set this variable automatically. Setting OKV_HOME
enables utilities to communicate with Oracle Key Vault. These include utilities such as Oracle Recovery Manager (RMAN) that access Oracle Key Vault for keys.
You must set OKV_HOME
in all environments where you will run utilities such as RMAN. For example, if you spawn a new xterm
window, then you will need to set OKV_HOME
in this environment before running RMAN.
Parent topic: Environment Variables and Endpoint Provisioning Guidance
10.3.4 Environment Variables in sqlnet.ora File
You must consider several points while using the srvctl
utility on Oracle Database endpoints.
-
If you are using the
srvctl
utility, and if you want to include environment variables in thesqlnet.ora
configuration file, then you must set these environment variables in both the operating system and thesrvctl
environment. -
For Oracle Database endpoints, if you are using the
srvctl
utility and setting environment variables insqlnet.ora
, then you must set them in both the operating system and thesrvctl
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
10.4 Endpoints That Do Not Use the Oracle Key Vault Client Software
Third-party KMIP endpoints do not use the Oracle Key Vault software okvutil
and liborapkcs.so
.
In this case you must manually set the Transport Layer Security (TLS) authentication as follows:
-
Extract the
ssl
directory from theokvclient.jar
file.jar xvf okvclient.jar ssl
-
Use the following files to set up the TLS authentication:
-
ssl/key.pem
: Endpoint private key -
ssl/cert.pem
: Endpoint certificate -
ssl/cert_req.pem
: Certificate request corresponding tocert.pem
-
ssl/CA.pem
: Trust anchor for verifying the Oracle Key Vault server certificate
-
Parent topic: Enrolling Endpoints for Oracle Key Vault
10.5 Transparent Data Encryption Endpoint Management
Oracle Key Vault can manage TDE keys by using the same PKCS#11 interface that TDE uses to communicate with an external keystore.
Therefore, you do not need to patch the database to use Oracle Key Vault for storing and retrieving TDE master encryption keys. Oracle Key Vault supplies the PKCS#11 library to communicate with Oracle Key Vault.
Oracle Key Vault improves upon TDE key management. For example, you can directly upload the keys in the wallet to Oracle Key Vault for long-term retention, to be shared with other database endpoints within the same endpoint group. Therefore, you do not need to store the wallet indefinitely after migration. Migration in this context means that the database is configured to use Oracle Key Vault for wallet backup, and that the administrator intends to migrate to an online master key (formerly knows as TDE direct connect).
You can continue to use the wallet, and upload wallet copies to Key Vault as part of every TDE key administration SQL operation, involving a WITH BACKUP
SQL clause. However, be aware that TDE ignores the WITH BACKUP
clause in an Oracle Key Vault online key deployment, even if it is required for the ADMINISTER KEY MANAGEMENT
statement.
Oracle Database TDE are endpoints for Oracle Key Vault. Endpoint enrollment and installation ensure that the PKCS#11 library is installed in the correct location for TDE to pick up and use. When the PKCS#11 library is installed, all other configurations and operations are in effect.
Example 10-1 shows examples of setting an encryption key.
Example 10-1 Setting an Encryption Key
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY secret_passphrase -- For Oracle Database 11g Release 2 ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY secret_passphrase WITH BACKUP; -- For Oracle Database 12c and later
Parent topic: Enrolling Endpoints for Oracle Key Vault
10.6 Endpoint okvclient.ora Configuration File
Oracle Key Vault endpoint libraries and utilities use the okvclient.ora
configuration file, which stores the configuration parameters associated with the endpoint.
The okvclient.ora
file consists of key-value pairs separated by an equal sign (=
). You can set the following parameters in the endpoint configuration file:
-
SERVER=node1_IP:node1_port/node1_DN,node2_IP:node2_port/node2_DN,...
This parameter specifies the IP address and port number of the Oracle Key Vault server, separated by a colon. If the port number is not specified, then it defaults to the standard KMIP port
5696
. -
STANDBY_SERVER=standby_server_IP:standby_server port
This is the standby server. If primary-standby is configured, then this parameter shows the standby IP address.
READ_SERVER=node1_IP:node1_port/node1_DN,node2_IP:node2_port/node2_DN,...
This parameter specifies the list of read-only servers.
-
SSL_WALLET_LOC=directory
This parameter specifies the location of the wallet containing TLS credentials for the endpoint.
-
SERVER_POLL_TIMEOUT=timeout_value
You can use the
SERVER_POLL_TIMEOUT
parameter to specify a timeout for a client's attempt to connect to an Oracle Key Vault server before trying the next server in the list. The default value is 300 (milliseconds).In Oracle Key Vault clients first establish a non-blocking TCP connection to Oracle Key Vault to quickly detect unreachable servers.
After the first attempt, the client makes a second and final attempt to connect to the server but this time waits for twice as long as the duration specified by the
SERVER_POLL_TIMEOUT
parameter. This is done to overcome possible network congestion or delays.
The CONF_ID
value in an okvclient.ora
file is a unique internal value that helps an Oracle database to find its virtual wallet in Oracle Key Vault. Do not modify this value.
Parent topic: Enrolling Endpoints for Oracle Key Vault