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.
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 whichkeyring_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
, andkey.pem
. If the key file is password-protected, thessl
directory can contain a single-line text file namedpassword.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”.
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 theSTANDBY_SERVER
variable is optional. Thekeyring_okv
plugin attempts to communicate with the server running on the host named by theSERVER
variable and falls back toSTANDBY_SERVER
if that fails.NoteIf 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 theokvclient.ora
file to specify the IP addresses and port numbers of the servers as a comma-separated list in the value of theSTANDBY_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 theokvclient.jar
file:jar xf okvclient.jar ssl
Copy the Oracle Key Vault support files (the
okvclient.ora
file and thessl
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.
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 theokvclient.ora
file to specify the IP addresses and port numbers of the servers as a comma-separated list in the value of theSTANDBY_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 namedCA.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
andprivate_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 thessl
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 thessl
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.
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.
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.
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 thessl
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 renamekey.pem.new
tokey.pem
.Change the ownership and access mode of new
key.pem
file andpassword.txt
file as necessary to ensure that they have the same restrictions as other files in thessl
directory.