Movatterモバイル変換

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/keyring directory of MySQL source distributions. The source files in that directory implement a plugin namedkeyring_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.

#include <mysql/plugin_keyring.h>

plugin_keyring.h includesplugin.h, so you need not include the latter file explicitly.plugin.h defines theMYSQL_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 (seeSection 4.4.2.1, “Server Plugin Library and Plugin Descriptors”). Inkeyring.cc, the general descriptor forkeyring_file looks 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;

Thename member (keyring_file) indicates the plugin name. This is the name displayed byINFORMATION_SCHEMA.PLUGINS orSHOW PLUGINS.

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

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

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

Thekeyring_descriptor value 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_file plugin, 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_xxx functions implemented by a keyring plugin are analogous to themy_key_xxx functions exposed by the keyring service API. For example, themysql_key_store plugin function is analogous to themy_key_store keyring 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”. To make the library file available for use, install it in the plugin directory (the directory named by theplugin_dir system variable). For thekeyring_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 ofkeyring_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. Forkeyring_file, use these lines in the servermy.cnf file, adjusting the.so suffix 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.PLUGINS table or use theSHOW PLUGINS statement (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_file plugin 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_data variable, seeServer System Variables.

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