MySQL 8.0 Reference Manual Including MySQL NDB Cluster 8.0
Keyring service consumers require a keyring plugin to be installed. MySQL provides these plugin choices:
keyring_file
: Stores keyring data in a
file local to the server host. Available in all MySQL
distributions.
keyring_encrypted_file
: Stores keyring
data in an encrypted file local to the server host.
Available in MySQL Enterprise Edition distributions.
keyring_okv
: Uses 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.
For keyring_oci
:
Section 6.4.4.7, “Using the Oracle Cloud Infrastructure Vault Keyring Plugin”
This section describes how to install the keyring plugin of your choosing. For general information about installing plugins, see Section 5.6.1, “Installing and Uninstalling Plugins”.
If you intend to use keyring user-defined functions (UDFs) in conjunction with the keyring plugin, install the UDFs after installing the plugin, using the instructions in Section 6.4.4.10, “General-Purpose Keyring Key-Management Functions”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory location
by setting the value of
plugin_dir
at server startup.
Installation for each keyring plugin is similar. The following
instructions use keyring_file
. Users of a
different keyring plugin can substitute its name for
keyring_file
.
The keyring_file
plugin library file base
name is keyring_file
. The file name suffix
differs per platform (for example, .so
for
Unix and Unix-like systems, .dll
for
Windows).
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 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 InnoDB
initialization.
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:
[mysqld] early-plugin-load=keyring_file.so
Before starting the server, check the notes for your chosen keyring plugin to see whether it permits or requires additional configuration:
keyring_file
:
Section 6.4.4.2, “Using the keyring_file File-Based Plugin”.
keyring_encrypted_file
:
Section 6.4.4.3, “Using the keyring_encrypted_file Keyring Plugin”.
keyring_okv
:
Section 6.4.4.4, “Using the keyring_okv KMIP Plugin”.
keyring_aws
:
Section 6.4.4.5, “Using the keyring_aws Amazon Web Services Keyring Plugin”
keyring_hashicorp
:
Section 6.4.4.6, “Using the HashiCorp Vault Keyring Plugin”
After performing any plugin-specific configuration, verify
plugin installation. With the MySQL server running, examine the
INFORMATION_SCHEMA.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
or
--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, such as InnoDB
:
Plugin loading using
--plugin-load
or
--plugin-load-add
occurs
after InnoDB
initialization.
Plugins installed using INSTALL
PLUGIN
are registered in the
mysql.plugin
system table and loaded
automatically for subsequent server restarts. However,
because mysql.plugin
is an
InnoDB
table, any plugins named in it can
be loaded during startup only after
InnoDB
initialization.
If no keyring 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 example, if
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
keyring plugin.