Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.0Mb
PDF (A4) - 38.1Mb
PDF (RPM) - 37.3Mb
HTML Download (TGZ) - 10.2Mb
HTML Download (Zip) - 10.3Mb
HTML Download (RPM) - 8.9Mb
Man Pages (TGZ) - 217.0Kb
Man Pages (Zip) - 329.9Kb
Info (Gzip) - 3.5Mb
Info (Zip) - 3.5Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  Using the keyring_aws Amazon Web Services Keyring Plugin

6.5.4.4 Using the keyring_aws Amazon Web Services Keyring Plugin

Note

The keyring_aws plugin is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see http://www.mysql.com/products/.

The keyring_aws plugin is a keyring plugin that 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 keyring_aws.

keyring_aws is available on these platforms:

  • Debian 8

  • EL7

  • macOS 10.12

  • OS X 10.10 and 10.11

  • SLES 12

  • Ubuntu 14.04 and 16.04

  • Windows

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 keyring plugin.

keyring_aws Configuration

To install the keyring_aws plugin, use the general installation instructions found in Section 6.5.4.1, “Keyring Plugin Installation”, together with the plugin-specific configuration information found here.

The plugin library file contains the keyring_aws plugin and two user-defined functions (UDFs), keyring_aws_rotate_cmk() and keyring_aws_rotate_keys().

To configure keyring_aws, you must obtain a secret access key that provides credentials for communicating with AWS KMS and write it to a configuration file:

  1. Create an AWS KMS account.

  2. 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.

  3. If necessary, create the directory in which the configuration file will 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_conf as the file name, the following commands (executed as root) create its parent directory and set the directory mode and ownership:

    shell> cd /usr/local/mysql
    shell> mkdir mysql-keyring
    shell> chmod 750 mysql-keyring
    shell> chown mysql mysql-keyring
    shell> chgrp mysql mysql-keyring

    At MySQL startup, set the keyring_aws_conf_file system variable to /usr/local/mysql/mysql-keyring/keyring_aws_conf to indicate the configuration file location to the server.

  4. Prepare the keyring_aws configuration 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 AKIAIOSFODNN7EXAMPLE and the key is wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, the configuration file looks like this:

    AKIAIOSFODNN7EXAMPLE
    wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

keyring_aws must be loaded at each server startup using the --early-plugin-load option. The keyring_aws_conf_file and keyring_aws_data_file system variables optionally configure the locations of the files used by the keyring_aws plugin for configuration information and data storage. The variable default values are platform specific. To configure the file locations explicitly, set the variable values at startup. For example, use these lines in the server my.cnf file (adjust the .so suffix and file locations for your platform as necessary):

[mysqld]
early-plugin-load=keyring_aws.so
keyring_aws_conf_file=/usr/local/mysql/mysql-keyring/keyring_aws_conf
keyring_aws_data_file=/usr/local/mysql/mysql-keyring/keyring_aws_data

For the 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 keyring_aws_conf_file and keyring_aws_data_file, see Section 6.5.4.8, “Keyring System Variables”.

Start the MySQL server and install the UDFs associated with the keyring_aws plugin. This is a one-time operation, performed by executing the following statements (adjust the .so suffix for your platform as necessary):

CREATE FUNCTION keyring_aws_rotate_cms RETURNS INTEGER SONAME 'keyring_aws.so';
CREATE FUNCTION keyring_aws_rotate_keys RETURNS INTEGER SONAME 'keyring_aws.so';

Obtain a customer master key (CMK) from AWS:

  1. Use the AWS KMS account (created previously) to create a CMK.

  2. Connect to the MySQL server and set the keyring_aws_cmk_id system variable to the CMK ID obtained from the AWS KMS server. For example:

    SET GLOBAL keyring_aws_cmk_id =
    'arn:aws:kms:us-west-2:111122223333:key/abcd1234-ef56-ab12-cd34-ef56abcd1234';

    SET GLOBAL sets the value for the running MySQL instance. To also set the value for subsequent restarts, set the variable in the server my.cnf file.

keyring_aws Operation

At plugin startup, the keyring_aws plugin 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.

During operation, keyring_aws maintains encrypted keys in the in-memory cache and uses the storage file as local persistent storage. Each keyring operation is transactional: keyring_aws either 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 checksum.

keyring_aws does not cache unencrypted keys in memory. (Between keyring operations, no unencrypted key material is stored in memory.)

The keyring_aws plugin supports the functions that comprise the standard keyring service interface. Keyring operations performed by these functions are accessible at two levels:

Example (using UDFs):

SELECT keyring_key_generate('MyKey', 'AES', 32);
SELECT keyring_key_remove('MyKey');

In addition, the keyring_aws_rotate_cmk() and keyring_aws_rotate_keys() UDFs 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 the UDFs. There are no corresponding C-languge key service functions.

The key types permitted by keyring_aws are described in Section 6.5.4.5, “Supported Keyring Key Types”.

keyring_aws Credential Changes

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:

  1. Use AWS KMS to create a new secret access key ID and secret access key.

  2. Store the new credentials in the configuration file (the file named by the keyring_aws_conf_file system variable). The file format is as described previously.

  3. Reinitialize the keyring_aws plugin so that it rereads 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 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 (adjust the .so suffix 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 PLUGIN has the side effect of registering the plugin it in the mysql.plugin system table. Because of this, if you decide to stop using keyring_aws, it is not sufficient to remove the --early-plugin-load option 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 mysql.plugin.

      Consequently, if you execute the UNINSTALL PLUGIN plus INSTALL PLUGIN sequence just described to change the AWS KMS credentials, then to stop using keyring_aws, it is necessary to execute UNINSTALL PLUGIN again to unregister the plugin in addition to removing the --early-plugin-load option.


User Comments
Sign Up Login You must be logged in to post a comment.