keyring_aws plugin is an extension
included in MySQL Enterprise Edition, a commercial product. To learn more about
commercial products, see https://www.mysql.com/products/.
keyring_aws keyring plugin communicates
with the Amazon Web Services Key Management Service (AWS KMS) as
a back end for key generation and uses a local file for key
storage. All keyring material is generated exclusively by the
AWS server, not by
MySQL Enterprise Edition can work with
keyring_aws on Red Hat
Enterprise Linux, SUSE Linux Enterprise Server, Debian, Ubuntu,
macOS, and Windows. MySQL Enterprise Edition does not support the use of
keyring_aws on these platforms:
Generic Linux (glibc2.12)
The discussion here assumes that you are familiar with AWS in general and KMS in particular. Some pertinent information sources:
The following sections provide configuration and usage
information for the
keyring_aws, use the general
instructions found in
Section 6.4.1, “Keyring Plugin Installation”, together with
the plugin-specific configuration information found here.
keyring_aws, you must obtain a
secret access key that provides credentials for communicating
with AWS KMS and write it to a configuration file:
Create an AWS KMS account.
Use AWS KMS to create a secret access key ID and secret access key. The access key serves to verify your identity and that of your applications.
Use the AWS KMS account to create a customer master key (CMK) ID. At MySQL startup, set the
keyring_aws_cmk_idsystem variable to the CMK ID value. This variable is mandatory and there is no default. (Its value can be changed at runtime if desired using
If necessary, create the directory in which the configuration file is to be located. The directory should have a restrictive mode and be accessible only to the account used to run the MySQL server. For example, on Unix and Unix-like systems, to use
/usr/local/mysql/mysql-keyring/keyring_aws_confas the file name, the following commands (executed as
root) create its parent directory and set the directory mode and ownership:
$> cd /usr/local/mysql $> mkdir mysql-keyring $> chmod 750 mysql-keyring $> chown mysql mysql-keyring $> chgrp mysql mysql-keyring
At MySQL startup, set the
keyring_aws_conf_filesystem variable to
/usr/local/mysql/mysql-keyring/keyring_aws_confto indicate the configuration file location to the server.
keyring_awsconfiguration file, which should contain two lines:
Line 1: The secret access key ID
Line 2: The secret access key
For example, if the key ID is
wwwwwwwwwwwwwEXAMPLEand the key is
xxxxxxxxxxxxx/yyyyyyy/zzzzzzzzEXAMPLEKEY, the configuration file looks like this:
To be usable during the server startup process,
keyring_aws must be loaded using the
--early-plugin-load option. The
variable is mandatory and configures the customer master key
(CMK) ID obtained from the AWS KMS server. The
variables optionally configure the locations of the files used
keyring_aws plugin for configuration
information and data storage. The file location variable
default values are platform specific. To configure the
locations explicitly, set the variable values at startup. For
example, use these lines in the server
my.cnf file, adjusting the
.so suffix and file locations for your
platform as necessary:
[mysqld] early-plugin-load=keyring_aws.so keyring_aws_cmk_id='arn:aws:kms:us-west-2:111122223333:key/abcd1234-ef56-ab12-cd34-ef56abcd1234' keyring_aws_conf_file=/usr/local/mysql/mysql-keyring/keyring_aws_conf keyring_aws_data_file=/usr/local/mysql/mysql-keyring/keyring_aws_data
keyring_aws plugin to start
successfully, the configuration file must exist and contain
valid secret access key information, initialized as described
previously. The storage file need not exist. If it does not,
keyring_aws attempts to create it (as well
as its parent directory, if necessary).
For additional information about the system variables used to
keyring_aws plugin, see
Section 6.4.12, “Keyring System Variables”.
Start the MySQL server and install the functions associated
keyring_aws plugin. This is a
one-time operation, performed by executing the following
statements, adjusting the
.so suffix for
your platform as necessary:
CREATE FUNCTION keyring_aws_rotate_cmk RETURNS INTEGER SONAME 'keyring_aws.so'; CREATE FUNCTION keyring_aws_rotate_keys RETURNS INTEGER SONAME 'keyring_aws.so';
For additional information about the
keyring_aws functions, see
Section 6.4.9, “Plugin-Specific Keyring Key-Management Functions”.
At plugin startup, the
reads the AWS secret access key ID and key from its
configuration file. It also reads any encrypted keys contained
in its storage file into its in-memory cache.
encrypted keys in the in-memory cache and uses the storage
file as local persistent storage. Each keyring operation is
successfully changes both the in-memory key cache and the
keyring storage file, or the operation fails and the keyring
state remains unchanged.
To ensure that keys are flushed only when the correct keyring
storage file exists,
keyring_aws stores a
SHA-256 checksum of the keyring in the file. Before updating
the file, the plugin verifies that it contains the expected
keyring_aws plugin supports the
functions that comprise the standard MySQL Keyring service
interface. Keyring operations performed by these functions are
accessible at two levels:
SQL interface: In SQL statements, call the functions described in Section 6.4.8, “General-Purpose Keyring Key-Management Functions”.
C interface: In C-language code, call the keyring service functions described in The Keyring Service.
Example (using the SQL interface):
SELECT keyring_key_generate('MyKey', 'AES', 32); SELECT keyring_key_remove('MyKey');
In addition, the
functions “extend” the keyring plugin interface
to provide AWS-related capabilities not covered by the
standard keyring service interface. These capabilities are
accessible only by calling these functions using SQL. There
are no corresponding C-languge key service functions.
For information about the characteristics of key values
Section 6.4.6, “Supported Keyring Key Types and Lengths”.
Assuming that the
keyring_aws plugin has
initialized properly at server startup, it is possible to
change the credentials used for communicating with AWS KMS:
Use AWS KMS to create a new secret access key ID and secret access key.
Store the new credentials in the configuration file (the file named by the
keyring_aws_conf_filesystem variable). The file format is as described previously.
keyring_awsplugin so that it re-reads the configuration file. Assuming that the new credentials are valid, the plugin should initialize successfully.
There are two ways to reinitialize the plugin:
Restart the server. This is simpler and has no side effects, but is not suitable for installations that require minimal server downtime with as few restarts as possible.
Reinitialize the plugin without restarting the server by executing the following statements, adjusting the
.sosuffix for your platform as necessary:
UNINSTALL PLUGIN keyring_aws; INSTALL PLUGIN keyring_aws SONAME 'keyring_aws.so';Note
In addition to loading a plugin at runtime,
INSTALL PLUGINhas the side effect of registering the plugin it in the
mysql.pluginsystem table. Because of this, if you decide to stop using
keyring_aws, it is not sufficient to remove the
--early-plugin-loadoption from the set of options used to start the server. That stops the plugin from loading early, but the server still attempts to load it when it gets to the point in the startup sequence where it loads the plugins registered in
Consequently, if you execute the
INSTALL PLUGINsequence just described to change the AWS KMS credentials, then to stop using
keyring_aws, it is necessary to execute
UNINSTALL PLUGINagain to unregister the plugin in addition to removing the