Keyring service consumers require that a keyring component or plugin be installed:
To use a keyring plugin, begin with the instructions here. (Also, for general information about installing plugins, see Section 5.6.1, “Installing and Uninstalling Plugins”.)
To use a keyring component instead, begin with Section 188.8.131.52, “Keyring Component Installation”.
If you intend to use keyring functions in conjunction with the chosen keyring component or plugin, install the functions after installing that component or plugin, using the instructions in Section 184.108.40.206, “General-Purpose Keyring Key-Management Functions”.
Only one keyring component or plugin should be enabled at a time. Enabling multiple keyring components or plugins is unsupported and results may not be as anticipated.
A keyring component must be enabled on the MySQL Server instance if you need to support secure storage for persisted system variable values, rather than a keyring plugin, which do not support the function. See Persisting Sensitive System Variables.
MySQL provides these keyring plugin choices:
keyring_file(deprecated): Stores keyring data in a file local to the server host. Available in MySQL Community Edition and MySQL Enterprise Edition distributions. For instructions about installing the component that replaces this plugin, see Section 220.127.116.11, “Keyring Component Installation”.
keyring_encrypted_file(deprecated): Stores keyring data in an encrypted, password-protected file local to the server host. Available in MySQL Enterprise Edition distributions. For instructions about installing the component that replaces this plugin, see Section 18.104.22.168, “Keyring Component Installation”.
keyring_okv: A KMIP 1.1 plugin for use with KMIP-compatible back end keyring storage products such as Oracle Key Vault and Gemalto SafeNet KeySecure Appliance. Available in MySQL Enterprise Edition distributions.
keyring_aws: Communicates with the Amazon Web Services Key Management Service as a back end for key generation and uses a local file for key storage. Available in MySQL Enterprise Edition distributions.
keyring_hashicorp: Communicates with HashiCorp Vault for back end storage. Available in MySQL Enterprise Edition distributions.
keyring_oci(deprecated): Communicates with Oracle Cloud Infrastructure Vault for back end storage. See Section 22.214.171.124, “Using the Oracle Cloud Infrastructure Vault Keyring Plugin”.
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, configure the plugin directory location
by setting the value of
plugin_dir at server startup.
A keyring component or plugin must be loaded early during the
server startup sequence so that other components can access it
as necessary during their own initialization. For example, the
InnoDB storage engine uses the keyring for
tablespace encryption, so a keyring component or plugin must be
loaded and available prior to
Installation for each keyring plugin is similar. The following
instructions describe how to install
keyring_file. To use a different keyring
plugin, 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,
To load the plugin, use the
--early-plugin-load option to
name the plugin library file that contains it. For example, on
platforms where the plugin library file suffix is
.so, use these lines in the server
my.cnf file, adjusting the
.so suffix for your platform as necessary:
Before starting the server, check the notes for your chosen keyring plugin for configuration instructions specific to that plugin:
keyring_encrypted_file: Section 126.96.36.199, “Using the keyring_encrypted_file Encrypted File-Based Keyring Plugin”.
keyring_okv: Section 188.8.131.52, “Using the keyring_okv KMIP Plugin”.
keyring_hashicorp: Section 184.108.40.206, “Using the HashiCorp Vault Keyring Plugin”
After performing any plugin-specific configuration, start the
server. Verify plugin installation by examining the Information
PLUGINS table or use the
SHOW PLUGINS statement (see
Section 5.6.2, “Obtaining 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 | +--------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
Plugins can be loaded by methods other than
--early-plugin-load, 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
components that use the keyring, 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
If no keyring component or plugin is available when a 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