Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 37.5Mb
PDF (A4) - 37.5Mb
PDF (RPM) - 36.9Mb
HTML Download (TGZ) - 10.2Mb
HTML Download (Zip) - 10.2Mb
HTML Download (RPM) - 8.9Mb
Man Pages (TGZ) - 211.3Kb
Man Pages (Zip) - 321.0Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  Using the keyring_okv Oracle Key Vault Plugin Using 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 as a back end for keyring storage. keyring_okv communicates securely with Oracle Key Vault, with keyring material generated exclusively by the Oracle Key Vault server, not by keyring_okv.

keyring_okv uses the KMIP 1.1 protocol to communicate with the back end, so it works with other KMIP-compatible products as well, such as SafeNet KeySecure Appliance.

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, “Supported Keyring Key Types”.

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

General keyring_okv Configuration

Regardless of which KMIP back end the keyring_okv plugin uses for keyring storage, the keyring_okv_conf_dir system variable configures the location of the directory used by keyring_okv for its support files. The default value is empty, so you must set the variable to name a properly configured directory before the plugin can communicate with the KMIP back end. Unless you do so, keyring_okv writes a message to the error log during server startup that it cannot communicate:

[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'

The keyring_okv_conf_dir variable must name a directory that that contains the following items:

  • okvclient.ora: A file that contains details of the KMIP back end with which keyring_okv will communicate.

  • ssl: A directory that contains the certificate and key files required to establish a secure connection with the KMIP back end: CA.pem, cert.pem, and key.pem.

Both the okvclient.ora file and ssl directory with the certificate and key files are required for keyring_okv to work properly. The procedure used to populate the configuration directory with these files depends on the KMIP back end used with keyring_okv, as described elsewhere.

The configuration directory used by keyring_okv as the location for its support files 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:

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

To configure keyring_okv to load during server startup, use the --early-plugin-load option, and set the keyring_okv_conf_dir system variable to tell keyring_okv where to find its configuration directory. 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, “Keyring System Variables”.

Configuring keyring_okv for Oracle Key Vault

The discussion here assumes that you are familiar with Oracle Key Vault. Some pertinent information sources:

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 following procedure briefly summarizes the process of setting up keyring_okv for use with Oracle Key Vault:

  1. Create the configuration directory for the keyring_okv plugin to use.

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

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

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

Use the following procedure to configure keyring_okv and Oracle Key Vault to work together. This procedure only summarizes 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. 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.

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

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

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

  5. Log out from the Oracle Key Vault server.

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

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

  8. 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 file contents include lines that look something like this:


    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.

    The okvclient.ora file must contain a setting for the SERVER variable. A setting for the STANDBY_SERVER variable is optional as of MySQL 5.7.19. Prior to MySQL 5.7.19, a setting for STANDBY_SERVER is mandatory; if okvclient.ora is generated with no setting for STANDBY_SERVER, keyring_okv fails to initialize. The workaround is to check oraclient.ora and add a dummy setting for STANDBY_SERVER, if one is missing:

  9. 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
  10. Use this command to extract the ssl directory containing SSL materials from the okvclient.jar file:

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

After completing the preceding procedure, restart the MySQL server. It loads the keyring_okv plugin and keyring_okv uses the files in its configuration directory to communicate with Oracle Key Vault.

Configuring keyring_okv for the SafeNet KeySecure Appliance

The SafeNet KeySecure Appliance uses the KMIP protocol (version 1.1 or 1.2). As of MySQL 5.7.18, the keyring_okv keyring plugin (which supports KMIP 1.1) can use KeySecure as its KMIP back end for keyring storage.

Use the following procedure to configure keyring_okv and KeySecure to work together. The procedure only summarizes how to interact with KeySecure. For details, consult the section named Add a KMIP Server in the KeySecure User Guide.

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

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

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


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

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

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

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

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

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

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

  10. 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
  11. Copy the key.pem file into the ssl directory.

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

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

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

After completing the preceding procedure, restart the MySQL server. It loads the keyring_okv plugin and keyring_okv uses the files in its configuration directory to communicate with KeySecure.

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