#### 6.4.4.8 Using the keyring\_okv KMIP Plugin

[]()[]()

Note

 The `keyring_okv` plugin is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see [https://www.mysql.com/products/](https://www.mysql.com/products/).

 The Key Management Interoperability Protocol (KMIP) enables communication of cryptographic keys between a key management server and its clients. The `keyring_okv` keyring plugin uses the KMIP 1.1 protocol to communicate securely as a client of a KMIP back end. Keyring material is generated exclusively by the back end, not by `keyring_okv`. The plugin works with these KMIP-compatible products:

* Oracle Key Vault

* Gemalto SafeNet KeySecure Appliance

* Townsend Alliance Key Manager

* Entrust KeyControl

 Each MySQL Server instance must be registered separately as a client for KMIP. If two or more MySQL Server instances use the same set of credentials, they can interfere with each other’s functioning.

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

* SQL interface: In SQL statements, call the functions described in [Section 6.4.4.14, “General-Purpose Keyring Key-Management Functions”](keyring-functions-general-purpose.html).

* C interface: In C-language code, call the keyring service functions described in [Section 5.6.9.2, “The Keyring Service”](keyring-service.html).

 Example (using the SQL interface):

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

 For information about the characteristics of key values permitted by `keyring_okv`, [Section 6.4.4.12, “Supported Keyring Key Types and Lengths”](keyring-key-types.html).

 To install `keyring_okv`, use the general instructions found in [Section 6.4.4.3, “Keyring Plugin Installation”](keyring-plugin-installation.html), together with the configuration information specific to `keyring_okv` found here.

* [General keyring\_okv Configuration](keyring-okv-plugin.html#keyring-okv-configuration)

* [Configuring keyring\_okv for Oracle Key Vault](keyring-okv-plugin.html#keyring-okv-oracle-key-vault)

* [Configuring keyring\_okv for Gemalto SafeNet KeySecure Appliance](keyring-okv-plugin.html#keyring-okv-keysecure)

* [Configuring keyring\_okv for Townsend Alliance Key Manager](keyring-okv-plugin.html#keyring-okv-alliance)

* [Configuring keyring\_okv for Entrust KeyControl](keyring-okv-plugin.html#keyring-okv-entrust-keycontrol)

* [Password-Protecting the keyring\_okv Key File](keyring-okv-plugin.html#keyring-okv-encrypt-key-file)

##### General keyring\_okv Configuration

[]()

 Regardless of which KMIP back end the `keyring_okv` plugin uses for keyring storage, the [`keyring_okv_conf_dir`](keyring-system-variables.html#sysvar_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`](keyring-system-variables.html#sysvar_keyring_okv_conf_dir) variable must name a directory that contains the following items:

* `okvclient.ora`: A file that contains details of the KMIP back end with which `keyring_okv` communicates.

* `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`. If the key file is password-protected, the `ssl` directory can contain a single-line text file named `password.txt` containing the password needed to decrypt the key file.

 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 the `/usr/local/mysql/mysql-keyring-okv` directory, 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 be usable during the server startup process, `keyring_okv` must be loaded using the [`--early-plugin-load`](server-options.html#option_mysqld_early-plugin-load) option. Also, set the [`keyring_okv_conf_dir`](keyring-system-variables.html#sysvar_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, adjusting 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
```

 For additional information about [`keyring_okv_conf_dir`](keyring-system-variables.html#sysvar_keyring_okv_conf_dir), see [Section 6.4.4.18, “Keyring System Variables”](keyring-system-variables.html).

##### Configuring keyring\_okv for Oracle Key Vault

[]()[]()

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

* [Oracle Key Vault site](http://www.oracle.com/technetwork/database/options/key-management/overview/index.html)

* [Oracle Key Vault documentation](http://www.oracle.com/technetwork/database/options/key-management/documentation/index.html)

 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. Note that you must register a separate endpoint for each MySQL Server instance. If two or more MySQL Server instances use the same endpoint, they can interfere with each other’s functioning.

 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 description only summarizes how to interact with Oracle Key Vault. For details, visit the [Oracle Key Vault](http://www.oracle.com/technetwork/database/options/key-management/overview/index.html) site and consult the Oracle Key Vault Administrator's Guide.

1. Create the configuration directory that contains the Oracle Key Vault support files, and make sure that the [`keyring_okv_conf_dir`](keyring-system-variables.html#sysvar_keyring_okv_conf_dir) system variable is set to name that directory (for details, see [General keyring\_okv Configuration](keyring-okv-plugin.html#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. On the Endpoints page, click Add.

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` 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 is 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:

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

   * For the `SERVER` variable, a setting in the `okvclient.ora` file is mandatory.

   * For the `STANDBY_SERVER` variable, a setting in the `okvclient.ora` file is optional.

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.

12. (Optional) If you wish to password-protect the key file, use the instructions in [Password-Protecting the keyring\_okv Key File](keyring-okv-plugin.html#keyring-okv-encrypt-key-file).

 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 Gemalto SafeNet KeySecure Appliance

[]()[]()[]()

 Gemalto SafeNet KeySecure Appliance uses the KMIP protocol (version 1.1 or 1.2). 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 description only summarizes how to interact with KeySecure. For details, consult the section named Add a KMIP Server in the [KeySecure User Guide](https://www2.gemalto.com/aws-marketplace/usage/vks/uploadedFiles/Support_and_Downloads/AWS/007-012362-001-keysecure-appliance-user-guide-v7.1.0.pdf).

1. Create the configuration directory that contains the KeySecure support files, and make sure that the [`keyring_okv_conf_dir`](keyring-system-variables.html#sysvar_keyring_okv_conf_dir) system variable is set to name that directory (for details, see [General keyring\_okv Configuration](keyring-okv-plugin.html#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:

   ```
   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
   ```

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 can 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 as a file named `cert.pem` in the `ssl` directory.

15. (Optional) If you wish to password-protect the key file, use the instructions in [Password-Protecting the keyring\_okv Key File](keyring-okv-plugin.html#keyring-okv-encrypt-key-file).

 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.

##### Configuring keyring\_okv for Townsend Alliance Key Manager

[]()[]()[]()

 Townsend Alliance Key Manager uses the KMIP protocol. The `keyring_okv` keyring plugin can use Alliance Key Manager as its KMIP back end for keyring storage. For additional information, see [Alliance Key Manager for MySQL](https://www.townsendsecurity.com/product/encryption-key-management-mysql).

##### Configuring keyring\_okv for Entrust KeyControl

[]()[]()[]()

 Entrust KeyControl uses the KMIP protocol. The `keyring_okv` keyring plugin can use Entrust KeyControl as its KMIP back end for keyring storage. For additional information, see the [Oracle MySQL and Entrust KeyControl with nShield HSM Integration Guide](https://www.entrust.com/-/media/documentation/integration-guides/oracle-mysql-enterprise-keycontrol-nshield-ig.pdf).

##### Password-Protecting the keyring\_okv Key File

 You can optionally protect the key file with a password and supply a file containing the password to enable the key file to be decrypted. To so do, change location to the `ssl` directory and perform these steps:

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

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

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

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

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

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

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

