6.4.4.5 Using the keyring_aws Amazon Web Services Keyring Plugin

To install the keyring_aws plugin, use the general installation instructions found in Section 6.4.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:

To be usable during the server startup process, keyring_aws must be loaded using the --early-plugin-load option. The keyring_aws_cmk_id system variable is mandatory and configures the customer master key (CMK) ID obtained from the AWS KMS server. 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 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 (adjust 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

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 the system variables used to configure the keyring_aws plugin, see Section 6.4.4.11, “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):

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.

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):

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.4.4.7, “Supported Keyring Key Types”.

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: