Documentation Home
Security in MySQL
Related Documentation Download this Excerpt
PDF (US Ltr) - 1.2Mb
PDF (A4) - 1.2Mb
EPUB - 309.4Kb
HTML Download (TGZ) - 269.4Kb
HTML Download (Zip) - 279.0Kb

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

7.4.3 Configuring the keyring_okv Oracle Key Vault Plugin


The keyring_okv plugin is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see

The 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 keyring_okv.

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.

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:

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

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

  3. Install the client software to populate a directory for use by keyring_okv that contains Oracle Key Vault support files.

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

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

  2. Select the Endpoints tab to arrive at the Endpoints page, then click Add on the Endpoints page.

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

  4. Log out from the Oracle Key Vault server.

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

  6. 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 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.)

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


    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.

    If the okvclient.ora is generated with no setting for STANDBY_SERVER, keyring_okv will fail to initialize. The workaround is to check oraclient.ora file and add a dummy setting for STANDBY_SERVER, if one is missing:

  8. 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
  9. 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 MySQL 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, use these lines in the server my.cnf file (adjust the .so suffix and directory location for your platform as necessary):


For additional information about keyring_okv_conf_dir, see Section 7.4.7, “Keyring System Variables”.

The keyring_okv plugin supports the functions that comprise the standard keyring service interface. Keyring operations performed by these functions are accessible at two levels:

Example (using UDFs):

SELECT keyring_key_generate('MyKey', 'AES', 32);
SELECT keyring_key_remove('MyKey');

The key types permitted by keyring_okv are described in Section 7.4.4, “Supported Keyring Types”.

User Comments
Sign Up Login You must be logged in to post a comment.