MySQL :: Security in MySQL :: 7.3.3 Configuring the keyring

Security in MySQL / ... / Configuring the keyring_okv Oracle Key Vault Plugin

7.3.3 Configuring the keyring_okv Oracle Key Vault Plugin

Note

The keyring_okv plugin is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see http://www.mysql.com/products/.

The keyring_okv plugin is a keyring plugin that uses Oracle Key Vault for keyring backend storage. This plugin is available in MySQL Enterprise Edition. keyring_okv communicates securely with Oracle Key Vault. All keyring material is generated exclusively by the Oracle Key Vault server, not by keyring_okv.

To use the keyring_okv plugin, use the general installation instructions found in Section 7.3.1, “Keyring Plugin Installation”, together with the plugin-specific configuration information found here.

In Oracle Key Vault terminology, clients that use Oracle Key Vault to store and retrieve security objects are called endpoints. To communicate with Oracle Key Vault, it is necessary to register as an endpoint and enroll by downloading and installing endpoint support files.

The keyring_okv_conf_dir system variable configures the location of the directory used by keyring_okv for Oracle Key Vault support files. The default value is empty, so you must set it before the plugin can communicate with Oracle Key Vault. The following procedure briefly summarizes the process of configuring this directory:

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 a directory for use by keyring_okv that contains Oracle Key Vault support files.
Set the keyring_okv_conf_dir system variable to the directory containing the support files.

Unless you set keyring_okv_conf_dir to a properly configured directory, keyring_okv writes a message to the error log that it cannot communicate with Oracle Key Vault:

[Warning] Plugin keyring_okv reported: 'For keyring_okv to be
initialized, please point the keyring_okv_conf_dir variable to a directory
containing Oracle Key Vault configuration file and ssl materials'

Use the following procedure to register with Oracle Key Vault as an endpoint and install the required software. This procedure summarizes only briefly how to interact with Oracle Key Vault. For details, visit the Oracle Key Vault site and consult the Oracle Key Vault Administrator's Guide.

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, then click Add on the Endpoints page.
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 using 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, 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 okvclient.ora file should contain settings for SERVER and STANDBY_SERVER variables. The keyring_okv plugin will attempt to communicate with SERVER and fall 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	-

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

Create a directory to be used by keyring_okv as the location for its support files. Into that directory, copy the okvclient.ora file and the ssl directory extracted using the preceding procedure. The directory for keyring_okv should have a restrictive mode and be accessible only to the account used to run the server. For example, on Unix and Unix-like systems, to use /usr/local/mysql/mysql-keyring-okv, the following commands (executed as root) create the directory and set its mode and ownership:

shell> cd /usr/local/mysql
shell> mkdir mysql-keyring-okv
shell> chmod 750 mysql-keyring-okv
shell> chown mysql mysql-keyring-okv
shell> chgrp mysql mysql-keyring-okv

After installing the Oracle Key Vault support files, tell keyring_okv where to find them by setting the keyring_okv_conf_dir system variable. For example:

[mysqld]
early-plugin-load=keyring_okv.so
keyring_okv_conf_dir=/usr/local/mysql/mysql-keyring-okv

For additional information about keyring_okv_conf_dir, see Server System Variables.

PREV HOME UP NEXT

User Comments