Due to license incompatibilities between the MariaDB server source code and the Amazon AWS C++ SDK, we can only distribute the plugin in source code form, and not as ready-to-use binaries. See Installing the Plugin's Package for details.
MariaDB's data-at-rest encryption requires the use of a key management and encryption plugin. These plugins are responsible both for the management of encryption keys and for the actual encryption and decryption of data.
MariaDB supports the use of multiple encryption keys. Each encryption key uses a 32-bit integer as a key identifier. If the specific plugin supports key rotation, then encryption keys can also be rotated, which creates a new version of the encryption key.
The AWS Key Management plugin is a key management and encryption plugin that uses the Amazon Web Services (AWS) Key Management Service (KMS).
The AWS Key Management plugin uses the 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. It supports multiple encryption keys. It supports key rotation.
Tutorials related to the AWS Key Management plugin can be found at the following pages:
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 .
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 an AWS credentials file for the user who runs mysqld. More information about the credentials file can be found in .
The AWS Key Management plugin depends on the , which uses the . This license is not compatible with MariaDB Server's , so we are not able to distribute packages that contain the AWS Key Management plugin. Therefore, the only way to currently obtain the plugin is to install it from source.
When , the AWS Key Management plugin is built by default, on systems that support it.
Compilation is controlled by the following arguments:
-DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC to build a loadable plugin library
-DAWS_SDK_EXTERNAL_PROJECT=ON to download the AWS C++ SDK code
-DNOT_FOR_DISTRIBUTION=ON to confirm that you know to not distribute the resulting binaries
The plugin uses , 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
You do not need to download/install the AWS C++ SDK yourself; the correct version of the SDK GitHub repository will be cloned into the build directory at build time, and only the libraries for AWS components actually needed by the key management plugin will be built, which takes much less time than building the full AWS C++ SDK.
With all prerequisites installed, the actual build process pretty much comes down to:
Cmake will print the following warning as part of its output. Please take it seriously and do not distribute the aws_key_management.so file to any third parties: You have linked MariaDB with Apache 2.0 libraries! You may not distribute the resulting binary. If you do, you will put yourself into a legal problem with the Free Software Foundation.
After make succeeded you can copy the created aws_key_management.so plugin library file to the plugin directory of your actual MariaDB Server machines installation, e.g. /usr/lib64/mysql/plugin on RedHat/Fedora based systems or /usr/lib/mysql/plugin on Debian-based systems.
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. There are two methods that can be used to install the plugin with MariaDB.
The first method can be used to install the plugin without restarting the server. You can install the plugin dynamically by executing or . For example:
The second method can be used to tell the server to load the plugin when it starts up. The plugin can be installed this way by providing the or the options. This can be specified as a command-line argument to or it can be specified in a relevant server in an . For example:
Before you uninstall the plugin, you should ensure that is completely disabled, and that MariaDB no longer needs the plugin to decrypt tables or other files.
You can uninstall the plugin dynamically by executing or . For example:
If you installed the plugin by providing the or the options in a relevant server in an , then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.
To enable the AWS Key Management plugin, you also need to set the plugin's system variables. The system variable is the primary one to set. These system variables can be specified as command-line arguments to or they can be specified in a relevant server in an . For example:
Once you've updated the configuration file, restart the MariaDB server to apply the changes and make the key management and encryption plugin available for use.
Once the AWS Key Management Plugin is enabled, you can use it by creating an encrypted table:
Now, table t will be encrypted using the encryption key generated by AWS.
For more information on how to use encryption, see .
The AWS Key Management Plugin supports . Each encryption key can be defined with a different 32-bit integer as a key identifier. If a previously unused identifier is used, then the plugin will automatically generate a new key.
When , the key that is used to encrypt tables .
When , the key that is used to encrypt tables .
The AWS Key Management plugin does support . To rotate a key, set the system variable. For example, to rotate key with ID 2:
Or to rotate all keys, set the value to -1:
aws_key_management_key_specDescription: Encryption algorithm used to create new keys
Commandline: --aws-key-management-key-spec=value
Scope: Global
Dynamic: No
aws_key_management_log_levelDescription: 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.
Commandline: --aws-key-management-log-level=value
Scope: Global
Dynamic: No
aws_key_management_master_key_idDescription: 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.
Commandline: --aws-key-management-master-key-id=value
Scope: Global
Dynamic: No
aws_key_management_mockDescription: Mock AWS KMS calls (for testing). Must be enabled at compile-time.
Commandline: --aws-key-management-mock
Scope: Global
Dynamic: No
aws_key_management_regionDescription: AWS region name, e.g us-east-1 . Default is SDK default, which is us-east-1.
Commandline: --aws-key-management-region=value
Scope: Global
Dynamic: No
aws_key_management_request_timeoutDescription: Timeout in milliseconds for create HTTPS connection or execute AWS request. Specify 0 to use SDK default.
Commandline: --aws-key-management-request-timeout=value
Scope: Global
Dynamic: No
aws_key_management_rotate_keyDescription: 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.
Commandline: --aws-key-management-rotate-key=value
Scope: Global
aws_key_managementDescription: Controls how the server should treat the plugin when the server starts up.
Valid values are:
OFF - Disables the plugin without removing it from the table.
This page is licensed: CC BY-SA / Gnu FDL
opensslYou may need to use a newer version of cmake than is provided by default in your OS.
Data Type: enumerated
Default Value: AES_128
Valid Values: AES_128, AES_256
Data Type: enumerated
Default Value: Off
Valid Values: Off, Fatal, Warn, Info, Debug and Trace
Data Type: string
Default Value:
Data Type: boolean
Default Value: OFF
Valid Values: OFF, ON
Data Type: string
Default Value: 'us-east-1'
Data Type: integer
Default Value: 0
Data Type: integer
Default Value:
ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.
See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
Commandline: --aws-key-management=value
Data Type: enumerated
Default Value: ON
Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT
1.0
Stable
,
1.0
Beta
1.0
Experimental
# clone the MariaDB Server source code repository
git clone https://github.com/MariaDB/server.git
cd server
# prepare the build
mkdir _build
cd _build
cmake .. -DNOT_FOR_DISTRIBUTION=ON \
-DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC \
-DAWS_SDK_EXTERNAL_PROJECT=1
# build the plugin only
cd plugin/aws_key_management
makeINSTALL SONAME 'aws_key_management';[mariadb]
...
plugin_load_add = aws_key_managementUNINSTALL SONAME 'aws_key_management';[mariadb]
...
aws_key_management_master_key_id=alias/<your key's alias>CREATE TABLE t (i INT) ENGINE=InnoDB ENCRYPTED=YESSET GLOBAL aws_key_management_rotate_key=2;SET GLOBAL aws_key_management_rotate_key=-1;