AWS Key Management Encryption Plugin

MariaDB's data-at-rest encryption supports the use of multiple encryption keys. Each key uses a 32-bit integer as a key identifier and can be versioned, allowing you to automatically re-encrypt data from older to newer versions of the key.

In order to use data-at-rest encryption, you need to load an encryption key management plugin to manage the encryption keys.

The AWS Key Management plugin is a encryption key management plugin that uses the Amazon Web Services (AWS) Key Management Service (KMS).

Overview

The AWS Key Management plugin uses the Amazon Web Services (AWS) Key Management Service (KMS) to generate and store AES keys on disk, in encrypted form, using the Customer Master Key (CMK) kept in AWS KMS. When MariaDB Server starts, the plugin will decrypt the encrypted keys, using the AWS KMS "Decrypt" API function. MariaDB data will then be encrypted and decrypted using the AES key.

Versions

Tutorials

Tutorials related to the AWS Key Management plugin can be found at the following pages:

• Amazon Web Services (AWS) Key Management Service (KMS) Encryption Plugin Setup Guide
• Amazon Web Services (AWS) Key Management Service (KMS) Encryption Plugin Advanced Usage

Preparation

• Before you use the plugin, you need to create a Customer Master Key (CMK). Create a key using the AWS Console as described in the AMS KMS developer guide.
• The easiest way to give the AWS key management plugin access to the key is to create an IAM Role with access to the key, and to apply that IAM Role to an EC2 instance where MariaDB Server runs.
• Make sure that MariaDB Server runs under the correct AWS identity that has access to the above key. For example, you can store the AWS credentials in a AWS credentials file for the user who runs mysqld. More information about the credentials file can be found in the AWS CLI Getting Started Guide.

Installing the AWS Key Management Plugin Package

The AWS Key Management plugin is included in MariaDB packages as the aws_key_management.so or aws_key_management.dll shared library on systems where it can be built. The plugin is not provided in packages for MariaDB 10.1, but it is provided in packages for MariaDB 10.2 and later, at least for environments where the plugin is supported. The plugin was first included in MariaDB 10.2.6.

Installing on Linux

The plugin is included in binary tarballs on Linux.

Package managers can also be used to install standalone packages that contain the plugin.

Installing with a Package Manager

Installing with yum

On RHEL, CentOS, and other similar Linux distributions that use RPM packages, you can install the AWS Key Management Plugin with yum:

sudo yum install MariaDB-aws-key-management

Installing with apt-get

On Debian, Ubuntu, and other similar Linux distributions that use DEB packages, you can install the AWS Key Management Plugin with apt-get:

sudo apt-get install mariadb-plugin-aws-key-management

Installing on Windows

The plugin is included in MSI and ZIP packages on Windows.

Installing from Source

When compiling MariaDB from source, the AWS Key Management plugin is not built by default in MariaDB 10.1, but it is built by default in MariaDB 10.2 and later, on systems that support it.

Compilation is controlled by the -DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC -DAWS_SDK_EXTERNAL_PROJECT=1 cmake arguments.

The plugin uses AWS C++ SDK, which introduces the following restrictions:

• The plugin can only be built on Windows, Linux and macOS.
• The plugin requires that one of the following compilers is used: gcc 4.8 or later, clang 3.3 or later, Visual Studio 2013 or later.
• On Unix, the libcurl development package (e.g. libcurl3-dev on Debian Jessie), uuid development package and openssl need to be installed.
• You may need to use a newer version of cmake than is provided by default in your OS.

Installing the Plugin with MariaDB

Even after the package that contains the plugin's shared library is installed on the operating system, the plugin is not actually installed by MariaDB by default. To install the plugin with MariaDB, you need to install it with INSTALL PLUGIN. For example:

INSTALL SONAME 'aws_key_management';

You can also load the plugin by providing the --plugin-load or the --plugin-load-add options with the name of the shared library as an argument, which is aws_key_management.so. This can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file. For example:

[mysqld]
...
plugin-load = aws_key_management

Configuring the AWS Key Management Plugin

To enable the AWS Key Management plugin, you also need to set the plugin's system variables. The aws_key_management_master_key_id system variable is the primary one to set. These system variables can be specified as command-line arguments to mysqld or they can be specified in a relevant server option group in an option file. For example:

[mysqld]
...
aws_key_management_master_key_id=alias/<your key's alias>

Once you've updated the configuration file, restart the MariaDB server to apply the changes and make the encryption plugin available for use.

Using the AWS Key Management Plugin

Once the AWS Key Management Plugin is enabled, you can use it by creating an encrypted table:

CREATE TABLE t (i int) ENGINE=InnoDB ENCRYPTED=YES

Now, table t will be encrypted using the encryption key generated by AWS.

Multiple key IDs are supported. A different key can be chosen by adding the ENCRYPTION_KEY_ID table option to the CREATE TABLE statement. A new key will automatically be generated if a previously unused key ID is supplied.

Rotating Keys

The AWS Key Management plugin does support key rotation. To rotate a key, set the aws_key_management_rotate_key system variable. For example, to rotate key with ID 2:

SET GLOBAL aws_key_management_rotate_key=2;

Or to rotate all keys, set the value to -1:

SET GLOBAL aws_key_management_rotate_key=-1;

System Variables

aws_key_management_master_key_id

• Description: AWS KMS Customer Master Key ID (ARN or alias prefixed by alias/) for the master encryption key. Used to create new data keys. If not set, no new data keys will be created.

aws_key_management_rotate_key

• Description: Set this variable to a data key ID to perform rotation of the key to the master key given in aws_key_management_master_key_id. Specify -1 to rotate all keys.

aws_key_management_region

• Description: AWS region name, e.g us-east-1 . Default is SDK default, which is us-east-1.

aws_key_management_key_spec

• Description: Encryption algorithm used to create new keys
• Default Value: AES_128
• Valid Values: AES_128, AES_256

aws_key_management_log_level

• Description: Dump log of the AWS SDK to MariaDB error log. Permitted values, in increasing verbosity, are Off (default), Fatal, Error, Warn, Info, Debug, and Trace.
• Default Value: Off
• Valid Values: Off, Fatal, Warn, Info, Debug and Trace