MySQL Server supports a keyring service that enables internal server components and plugins to securely store sensitive information for later retrieval. This section describes how to write a server-side keyring plugin that can be used by service functions to perform key-management operations. For general keyring information, see The MySQL Keyring.
MySQL 8.4 removed the deprecated keyring plugins in favor of
using the keyring components. For example, use
component_keyring_file
instead of
keyring_file
. For related information,
see Keyring Components Versus Keyring Plugins.
The instructions here are based on the source code in the
plugin/keyring
directory of MySQL source
distributions. The source files in that directory implement a
plugin named keyring_file
that uses a file
local to the server host for data storage.
To write a keyring plugin, include the following header file in the plugin source file. Other MySQL or general header files might also be needed, depending on the plugin capabilities and requirements.
Press CTRL+C to copy#include <mysql/plugin_keyring.h>
plugin_keyring.h
includes
plugin.h
, so you need not include the
latter file explicitly. plugin.h
defines
the MYSQL_KEYRING_PLUGIN
server plugin type
and the data structures needed to declare the plugin.
plugin_keyring.h
defines data structures
specific to keyring plugins.
A keyring plugin, like any MySQL server plugin, has a general
plugin descriptor (see
Section 4.4.2.1, “Server Plugin Library and Plugin Descriptors”). In
keyring.cc
, the general descriptor for
keyring_file
looks like this:
Press CTRL+C to copymysql_declare_plugin(keyring_file) { MYSQL_KEYRING_PLUGIN, /* type */ &keyring_descriptor, /* descriptor */ "keyring_file", /* name */ "Oracle Corporation", /* author */ "store/fetch authentication data to/from a flat file", /* description */ PLUGIN_LICENSE_GPL, keyring_init, /* init function (when loaded) */ keyring_deinit, /* deinit function (when unloaded) */ 0x0100, /* version */ NULL, /* status variables */ keyring_system_variables, /* system variables */ NULL, 0, } mysql_declare_plugin_end;
The name
member
(keyring_file
) indicates the plugin name.
This is the name displayed by
INFORMATION_SCHEMA.PLUGINS
or
SHOW PLUGINS
.
The general descriptor also refers to
keyring_system_variables
, a structure that
exposes a system variable to the SHOW
VARIABLES
statement:
Press CTRL+C to copystatic struct st_mysql_sys_var *keyring_system_variables[]= { MYSQL_SYSVAR(data), NULL };
The keyring_init
initialization function
creates the data file if it does not exist, then reads it and
initializes the keystore. The
keyring_deinit
function frees data
structures associated with the file.
The keyring_descriptor
value in the general
descriptor points to the type-specific descriptor. For keyring
plugins, this descriptor has the following structure:
Press CTRL+C to copystruct st_mysql_keyring { int interface_version; bool (*mysql_key_store)(const char *key_id, const char *key_type, const char* user_id, const void *key, size_t key_len); bool (*mysql_key_fetch)(const char *key_id, char **key_type, const char *user_id, void **key, size_t *key_len); bool (*mysql_key_remove)(const char *key_id, const char *user_id); bool (*mysql_key_generate)(const char *key_id, const char *key_type, const char *user_id, size_t key_len); };
The type-specific descriptor has these members:
interface_version
: By convention, type-specific plugin descriptors begin with the interface version for the given plugin type. The server checksinterface_version
when it loads the plugin to see whether the plugin is compatible with it. For keyring plugins, the value of theinterface_version
member isMYSQL_KEYRING_INTERFACE_VERSION
(defined inplugin_keyring.h
).mysql_key_store
: A function that obfuscates and stores a key in the keyring.mysql_key_fetch
: A function that deobfuscates and retrieves a key from the keyring.mysql_key_remove
: A function that removes a key from the keyring.mysql_key_generate
: A function that generates a new random key and stores it in the keyring.
For the keyring_file
plugin, the
type-specific descriptor looks like this:
Press CTRL+C to copystatic struct st_mysql_keyring keyring_descriptor= { MYSQL_KEYRING_INTERFACE_VERSION, mysql_key_store, mysql_key_fetch, mysql_key_remove, mysql_key_generate };
The
mysql_key_
functions implemented by a keyring plugin are analogous to the
xxx
my_key_
functions exposed by the keyring service API. For example, the
xxx
mysql_key_store
plugin function is
analogous to the my_key_store
keyring
service function. For information about the arguments to
keyring service functions and how they are used, see
The Keyring Service.
To compile and install a plugin library file, use the
instructions in Section 4.4.3, “Compiling and Installing Plugin Libraries”.
To make the library file available for use, install it in the
plugin directory (the directory named by the
plugin_dir
system variable).
For the keyring_file
plugin, it is compiled
and installed when you build MySQL from source. It is also
included in binary distributions. The build process produces a
shared object library with a name of
keyring_file.so
(the
.so
suffix might differ depending on your
platform).
Keyring plugins typically are loaded early during the server
startup process so that they are available to built-in plugins
and storage engines that might depend on them. For
keyring_file
, use these lines in the server
my.cnf
file, adjusting the
.so
suffix for your platform as
necessary:
Press CTRL+C to copy[mysqld] early-plugin-load=keyring_file.so
For additional information about plugin loading, see Installing and Uninstalling Plugins.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement (see
Obtaining Server Plugin Information). For example:
Press CTRL+C to copymysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'keyring%'; +--------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +--------------+---------------+ | keyring_file | ACTIVE | +--------------+---------------+
While the keyring_file
plugin is installed,
it exposes a system variable that indicates the location of
the data file it uses for secure information storage:
Press CTRL+C to copymysql> SHOW VARIABLES LIKE 'keyring_file%'; +-------------------+----------------------------------+ | Variable_name | Value | +-------------------+----------------------------------+ | keyring_file_data | /usr/local/mysql/keyring/keyring | +-------------------+----------------------------------+
To disable the plugin after testing it, restart the server
without an --early-plugin-load
option that names the plugin.