AWS Key Management Encryption Plugin - Source

You are viewing an old version of this article. View the current version here

Revision: 54750
User: Vladislav Vaintroub
Date: 2017-05-18 22:36

<<product mariadb from=10.1.13>>
This plugin was first available (in the source only) from MariaDB 10.1.13.
<</product>>

<<toc>>
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 [[mariadb-enterprise-aws-kms-encryption-plugin-setup-guide| Amazon Web Services (AWS) Key Management Service (KMS) Encryption Plugin Setup Guide]].

==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 [[http://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html|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 [[http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-file|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 [[https://github.com/awslabs/aws-sdk-cpp | 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:<<code inline=false>>plugin-load-add=aws_key_management  # if plugin is built dynamically
aws_key_management_master_key_id=alias/<your key's alias>
<</code>>
* Start MariaDB Server (##mysqld##)
* Create a table, with encryption enabled:<<code inline=false>>CREATE TABLE t (i int) ENGINE=InnoDB ENCRYPTED=YES
<</code>>

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##
----

Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.

AWS Key Management Encryption Plugin - Source

Products

Services

Pricing

Resources

About Us

Download MariaDB