6.4.4.4 Using the keyring_okv KMIP Plugin

Create the configuration directory for the keyring_okv plugin to use.

Register an endpoint with Oracle Key Vault to obtain an enrollment token.

Use the enrollment token to obtain the okvclient.jar client software download.

Install the client software to populate the keyring_okv configuration directory that contains the Oracle Key Vault support files.

Create the configuration directory that will contain the Oracle Key Vault support files, and make sure that the keyring_okv_conf_dir system variable is set to name that directory (for details, see General keyring_okv Configuration).

Log in to the Oracle Key Vault management console as a user who has the System Administrator role.

Select the Endpoints tab to arrive at the Endpoints page. On the Endpoints page, click Add.

Provide the required endpoint information and click Register. The endpoint type should be Other. Successful registration results in an enrollment token.

Log out from the Oracle Key Vault server.

Connect again to the Oracle Key Vault server, this time without logging in. Use the endpoint enrollment token to enroll and request the okvclient.jar software download. Save this file to your system.

Install the okvclient.jar file using the following command (you must have JDK 1.4 or higher):

java -jar okvclient.jar -d dir_name [-v]

The directory name following the -d option is the location in which to install extracted files. The -v option, if given, causes log information to be produced that may be useful if the command fails.

When the command asks for an Oracle Key Vault endpoint password, do not provide one. Instead, press Enter. (The result is that no password will be required when the endpoint connects to Oracle Key Vault.)

The preceding command produces an okvclient.ora file, which should be in this location under the directory named by the -d option in the preceding java -jar command:

install_dir/conf/okvclient.ora

The file contents include lines that look something like this:

SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num

The keyring_okv plugin attempts to communicate with the server running on the host named by the SERVER variable and falls back to STANDBY_SERVER if that fails:

Go to the Oracle Key Vault installer directory and test the setup by running this command:

okvutil/bin/okvutil list

The output should look something like this:

Unique ID                               Type            Identifier
255AB8DE-C97F-482C-E053-0100007F28B9	Symmetric Key	-
264BF6E0-A20E-7C42-E053-0100007FB29C	Symmetric Key	-

For a fresh Oracle Key Vault server (a server without any key in it), the output looks like this instead, to indicate that there are no keys in the vault:

no objects found

Use this command to extract the ssl directory containing SSL materials from the okvclient.jar file:

jar xf okvclient.jar ssl

Copy the Oracle Key Vault support files (the okvclient.ora file and the ssl directory) into the configuration directory.

(Optional) If you wish to password-protect the key file, use the instructions in Password-Protecting the keyring_okv Key File.

Create the configuration directory that will contain the KeySecure support files, and make sure that the keyring_okv_conf_dir system variable is set to name that directory (for details, see General keyring_okv Configuration).

In the configuration directory, create a subdirectory named ssl to use for storing the required SSL certificate and key files.

In the configuration directory, create a file named okvclient.ora. It should have following format:

SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num

For example, if KeySecure is running on host 198.51.100.20 and listening on port 9002, the okvclient.ora file looks like this:

SERVER=198.51.100.20:9002
STANDBY_SERVER=198.51.100.20:9002

Connect to the KeySecure Management Console as an administrator with credentials for Certificate Authorities access.

Navigate to Security >> Local CAs and create a local certificate authority (CA).

Go to Trusted CA Lists. Select Default and click on Properties. Then select Edit for Trusted Certificate Authority List and add the CA just created.

Download the CA and save it in the ssl directory as a file named CA.pem.

Navigate to Security >> Certificate Requests and create a certificate. Then you will be able to download a compressed tar file containing certificate PEM files.

Extract the PEM files from in the downloaded file. For example, if the file name is csr_w_pk_pkcs8.gz, decompress and unpack it using this command:

tar zxvf csr_w_pk_pkcs8.gz

Two files result from the extraction operation: certificate_request.pem and private_key_pkcs8.pem.

Use this openssl command to decrypt the private key and create a file named key.pem:

openssl pkcs8 -in private_key_pkcs8.pem -out key.pem

Copy the key.pem file into the ssl directory.

Copy the certificate request in certificate_request.pem into the clipboard.

Navigate to Security >> Local CAs. Select the same CA that you created earlier (the one you downloaded to create the CA.pem file), and click Sign Request. Paste the Certificate Request from the clipboard, choose a certificate purpose of Client (the keyring is a client of KeySecure), and click Sign Request. The result is a certificate signed with the selected CA in a new page.

Copy the signed certificate to the clipboard, then save the clipboard contents as a file named cert.pem in the ssl directory.

(Optional) If you wish to password-protect the key file, use the instructions in Password-Protecting the keyring_okv Key File.

Encrypt the key.pem key file. For example, use a command like this, and enter the encryption password at the prompts:

shell> openssl rsa -des3 -in key.pem -out key.pem.new
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

Save the encryption password in a single-line text file named password.txt in the ssl directory.

Verify that the encrypted key file can be decrypted using the following command. The decrypted file should display on the console:

shell> openssl rsa -in key.pem.new -passin file:password.txt

Remove the original key.pem file and rename key.pem.new to key.pem.

Change the ownership and access mode of new key.pem file and password.txt file as necessary to ensure that they have the same restrictions as other files in the ssl directory.