Keyring service consumers require a keyring plugin to be installed. MySQL provides these plugin choices:
keyring_file: A plugin that stores keyring data in a file local to the server host. Available in all MySQL distributions as of MySQL 5.7.11.
keyring_okv: A plugin that uses Oracle Key Vault for keyring backend storage. Available in MySQL Enterprise Edition distributions as of MySQL 5.7.12.
This section describes how to install the keyring plugin of your choosing. For general information about installing plugins, see Section 6.5.2, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
variable). If necessary, set the value of
plugin_dir at server startup to
tell the server the plugin directory location.
Installation for each keyring plugin is similar. The following
keyring_file. Users of a
different keyring plugin can substitute its name for
keyring_file plugin library file base
keyring_file. The file name suffix
differs per platform (for example,
Unix and Unix-like systems,
Only one keyring plugin should be enabled at a time. Enabling multiple keyring plugins is unsupported and results may not be as anticipated.
The keyring plugin must be loaded early during the server
startup sequence so that server components can access it as
necessary during their own initialization. For example, the
InnoDB storage engine uses the keyring for
tablespace encryption, so the keyring plugin must be loaded and
available prior to
To load the plugin, use the
--early-plugin-load option to
name the plugin library file. For example, on platforms where
the plugin library file suffix is
these lines in the server
.so suffix for your platform as
In MySQL 5.7.11, the default
--early-plugin-load value was
the name of the
keyring_file plugin library
file, so that plugin was loaded by default.
InnoDB tablespace encryption requires the
keyring_file plugin to be loaded prior to
InnoDB initialization, so this change of
value introduces an incompatibility for upgrades from 5.7.11
to 5.7.12 or higher. Administrators who have encrypted
InnoDB tablespaces must take explicit
action to ensure continued loading of the
keyring_file plugin: Start the server with
that names the plugin library file.
Before starting the server, check the notes for your chosen keyring plugin to see whether it permits or requires additional configuration:
keyring_file: Section 126.96.36.199, “Configuring the keyring_file File-Based Plugin”.
keyring_okv: Section 188.8.131.52, “Configuring the keyring_okv Oracle Key Vault Plugin”.
After performing any plugin-specific configuration, verify
plugin installation. With the MySQL server running, examine the
INFORMATION_SCHEMA.PLUGINS table or
SHOW PLUGINS statement
(see Section 6.5.3, “Obtaining Server Plugin Information”). For
SELECT PLUGIN_NAME, PLUGIN_STATUS FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE 'keyring%';+--------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +--------------+---------------+ | keyring_file | ACTIVE | +--------------+---------------+
If no keyring plugin is available when a server component tries
to access the keyring service, the service cannot be used by
that component. As a result, the component may fail to
initialize or may initialize with limited functionality. For
InnoDB finds that there are
encrypted tablespaces when it initializes, it attempts to access
the keyring. If the keyring is unavailable,
InnoDB can access only unencrypted
tablespaces. To ensure that
InnoDB can access
encrypted tablespaces as well, use
--early-plugin-load to load the
Plugins can be loaded by other methods, such as the
--plugin-load-add option or the
INSTALL PLUGIN statement.
However, keyring plugins loaded using those methods may be
available too late in the server startup sequence for certain
server components, such as
Plugins installed using
INSTALL PLUGINare registered in the
mysql.pluginsystem table and loaded automatically for subsequent server restarts. However, because
InnoDBtable, any plugins named in it can be loaded during startup only after