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, seeThe MySQL Keyring。

The instructions here are based on the source code in theplugin/keyringdirectory of MySQL source distributions. The source files in that directory implement a plugin namedkeyring_filethat 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.

#include 

plugin_keyring.hincludesplugin.h, so you need not include the latter file explicitly.plugin.hdefines theMYSQL_KEYRING_PLUGINserver plugin type and the data structures needed to declare the plugin.plugin_keyring.hdefines data structures specific to keyring plugins.

A keyring plugin, like any MySQL server plugin, has a general plugin descriptor (seeSection 4.4.2.1, “Server Plugin Library and Plugin Descriptors”). Inkeyring.cc, the general descriptor forkeyring_filelooks like this:

mysql_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;

Thenamemember (keyring_file) indicates the plugin name. This is the name displayed byINFORMATION_SCHEMA.PLUGINSorSHOW PLUGINS。

The general descriptor also refers tokeyring_system_variables, a structure that exposes a system variable to theSHOW VARIABLESstatement:

static struct st_mysql_sys_var *keyring_system_variables[]= { MYSQL_SYSVAR(data), NULL };

Thekeyring_initinitialization function creates the data file if it does not exist, then reads it and initializes the keystore. Thekeyring_deinitfunction frees data structures associated with the file.

Thekeyring_descriptorvalue in the general descriptor points to the type-specific descriptor. For keyring plugins, this descriptor has the following structure:

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

For thekeyring_fileplugin, the type-specific descriptor looks like this:

static struct st_mysql_keyring keyring_descriptor= { MYSQL_KEYRING_INTERFACE_VERSION, mysql_key_store, mysql_key_fetch, mysql_key_remove, mysql_key_generate };

Themysql_key_xxxfunctions implemented by a keyring plugin are analogous to themy_key_xxxfunctions exposed by the keyring service API. For example, themysql_key_storeplugin function is analogous to themy_key_storekeyring service function. For information about the arguments to keyring service functions and how they are used, seeThe Keyring Service。

To compile and install a plugin library file, use the instructions inSection 4.4.3, “Compiling and Installing Plugin Libraries”。库文件使用,本月all it in the plugin directory (the directory named by theplugin_dirsystem variable). For thekeyring_fileplugin, 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 ofkeyring_file.so(the。sosuffix 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. Forkeyring_file, use these lines in the servermy.cnffile, adjusting the。sosuffix for your platform as necessary:

[mysqld] early-plugin-load=keyring_file.so

For additional information about plugin loading, seeInstalling and Uninstalling Plugins。

To verify plugin installation, examine theINFORMATION_SCHEMA.PLUGINStable or use theSHOW PLUGINSstatement (seeObtaining Server Plugin Information). For example:

mysql> SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS WHERE PLUGIN_NAME LIKE 'keyring%'; +--------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +--------------+---------------+ | keyring_file | ACTIVE | +--------------+---------------+

While thekeyring_fileplugin is installed, it exposes a system variable that indicates the location of the data file it uses for secure information storage:

mysql> SHOW VARIABLES LIKE 'keyring_file%'; +-------------------+----------------------------------+ | Variable_name | Value | +-------------------+----------------------------------+ | keyring_file_data | /usr/local/mysql/keyring/keyring | +-------------------+----------------------------------+

For a description of thekeyring_file_datavariable, seeServer System Variables。

To disable the plugin after testing it, restart the server without an--early-plugin-loadoption that names the plugin.