AWS Key Management Encryption Plugin

The AWS Key Management plugin uses the Amazon Web Services (AWS) Key Management Service (KMS) for encryption at rest.

The plugin uses AWS Key management service 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 data keys, using the AWS KMS "Decrypt" API function. MariaDB data will then be encrypted and decrypted using the AES key.

The AWS KMS plugin is included in MariaDB Enterprise packages, on OSs where it can be built, starting with MariaDB Enterprise 10.1.13, and in MSI, ZIP, RPM, .deb, and .tar.gz distributions starting from MariaDB 10.2.6.

For more information, consult the Amazon Web Services (AWS) Key Management Service (KMS) Encryption Plugin Setup Guide.

Versions

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.

Building from source

The plugin is disabled by default in MariaDB Server 10.1. It's built by default, where possible, in MariaDB Server 10.2.

To compile it yourself, use the -DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC CMake argument.

The plugin uses AWS C++ SDK, which induces 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 and openssl need to be installed.
• You may need to use a newer version of CMake than is provided by default in your OS.

Using the plugin

• Add the following lines to my.ini/my.cnf:

  plugin-load-add=aws_key_management  # if plugin is built dynamically
  aws_key_management_master_key_id=alias/<your key's alias>
  

• Start MariaDB Server (mysqld)
• Create a table, with encryption enabled:

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

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

Multiple key IDs are supported, by adding ENCRYPTION_KEY_ID=<number> can be added to the CREATE TABLE command. New keys will automatically be generated if a previously unused key ID is supplied.

Plugin 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