6.4.4.4 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/.

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

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

SQL interface: In SQL statements, call the user-defined functions (UDFs) described in Section 6.4.4.8, “General-Purpose Keyring Key-Management Functions”.
C interface: In C-language code, call the keyring service functions described in Section 29.3.2, “The Keyring Service”.

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

To install the keyring_okv plugin, use the general keyring installation instructions found in Section 6.4.4.1, “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 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. 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 option. Also, 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):

[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 Section 6.4.4.11, “Keyring System Variables”.

Contents Haut

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:

Create the configuration directory for the keyring_okv plugin to use.
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 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 site and consult the Oracle Key Vault Administrator's Guide.

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).
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. On the Endpoints page, click Add.
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 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 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 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.
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
```
Use this command to extract the ssl directory containing SSL materials from the okvclient.jar file:
```
jar xf okvclient.jar ssl
```
Copy the Oracle Key Vault support files (the okvclient.ora file and the ssl directory) into the configuration directory.
(Optional) If you wish to password-protect the key file, use the instructions in Password-Protecting the keyring_okv 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.

Contents Haut

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.

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).
In the configuration directory, create a subdirectory named ssl to use for storing the required SSL certificate and key files.
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
```
Connect to the KeySecure Management Console as an administrator with credentials for Certificate Authorities access.
Navigate to Security >> Local CAs and create a local certificate authority (CA).
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.
Download the CA and save it in the ssl directory as a file named CA.pem.
Navigate to Security >> Certificate Requests and create a certificate. Then you will be able to download a compressed tar file containing certificate PEM files.
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.
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
```
Copy the key.pem file into the ssl directory.
Copy the certificate request in certificate_request.pem into the clipboard.
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.
Copy the signed certificate to the clipboard, then save the clipboard contents as a file named cert.pem in the ssl directory.
(Optional) If you wish to password-protect the key file, use the instructions in Password-Protecting the keyring_okv 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.

Contents Haut

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:

Encrypt the key.pem key file. For example, use a command like this, and enter the encryption password at the prompts:
```
shell> openssl rsa -des3 -in key.pem -out key.pem.new
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
```
Save the encryption password in a single-line text file named password.txt in the ssl directory.
Verify that the encrypted key file can be decrypted using the following command. The decrypted file should display on the console:
```
shell> openssl rsa -in key.pem.new -passin file:password.txt
```
Remove the original key.pem file and rename key.pem.new to key.pem.
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.

Find a PHP function

Document created the 26/06/2006, last modified the 26/10/2018
Source of the printed document:https://www.gaudry.be/en/mysql-rf-keyring-okv-plugin.html

The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.

References

Manuel MySQL : https://dev.mysql.com/

These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.

Contents Haut