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/.
keyring_okv plugin is a keyring plugin
that uses Oracle Key Vault for keyring backend storage.
keyring_okv communicates securely with Oracle
Key Vault. All keyring material is generated exclusively by the
Oracle Key Vault server, not by
The discussion here assumes that you are familiar with Oracle Key Vault. Some pertinent information sources:
To install the
keyring_okv plugin, use the
general installation instructions found in
Section 7.4.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.
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
Register an endpoint with Oracle Key Vault to obtain an enrollment token.
Use the enrollment token to obtain the
okvclient.jarclient software download.
Install the client software to populate a directory for use by
keyring_okvthat contains Oracle Key Vault support files.
keyring_okv_conf_dirsystem variable to the directory containing the support files.
Unless you set
keyring_okv_conf_dir to a
properly configured directory,
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.jarsoftware download. Save this file to your system.
okvclient.jarusing following command (you must have JDK 1.4 or higher):
java -jar okvclient.jar -d
The directory name following the
-doption is the location in which to install extracted files. The
-voption, 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.orafile, which should be in this location under the directory named by the
-doption in the preceding java -jar command:
okvclient.orafile should contain settings for
keyring_okvplugin will attempt to communicate with
SERVERand fall back to
STANDBY_SERVERif that fails.
okvclient.orais generated with no setting for
keyring_okvwill fail to initialize. The workaround is to check
oraclient.orafile and add a “dummy” setting for
STANDBY_SERVER, if one is missing:
Go to the Oracle Key Vault installer directory and test the setup by running this command:
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
ssldirectory containing SSL materials from the
jar xf okvclient.jar ssl
Create a directory to be used by
as the location for its support files. Into that directory, copy
okvclient.ora file and the
ssl directory extracted using the preceding
procedure. The directory for
should have a restrictive mode and be accessible only to the
account used to run the MySQL server. For example, on Unix and
Unix-like systems, to use
following commands (executed as
the directory and set its mode and ownership:
chmod 750 mysql-keyring-okvshell>
chown mysql mysql-keyring-okvshell>
chgrp mysql mysql-keyring-okv
After installing the Oracle Key Vault support files, tell
keyring_okv where to find them by setting the
variable. For example, use these lines in the server
my.cnf file (adjust the
.so suffix and directory location for your
platform as necessary):
[mysqld] early-plugin-load=keyring_okv.so keyring_okv_conf_dir=/usr/local/mysql/mysql-keyring-okv
keyring_okv plugin supports the functions
that comprise the standard keyring service interface. Keyring
operations performed by these functions are accessible at two
C interface: In C-language code, call the keyring service functions described in The Keyring Service.
SQL interface: In SQL statements, call the user-defined functions (UDFs) described in Section 7.4.5, “General-Purpose Keyring Key-Management Functions”.
Example (using UDFs):
SELECT keyring_key_generate('MyKey', 'AES', 32); SELECT keyring_key_remove('MyKey');
The key types permitted by
described in Section 7.4.4, “Supported Keyring Types”.