MariaDB Encryption supports the use of multiple encryption keys. Each key uses a 32-bit integer as a key identifier and can be versioned. InnoDB and XtraDB then automatically re-encrypt data from older to newer versions of the same key.

How you store and rotate keys depends on the Key Management solution you choose. Currently, you have three options:

File Key Management Plugin

Encryption plugins developed for MariaDB are responsible for handling keys and versioning keys. The File Key Management plugin that ships with MariaDB and can serve as example and as starting point in developing encryption plugins.

The File Key Management plugin is an encryption plugin that reads keys from file. It enables additional server system variables.


  • Description: Defines the algorithm to use for encryption.
  • Commandline: --file-key-management-encryption-algorithm=value
  • Scope: Global
  • Dynamic: No
  • Data Type: enum
  • Default Value: aes_cbc


  • Description: Defines the key or path to the file that contains the key to use in decrypting the file with the encryption keys, which allows you to better secure it on your file system.
  • Commandline: --file-key-management-filekey=value
  • Scope: Global
  • Dynamic: No
  • Data Type: string
  • Default Value: (empty)


  • Description: Defines the path to the file that contains the encryption keys.
  • Commandline: --file-key-management-filename=value
  • Scope: Global
  • Dynamic: No
  • Data Type: string
  • Default Value: (empty)

Preparing File Keys

In order to encrypt your tables with keys using the File Key Management plugin, you first need to create the file that contains the keys. You can then, optionally, encrypt the key file to make it less accessible from the file system.

There are two parts to an encryption key entry. First a 32-bit integer used as a key identifier, then the hex-encoded encryption key, separated by a semicolon. The File Key Management plugin supports 128-, 192- and 256-bit keys. You can generate keys using OpenSSL. For instance, to create a random 128-bit encryption key, you would run the following command:

$ openssl rand -hex 16

You can copy this key to file using a text editor, or you can append a series of keys to a new file.

# openssl rand -hex 16 >> /etc/mysql/keys
# openssl rand -hex 16 >> /etc/mysql/keys
# openssl rand -hex 16 >> /etc/mysql/keys

Once you have created this file, open it in your preferred text editor and add the key identifier to start of each line.

# Keys

The identifiers give you a way to reference the keys from MariaDB. In the example above, you can use 1, 2 or 3 as key identifiers with the ENCRYPTION_KEY_ID table option.

Encrypting the Key File

By enabling the File Key Management plugin and setting the appropriate path on the file_key_management_filename system variable, you can begin using the plugin to manage your encryption keys. But, there is a security risk in doing so, given that the keys are stored in plain text on your system. You can reduce this exposure using file permissions, but it's better to encrypt the whole key file to further restrict access.

You can encrypt the key file using OpenSSL.

# openssl enc -aes-256-cbc -md sha1 -k your_passwd \
      -in /etc/mysql/keys -out /etc/mysql/keys.enc

Running this command reads the keys file created above and creates a new encrypted keys.enc, using the password given to the -k option. Once you've finished preparing your system, delete the plain text key file, as it's no longer necessary.

Configuring the File Key Management Plugin

With the files prepared, you can configure MariaDB to use the File Key Management plugin. You need to load the plugin in order to use it. At a minimum you only need to define the path to the key file for the file_key_management_filename system variable.

Update the configuration file to add the relevant system variables.

# vi /etc/my.cnf


# File Key Management
plugin_load_add = file_key_management
file_key_management_filename = /etc/mysql/keys.enc
file_key_management_filekey = FILE:/etc/mysql/.key
file_key_management_encryption_algorithm = aes_cbc

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

Encrypted Key File

In the event that you chose to also encrypt the key file, you need to provide the decryption key to the file_key_management_filekey system variable. You have two options with this variable.

- You can give it the password you used when you created the encrypted key.enc file with OpenSSL. - Using the FILE: prefix, you can give it the path to a file containing the password.

When encrypting your key file, it is best practice to store the password in a separate file. When the password is set on the variable, users can obtain it through the SHOW VARIABLES statement.

Encryption Algorithm

The File Key Management plugin supports two encryption algorithms: AES_CBC and AES_CTR. The recommended algorithm is CTR, but CTR is only available when MariaDB is built with recent versions of OpenSSL.

When set to ABS_CBC, MariaDB uses AES with 128-bit keys in the Cipher Block Chaining mode. When set to AES_CTR, MariaDB uses AES with 128-bit keys in the Counter mode for encrypting tablespace pages, (that is, with InnoDB, XtraDB and Aria), and uses AES in authenticated GCM mode for temporary files, (where the cipher text is allowed to be larger than the plain text).

eperi Gateway for Databases

The File Key Management plugin is intended as an example and a starting point for anyone developing an encryption plugin. It is not the most secure option, since it requires you to store your encryption keys on the same machine that's running MariaDB.

The eperi Gateway for Databases provides an alternative. With eperi, your keys are stored on a key server. You can, optionally, perform all encryption on the key server as well. This prevents an attacker with file system access from unauthorized reading of the database files.

It also provides the following benefits:

  • Key management outside the database
  • No keys on database server hard disk
  • Graphical user interface for configuration
  • Encryption and decryption outside the database, supporting HSM's for maximum security.

AWS Key Management Plugin

Amazon Web Services provides its own implementation of a key management plugin, which integrates with AWS Key Management Services (KMS) for at-rest encryption in MariaDB.

MariaDB Enterprise packages on operating systems where it can be built include the AWS Key Management plugin beginning in version 10.1.13 and in MSI, ZIP, RPM, DEB, and .tar.gz releases starting in MariaDB 10.2.6.

For more information, see AWS Key Management Encryption plugin.


Comments loading...