MySQL :: MySQL 8.0 Reference Manual :: 8.4.4.8 Using the keyring

MySQL 8.0 Reference Manual / ... / Using the keyring_okv KMIP Plugin

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

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 8.4.4.15, “General-Purpose Keyring Key-Management Functions”.
C interface: In C-language code, call the keyring service functions described in Section 7.6.9.2, “The Keyring Service”.

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

To install keyring_okv, use the general instructions found in Section 8.4.4.3, “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 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 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, 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, see Section 8.4.4.19, “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. 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:

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 contains 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 is 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 expected file contents include lines that look like this:
```
SERVER=host_ip:port_num
STANDBY_SERVER=host_ip:port_num
```
The SERVER variable is mandatory, and the STANDBY_SERVER variable is optional. 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.

Note

If the existing file is not in this format, then create a new file with the lines shown in the previous example. Also, consider backing up the okvclient.ora file before you run the okvutil command. Restore the file as needed.

From MySQL 8.0.29, you can specify more than one standby server (up to a maximum of 64). If you do, the keyring_okv plugin iterates over them until it can establish a connection, and fails if it cannot. To add extra standby servers, edit the okvclient.ora file to specify the IP addresses and port numbers of the servers as a comma-separated list in the value of the STANDBY_SERVER variable. For example:
```
STANDBY_SERVER=host_ip:port_num,host_ip:port_num,host_ip:port_num,host_ip:port_num
```
Ensure that the list of standby servers is kept short, accurate, and up to date, and servers that are no longer valid are removed. There is a 20-second wait for each connection attempt, so the presence of a long list of invalid servers can significantly affect the keyring_okv plugin’s connection time and therefore the server startup time.
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.

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 contains 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, and also running on alternative host 203.0.113.125 and listening on port 8041, the okvclient.ora file looks like this:
```
SERVER=198.51.100.20:9002
STANDBY_SERVER=203.0.113.125:8041
```
From MySQL 8.0.29, you can specify more than one standby server (up to a maximum of 64). If you do, the keyring_okv plugin iterates over them until it can establish a connection, and fails if it cannot. To add extra standby servers, edit the okvclient.ora file to specify the IP addresses and port numbers of the servers as a comma-separated list in the value of the STANDBY_SERVER variable. For example:
```
STANDBY_SERVER=host_ip:port_num,host_ip:port_num,host_ip:port_num,host_ip:port_num
```
Ensure that the list of standby servers is kept short, accurate, and up to date, and servers that are no longer valid are removed. There is a 20-second wait for each connection attempt, so the presence of a long list of invalid servers can significantly affect the keyring_okv plugin’s connection time and therefore the server startup time.
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 can 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.

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.

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.

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

PREV HOME UP NEXT

PDF (US Ltr) - 43.3Mb
PDF (A4) - 43.4Mb
Man Pages (TGZ) - 296.6Kb
Man Pages (Zip) - 401.9Kb
Info (Gzip) - 4.3Mb
Info (Zip) - 4.3Mb