File Key Management Encryption Plugin

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 File Key Management plugin that ships with MariaDB is a key management and encryption plugin that reads encryption keys from a plain-text file.

Overview

The File Key Management plugin is the easiest key management and encryption plugin to set up for users who want to use data-at-rest encryption. It reads encryption keys from a plain-text file. It supports two different encryption algorithms. It supports multiple encryption keys. It does not support key rotation.

It can also serve as an example and as a starting point when developing a key management and encryption plugin with the encryption plugin API.

Installing the File Key Management Plugin's Package

The File Key Management plugin is included in MariaDB packages as the file_key_management.so or file_key_management.dll shared library. The shared library is in the main server package, so no additional package installations are necessary. The plugin was first included in MariaDB 10.1.3.

Installing the Plugin

Although the plugin's shared library is distributed with MariaDB by default, the plugin is not actually installed by MariaDB by default. The plugin can be installed by providing the --plugin-load or the --plugin-load-add options. 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:

[mariadb]
...
plugin_load_add = file_key_management

Uninstalling the Plugin

Before you uninstall the plugin, you should ensure that data-at-rest encryption 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 UNINSTALL SONAME or UNINSTALL PLUGIN. For example:

UNINSTALL SONAME 'file_key_management';

If you installed the plugin by providing the --plugin-load or the --plugin-load-add options in a relevant server option group in an option file, then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.

Configuring the File Key Management Plugin

Creating the Key File

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
3b2bb95eba5a9f0045601f258491ef85

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
1;a3c93624f4968eb95056b6902de874ef
2;04e478eefe15b03c836282464b0e94a2
3;8c8ada2dfb4542b8e2673703f0364079

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 file, 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.

Enabling the File Key Management Plugin

To enable the File Key Management plugin, you also need to set the plugin's system variables. The file_key_management_filename system variable is the only required one. 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:

[mariadb]
...
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 key management and encryption plugin available for use.

Handling an Encrypted Key File

In the event that you chose to encrypt the key file, you will need to provide the decryption key via the file_key_management_filekey system variable. This system variable can be provided in two forms:

• 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 as the variable, other users can see it by inspecting the value of the variable with the SHOW VARIABLES statement.

Choosing an 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).

Using the File Key Management Plugin

Once the File 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 from the key file.

For more information on how to use encryption, see Data at Rest Encryption.

Using Multiple Encryption Keys

The File Key Management Plugin supports using multiple encryption keys. Each encryption key can be defined with a different 32-bit integer as a key identifier.

When encrypting InnoDB tables, the key that is used to encrypt tables can be changed.

When encrypting Aria tables, the key that is used to encrypt tables cannot currently be changed.

Rotating Keys

The File Key Management plugin does not currently support key rotation.

Versions

System Variables

file_key_management_encryption_algorithm

• Description: Defines the algorithm to use for encryption.
• Commandline: --file-key-management-encryption-algorithm=value
• Scope: Global
• Dynamic: No
• Data Type: enumerated
• Default Value: AES_CBC
• Valid Values: AES_CBC, AES_CTR

file_key_management_filekey

• 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)

file_key_management_filename

• 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)