MariaDB supports data-at-rest encryption for tables using the InnoDB storage engines. When enabled, the server encrypts data when it writes it to and decrypts data when it reads it from the file system. You can configure InnoDB encryption to automatically have all new InnoDB tables automatically encrypted, or specify encrypt per table.

For encrypting data with the Aria storage engine, see Encrypting Data for Aria.

InnoDB Encryption and Decryption Behavior

When data-at-rest encryption is enabled for InnoDB, encryption and decryption occur at specific points during disk I/O operations.

When is InnoDB data encrypted?

When InnoDB pages are written to disk, they are automatically encrypted.

When is InnoDB data decrypted?

InnoDB pages are decrypted before they are read from disk and stored in the InnoDB buffer pool. A page remains decrypted in memory while it is in the buffer pool. As a result, decrypted memory pages may include data from rows, columns, or even tables that the current query does not directly access.

Basic Configuration

Using data-at-rest encryption requires that you first configure an Encryption Key Management plugin, such as the file_key_management or aws_key_management plugins. MariaDB uses this plugin to store, retrieve and manage the various keys it uses when encrypting data to and decrypting data from the file system.

Once you have the plugin configured, you need to set a few additional system variables to enable encryption on InnoDB tables, including innodb_encrypt_tables, innodb_encrypt_log, innodb_encryption_threads, innodb_encrypt_temporary_tables and innodb_encryption_rotate_key_age.

For more information on system variables for encryption and other features, see the InnoDB system variables page.

Creating Encrypted Tables

To create encrypted tables, specify the table options ENCRYPTED=YES and ENCRYPTION_KEY_ID= with a corresponding key id;

Finding Encrypted Tables

When using data-at-rest encryption with the InnoDB storage engine, it is not necessary that you encrypt every table in your database. You can check which tables are encrypted and which are not by querying the INNODB_TABLESPACES_ENCRYPTION table in the Information Schema. This table provides information on which tablespaces are encrypted, which encryption key each tablespace is encrypted with, and whether the background encryption threads are currently working on the tablespace. Since the system tablespace can also contain tables, it can be helpful to join the INNODB_TABLESPACES_ENCRYPTION table with the INNODB_SYS_TABLES table to find out the encryption status of each specific table, rather than each tablespace. For example:

Redo Logs

Using data-at-rest encryption with InnoDB, the innodb_encrypt_tables system variable only encrypts the InnoDB tablespaces. In order to also encrypt the InnoDB Redo Logs, you also need to set the innodb_encrypt_log system variable.

Where the encryption key management plugin supports key rotation, the InnoDB Redo Log can also rotate encryption keys. In previous releases, the Redo Log can only use the first encryption key.

See Also

• Data at Rest Encryption

• Encryption Key Management

• Information Schema INNODB_TABLESPACES_ENCRYPTION table

_{This page is licensed: CC BY-SA / Gnu FDL}

Wrong Create Options

With InnoDB tables using encryption, there are several cases where a CREATE TABLE or ALTER TABLE statement can throw Error 1005, due to the InnoDB error 140, Wrong create options:

CREATE TABLE `test`.`table1` ( `id` INT(4) PRIMARY KEY , `name` VARCHAR(50));
ERROR 1005 (HY000): Can't create table `test`.`table1` (errno: 140 "Wrong create options")

When this occurs, you can usually get more information about the cause of the error by following it with a SHOW WARNINGS statement.

This error is known to occur in the following cases:

• Encrypting a table by setting the ENCRYPTED table option to YES when the innodb_file_per_table is set to OFF.In this case, SHOW WARNINGS would return the following:

SHOW WARNINGS;
+---------+------+---------------------------------------------------------------------+
| Level   | Code | Message                                                             |
+---------+------+---------------------------------------------------------------------+
| Warning |  140 | InnoDB: ENCRYPTED requires innodb_file_per_table                    |
| Error   | 1005 | Can't create table `db1`.`tab3` (errno: 140 "Wrong create options") |
| Warning | 1030 | Got error 140 "Wrong create options" from storage engine InnoDB     |
+---------+------+---------------------------------------------------------------------+
3 rows in set (0.00 sec)

• Encrypting a table by setting the ENCRYPTED table option to YES, and the innodb_default_encryption_key_id system variable or the ENCRYPTION_KEY_ID table option refers to a non-existent key identifier. In this case, SHOW WARNINGS would return the following:

SHOW WARNINGS;
+---------+------+---------------------------------------------------------------------+
| Level   | Code | Message                                                             |
+---------+------+---------------------------------------------------------------------+
| Warning |  140 | InnoDB: ENCRYPTION_KEY_ID 500 not available                         |
| Error   | 1005 | Can't create table `db1`.`tab3` (errno: 140 "Wrong create options") |
| Warning | 1030 | Got error 140 "Wrong create options" from storage engine InnoDB     |
+---------+------+---------------------------------------------------------------------+
3 rows in set (0.00 sec)

• In some versions, this could happen while creating a table with the ENCRYPTED table option set to DEFAULT while the innodb_encrypt_tables system variable is set to OFF, and the innodb_default_encryption_key_id system variable or the ENCRYPTION_KEY_ID table option are not set to 1. In this case, SHOW WARNINGS would return the following:

SHOW WARNINGS;
+---------+------+---------------------------------------------------------------------+
| Level   | Code | Message                                                             |
+---------+------+---------------------------------------------------------------------+
| Warning |  140 | InnoDB: innodb_encrypt_tables=OFF only allows ENCRYPTION_KEY_ID=1   |
| Error   | 1005 | Can't create table `db1`.`tab3` (errno: 140 "Wrong create options") |
| Warning | 1030 | Got error 140 "Wrong create options" from storage engine InnoDB     |
+---------+------+---------------------------------------------------------------------+
3 rows in set (0.00 sec)

Creating a table with the ENCRYPTED table option set to DEFAULT while the innodb_encrypt_tables system variable is set to OFF, and the innodb_default_encryption_key_id system variable or the ENCRYPTION_KEY_ID table option are not set to 1 no longer fail, and it no longer throws a warning.

For more information, see MDEV-18601.

Setting Encryption Key ID For an Unencrypted Table

If you set the ENCRYPTION_KEY_ID table option for a table that is unencrypted because the innodb_encrypt_tables system variable is set to OFF and the ENCRYPTED table option set to DEFAULT, then this encryption key ID will be saved in the table's .frm file, but the encryption key will not be saved to the table's .ibd file.

As a side effect, with the current encryption design, if the innodb_encrypt_tables system variable is later set to ON, and InnoDB goes to encrypt the table, then the InnoDB background encryption threads will not read this encryption key ID from the .frm file. Instead, the threads may encrypt the table with the encryption key with ID 1, which is internally considered the default encryption key when no key is specified. For example:

SET GLOBAL innodb_encrypt_tables=OFF;

CREATE TABLE tab1 (
   id INT PRIMARY KEY,
   str VARCHAR(50)
) ENCRYPTION_KEY_ID=100;

SET GLOBAL innodb_encrypt_tables=ON;

SELECT NAME, ENCRYPTION_SCHEME, CURRENT_KEY_ID
FROM information_schema.INNODB_TABLESPACES_ENCRYPTION
WHERE NAME='db1/tab1';
+----------+-------------------+----------------+
| NAME     | ENCRYPTION_SCHEME | CURRENT_KEY_ID |
+----------+-------------------+----------------+
| db1/tab1 |                 1 |              1 |
+----------+-------------------+----------------+

A similar problem is that, if you set the ENCRYPTION_KEY_ID table option for a table that is unencrypted because the ENCRYPTED table option is set to NO, then this encryption key ID will be saved in the table's .frm file, but the encryption key will not be saved to the table's .ibd file.

Recent versions of MariaDB will throw warnings in the case where the ENCRYPTED table option is set to NO, but they will allow the operation to succeed. For example:

CREATE TABLE tab1 (
   id INT PRIMARY KEY,
   str VARCHAR(50)
) ENCRYPTED=NO ENCRYPTION_KEY_ID=100;
Query OK, 0 rows affected, 1 warning (0.01 sec)

SHOW WARNINGS;
+---------+------+--------------------------------------------------+
| Level   | Code | Message                                          |
+---------+------+--------------------------------------------------+
| Warning |  140 | InnoDB: ENCRYPTED=NO implies ENCRYPTION_KEY_ID=1 |
+---------+------+--------------------------------------------------+
1 row in set (0.00 sec)

However, in this case, if you change the ENCRYPTED table option to YES or DEFAULT with ALTER TABLE, then it will actually use the proper key. For example:

SET GLOBAL innodb_encrypt_tables=ON;

ALTER TABLE tab1 ENCRYPTED=DEFAULT;

SELECT NAME, ENCRYPTION_SCHEME, CURRENT_KEY_ID
FROM information_schema.INNODB_TABLESPACES_ENCRYPTION
WHERE NAME = 'db1/tab1';
+----------+-------------------+----------------+
| NAME     | ENCRYPTION_SCHEME | CURRENT_KEY_ID |
+----------+-------------------+----------------+
| db1/tab1 |                 1 |            100 |
+----------+-------------------+----------------+

For more information, see MDEV-17230, MDEV-18601, and MDEV-19086.

Tablespaces Created on MySQL 5.1.47 or Earlier

MariaDB's data-at-rest encryption implementation re-used previously unused fields in InnoDB's buffer pool pages to identify the encryption key version and the post-encryption checksum. Prior to MySQL 5.1.48, these unused fields were not initialized in memory due to performance concerns. These fields still had zero values most of the time, but since they were not explicitly initialized, that means that these fields could have occasionally had non-zero values that could have been written into InnoDB's tablespace files. If MariaDB were to encounter an unencrypted page from a tablespace file that was created on an early version of MySQL that also had non-zero values in these fields, then it would mistakenly think that the page was encrypted.

The fix for MDEV-12112 changed the way that MariaDB distinguishes between encrypted and unencrypted pages, so that it is less likely to mistake an unencrypted page for an encrypted page.

If innodb_checksum_algorithm is set to full_crc32 or strict_full_crc32, and if the table does not use ROW_FORMAT=COMPRESSED, then data files are guaranteed to be zero-initialized.

For more information, see MDEV-18097.

Spatial Indexes

Support for encrypting spatial indexes. To enable, set the innodb_checksum_algorithm to full_crc32 or to strict_full_crc32. Note that MariaDB only encrypts spatial indexes when the ROW_FORMAT table option is not set to COMPRESSED.

For more information, see MDEV-12026.

Managing CPU Usage During InnoDB Encryption Operations

When encryption threads are enabled for InnoDB tables, the system initiates background threads to encrypt existing tablespace pages. During this initial process, you may see significant spikes in CPU and I/O usage. This can occur due to:

• Periodic key rotation checks that trigger re‑encryption work.

• Large datasets being encrypted, especially if many tables are enabled at once.

• Clustered environments such as MariaDB Galera Cluster, where each node performs encryption operations independently.

CPU usage can increase under several conditions. Common contributing factors are included below.

Causes of CPU Spikes

CPU usage increases during table encryption due to the following factors:

• CPU usage spikes after enabling encryption: This is expected because InnoDB must begin encrypting existing tablespace pages in the background once encryption is turned on. The initial workload is heavy.

• Increased disk I/O activity: The process involves reading unencrypted pages, encrypting them, and writing them back as encrypted. This read–encrypt–write cycle generates both CPU load (for encryption) and disk I/O load (for page movement).

• Background threads encrypting tablespace pages: InnoDB background threads actively encrypt tablespace pages that were encrypted before encryption was enabled. If too many threads are active or configured aggressively, they compete for CPU resources, causing spikes.

• Performance degradation during initial encryption: The initial stage of encrypting large tablespaces is the most resource-intensive phase. Once completed, ongoing CPU usage stabilizes, but during the initial encryption, performance can degrade significantly.

This behavior is normal during the one‑time setup phase when InnoDB begins encrypting existing tablespace pages. However, the impact can be reduced through:

• Tuning system variables such as innodb_encryption_threads, innodb_encryption_rotation_iops, and innodb_encryption_rotate_key_age.

• Monitoring background encryption activity to check progress and identify bottlenecks.

• Phased rollout of encryption, enabling it for a subset of tables at a time rather than all tables at once. See the section.

Configuration Options

Monitor Background Encryption Activity

MariaDB performs encryption in background threads. This helps determine if CPU usage is due to ongoing table encryption or key rotation.

Before changing configuration, verify whether background encryption is currently running by executing the following command:

SHOW ENGINE INNODB STATUS

You can review the encryption activity output.

Additionally, you can check the essential encryption-related status variables, as detailed in InnoDB: Background Encryption Threads.

Disable Key Rotation Checks

The innodb_encryption_rotate_key_age system variable manages how often InnoDB checks tablespace pages to determine whether they need to be re‑encrypted with a new key.

Setting this variable to 0 disables automatic key rotation checks if you do not require periodic re-encryption of old pages:

SET GLOBAL innodb_encryption_rotate_key_age=0;

Once disabled, key rotation checks can significantly reduce CPU usage. See innodb_encryption_rotate_key_age.

Limit Background Encryption Threads

The innodb_encryption_threads system variable controls the number of background encryption threads.

Lowering this value can prevent CPU contention at the cost of slower encryption progress.

SET GLOBAL innodb_encryption_threads=2;

You can maintain the value based on available CPU capacity and workload requirements. See innodb_encryption_threads.

Reduce Encryption Rotation IOPS

The innodb_encryption_rotation_iops system variable defines the maximum number of I/O operations per second that InnoDB background threads can use for page encryption and key rotation tasks.

Effect of Lowering the Value:

• Reduces CPU usage: fewer encryption operations are performed per second, lowering the load on CPU resources.

• Lowers disk pressure: decreases the number of read/write operations, reducing contention on storage I/O.

SET GLOBAL innodb_encryption_rotation_iops=50;

Setting a lower value (e.g., 25 or 50) limits the threads, making them read and write data more slowly, reducing both I/O and the associated CPU overhead. See innodb_encryption_rotation_iops.

Operational Best Practices

In addition to configuration changes, you can also manage encryption more effectively by applying the following operational practices:

• Encrypt table in batches: Instead of enabling encryption for all tables at once, apply it in stages. This allow background encryption to complete for one set of tables and then proceed with more. With this approach, peak CPU and I/O load can be reduced.

• Galera Cluster setup considerations:

  • Encryption operations are performed independently on each node

  • Use an odd number of nodes (3, 5, 7) to maintain quorum and prevent split-brain scenarios. See for details.

See Also

• InnoDB Data-at-Rest Encryption

• InnoDB Background Encryption Threads

• InnoDB System Variables

• Galera Cluster

_{This page is licensed: CC BY-SA / Gnu FDL}

MariaDB can encrypt data in tables that use the Aria storage engine. This includes both user-created tables and internal on-disk temporary tables that use the Aria storage engine. This ensures that your Aria data is only accessible through MariaDB.

For encryption with the InnoDB and XtraDB storage engines, see Encrypting Data for InnoDB/XtraDB.

Basic Configuration

In order to enable encryption for tables using the Aria storage engine, there are a couple server system variables that you need to set and configure. Most users will want to set and .

Users of data-at-rest encryption will also need to have a configured. Some examples are and .

Determining Whether a Table is Encrypted

The has the that can be used to get information about which tables are encrypted. Aria does not currently have anything like that (see about that).

To determine whether an Aria table is encrypted, you currently have to search the data file for some plain text that you know is in the data.

For example, let's say that we have the following table:

Then, we could search the data file that belongs to db1.aria_tab for str1 using a command-line tool, such as :

If you can find the plain text of the string, then you know that the table is not encrypted.

Encryption and the Aria Log

Only Aria tables are currently encrypted. The is not yet encrypted. See .

_{This page is licensed: CC BY-SA / Gnu FDL}

Once all data and logs have been decrypted, you can safely remove key management plugins, if desired. For example, if using the file key management plugin:

# Comment out or remove the following lines 
plugin_load_add = file_key_management 
file_key_management_filename = /etc/mysql/encryption/keyfile

Restart the server after editing the configuration.

• Ensure that all tables no longer report encryption in CREATE_OPTIONS.

• Confirm that redo logs and binary logs are unencrypted by checking server variables and log headers.

• Confirm that no key management plugin is loaded:

MariaDB Data-at-Rest Encryption, also known as Transparent Data Encryption (TDE), protects your data by encrypting files directly on the storage media. This ensures that if physical disks or backup files are stolen, the data remains unreadable without the corresponding encryption keys.

Security Context

When Encryption Protects Your Data

• Physical Theft: Unauthorized access to hard drives or storage arrays.

• Backup Exposure: If database backups are intercepted or accessed by unauthorized parties.

• Service Provider Access: Preventing infrastructure administrators in cloud or managed environments from viewing sensitive data.

When Encryption is No Help

• Authorized Access: Users with valid SQL credentials will still see decrypted data; TDE does not replace a robust strategy.

• Application Vulnerabilities: TDE does not prevent SQL injection or application-level data breaches.

• Data-in-Transit: This feature only secures stored data. Use to secure data moving across the network.

Architecture and Lifecycle

MariaDB performs encryption at the I/O layer. This process is "transparent" because applications and queries do not need to be modified to interact with encrypted data.

Once a is configured, encryption occurs automatically whenever MariaDB writes pages to disk, and decryption occurs when data is read back into memory.

• Write Path: When MariaDB flushes data from the buffer pool to the disk, the data is encrypted.

• Read Path: When MariaDB reads data from the disk into memory, it is decrypted.

• Memory: Data stored in RAM (such as the buffer pool) remains in a decrypted state while in use.

Storage Engine Support

MariaDB provides flexible control over what is encrypted, though support and requirements vary by component:

• InnoDB: Fully supported. You can encrypt all tablespaces, individual tables, and the InnoDB redo log. For details, see .

• Aria: Supported only for tables created with ROW_FORMAT=PAGE (the default). For details, see .

• Binary Logs: MariaDB can encrypt binary logs and relay logs to protect the replication pipeline. See .

Limitations

The following elements are not encrypted by the MariaDB server:

• Metadata: Information in .frm files and the system data dictionary.

• Specific Logs: The MariaDB Error Log, General Query Log, and Slow Query Log.

• Aria Control Log: While Aria tables can be encrypted, the Aria storage engine log is not currently encrypted.

Key Management

Encryption requires a key management and encryption plugin. These plugins are responsible for managing the 32-bit integer key identifiers and performing the cryptographic operations. You must install and configure a before enabling encryption options for storage engines.

Enabling Data-at-Rest Encryption

Enabling data-at-rest encryption encompasses these steps:

1. Creating a key file.

2. Installing and enabling a .

3. Enabling encryption for Aria tables, InnoDB tables, or both.

4. Verifying encryption is turned on.

Disabling Data-at-Rest Encryption

If you determine that encryption is no longer necessary, you can revert the system to an unencrypted state.

Prerequisites

• Encryption Status: MariaDB Enterprise Server must currently have data-at-rest encryption enabled and active.

• Key Management Access: You must have the original key management plugin active and the correct keys loaded to facilitate the decryption of the data.

• Sufficient Disk Space: Ensure adequate free space is available to accommodate the rewritten, unencrypted data files.

TDE in Action: Real-World Behavior

Transparent Data Encryption (TDE) is designed to protect data "at rest" while remaining completely invisible to standard SQL operations. With encryption turned on, MariaDB applies encryption to all new tables automatically.

Automatic Encryption (InnoDB & Aria)

For the subsequent instructions, we use these tables. With encrytion turned on, note that they're encrypted without using any special syntax:

Verifying Encryption Status

Because InnoDB and Aria handle data differently, you use two different methods to verify their encryption status.

For InnoDB

Check the information_schema to see the tablespace encryption scheme. If it's set to 1, the table is encrypted.

For Aria

There's no built-in way to check the encryption status of Aria tables, but you can check the contents of their .MAD files (the Aria data files) with commands like cat:

If you see unintelligible output rather than something resembling data, the Aria table is encrypted.

Transparent Data Access

Whether the table is InnoDB or Aria, the encryption is transparent. Standard SQL statements work without modification, as the engine decrypts the data in memory (the Buffer Pool for InnoDB or Page Cache for Aria).

Manual Control: Disabling Encryption

If you need to exempt a specific table from the global encryption policy, use the ENCRYPTED attribute.

Decrypting the Tables

Decrypting tables is done with an ALTER TABLE statement. For InnoDB tables, you can do this while global InnoDB table encryption is turned on.

Reencrypting the Tables

To enable data-at-rest encryption for tables using the Aria storage engine, configure the server to use an Encryption Key Management plugin. Once this is done, you can enable encryption by setting the relevant system variables.

Encrypting User-Created Tables

For user-created tables, enable encryption by setting the aria_encrypt_tables system variable to ON, then restart the server:

[mariadb]
aria_encrypt_tables = ON

Alternatively, set the variable with an SQL statement. This doesn't require a server restart, but the setting is lost on server restart:

Once this is set, Aria enables encryption on all newly created tables.

Encrypting Existing Tables

In cases where you have existing Aria tables that you would like to encrypt, the process is a little more complicated. Unlike InnoDB, Aria does not utilize to automatically perform encryption changes (see about that). Therefore, to encrypt existing tables, you need to identify each table that needs to be encrypted, and then you need to manually rebuild each table.

First, set the aria_encrypt_tables system variable to encrypt new tables.

Identify Aria tables that have the ROW_FORMAT table option set to PAGE.

For each table in the result set, issue an ALTER TABLE statement to rebuild the table.

This statement causes Aria to rebuild the table using the ROW_FORMAT table option. Since you enabled encryption, Aria also encrypts the table in the process.

Encrypting Internal Temporary Tables on Disk

During the execution of queries, MariaDB routinely creates internal temporary tables. These internal temporary tables initially use the storage engine, which is entirely stored in memory. When the table size exceeds the allocation defined by the system variable, MariaDB writes the data to disk using another storage engine. If you have the set to ON, MariaDB uses Aria in writing the internal temporary tables to disk.

Encryption for internal temporary tables is handled separately from encryption for user-created tables. To enable encryption for these tables, set the system variable to ON. Once set, all internal temporary tables that are written to disk using Aria are automatically encrypted.

Manually Encrypting Tables

Currently, Aria does not support manually encrypting tables through the and table options. For more information, see .

In cases where you want to encrypt tables manually or set the specific encryption key, use .

_{This page is licensed: CC BY-SA / Gnu FDL}

MariaDB can encrypt binary logs and relay logs to ensure that data modifications stored on disk are only accessible through the database server.

Prerequisites

Binary log and relay log encryption requires a configured Key Management and Encryption Plugin (such as File Key Management or AWS KMS). MariaDB specifically uses encryption key ID 1 for binary logs.

Key management plugin encryption looks like this (depending on the plugin used, and on the operating system the plugin is installed on):

[mariadb]
# File Key Management
plugin_load_add = file_key_management
file_key_management_filename = /etc/mysql/encryption/keyfile.enc
file_key_management_filekey = FILE:/etc/mysql/encryption/keyfile.key
file_key_management_encryption_algorithm = AES_CTR

Enabling Encryption

Binary log encryption is controlled by the system variable.

From this point forward, all new binary logs are encrypted. To remove old, unencrypted logs, use or .

Key Rotation

If your key management plugin supports rotation (check ), the server can use new key versions for new binary logs. However, unlike InnoDB, binary logs do not have a background re-encryption mechanism. Existing binary log files remain encrypted with the key version used at the time of their creation.

Reading Encrypted Binary Logs

Because encrypted logs cannot be read directly by standard text editors, you must use the utility.

Method 1: Remote Decryption (Recommended)

The most secure method is to have the server stream the decrypted events. This avoids the need to distribute encryption keys to administrative workstations.

Method 2: Local Decryption

You can decrypt logs locally if the mariadb-binlog utility has access to the same key management plugin and key material used by the server.

Disabling Encryption

Disabling encryption stops the server from encrypting future logs. It does not decrypt existing files.

️Understanding Binlog Encryption

Behind the Scenes

When starting with binary log encryption, MariaDB Server logs a Format_descriptor_log_event and a START_ENCRYPTION_EVENT, then encrypts all subsequent events for the binary log.

Each event header and footer are created and processed to produce encrypted blocks. These encrypted blocks are produced before transactions are committed and before the events are flushed to the binary log. As such, they exist in an encrypted state in memory buffers and in the IO_CACHE files for user connections.

Effects of Data-at-Rest Encryption on Replication

When using encrypted binary logs with , you can have different encryption keys on the master and the replica. The master decrypts encrypted binary log events as it reads them from disk, and before its sends them to the replica, so the replica actually receives the unencrypted binary log events.

To ensure that binary log events are encrypted as they are transmitted between the master and replica, use .

Effects of Data-at-Rest Encryption on mariadb-binlog

does not have the ability to decrypt encrypted on its own (see ). In order to use mariadb-binlog with encrypted , use the command-line option, so that the server can decrypt the for mariadb-binlog.

InnoDB uses encryption key management plugins to support the use of multiple encryption keys.

Encryption Keys

Each encryption key has a 32-bit integer that serves as a key identifier.

The default key is set using the innodb_default_encryption_key_id system variable.

Encryption keys can also be specified with the table option for tables that use tablespaces.

InnoDB encrypts the using the encryption key with the ID 1.

InnoDB encrypts the using the encryption key with the ID 1.

Keys with Manually Encrypted Tablespaces

With tables that use enabled encryption, one way to set the specific encryption key for the table is to use the table option. For example:

If the table option is not set for a table that uses enabled encryption, then it will inherit the value from the system variable. For example:

Keys with Automatically Encrypted Tablespaces

With tables that use enabled encryption, one way to set the specific encryption key for the table is to use the system variable. For example:

InnoDB tables that are part of the tablespace can only be encrypted using the encryption key set by the system variable.

If the table is in a tablespace, and if is set to ON or FORCE, and if is set to a value greater than 0, then you can also set the specific encryption key for the table by using the table option. For example:

However, if is set to OFF or if is set to 0, then this will not work. See for more information.

Key Rotation

Some allow you to automatically rotate and version your encryption keys. If a plugin support key rotation, and if it rotates the encryption keys, then InnoDB's can re-encrypt InnoDB pages that use the old key version with the new key version.

You can set the maximum age for an encryption key using the system variable. When this variable is set to a non-zero value, background encryption threads constantly check pages to determine if any page is encrypted with a key version that's too old. When the key version is too old, any page encrypted with the older version of the key is automatically re-encrypted in the background to use a more current version of the key. Bear in mind, this constant checking can sometimes result in high CPU usage.

Key rotation for the InnoDB is only supported in and later. For more information, see .

In order for key rotation to work, both the backend key management service (KMS) and the corresponding have to support key rotation. See to determine which plugins currently support key rotation.

Disabling Background Key Rotation Operations

In the event that you encounter issues with background key encryption, you can disable it by setting the system variable to 0. You may find this useful when the constant key version checks lead to excessive CPU usage. It's also useful in cases where your encryption key management plugin does not support key rotation, (such as with the plugin). For more information, see .

There are, however, issues that can arise when the background key rotation is disabled.

Pending Encryption Operations

When updating the value on the system variable, InnoDB internally treats the subsequent to encrypt and decrypt tablespaces as background key rotations. See for more information.

You can check the status of background encryption operations by querying the table in the database.

See for some example queries.

For more information, see .

_{This page is licensed: CC BY-SA / Gnu FDL}

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.

Supported Key Management Plugins list

Choosing an Encryption Key Management Solution

How MariaDB manages encryption keys depends on which encryption key management solution you choose. Currently, MariaDB has three options:

File Key Management Plugin

The File Key Management plugin that ships with MariaDB is a basic key management and encryption plugin that reads keys from a plain-text file. It can also serve as an example and as a starting point when developing a key management plugin.

For more information, see .

Hashicorp Key Management Plugin

Integrates MariaDB encryption with Vault for secure key management.

For more information, refer to the .

AWS Key Management Plugin

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 depends on the , which uses the . The 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 the source.

For more information, see .

Using Multiple Encryption Keys

Key management and encryption plugins support using multiple encryption keys. Each encryption key can be defined with a different 32-bit integer as a key identifier.

The support for multiple keys opens up some potential use cases. For example, let's say that a hypothetical key management and encryption plugin is configured to provide two encryption keys. One encryption key might be intended for "low security" tables. It could use short keys, which might not be rotated, and data could be encrypted with a fast encryption algorithm. Another encryption key might be intended for "high security" tables. It could use long keys, which are rotated often, and data could be encrypted with a slower but more secure encryption algorithm. The user would specify the identifier of the key that they want to use for different tables, only using high-level security where it's needed.

There are two encryption key identifiers that have special meanings in MariaDB. An encryption key 1 is intended for encrypting system data, such as InnoDB redo logs, binary logs, and so on. It must always exist when is enabled. An encryption key 2 is intended for encrypting temporary data, such as temporary files and temporary tables. It is optional. If it doesn't exist, then MariaDB uses an encryption key 1 for these purposes instead.

When , the key that is used to encrypt tables .

When , the key that is used to encrypt tables .

Key Rotation

Encryption key rotation is optional in MariaDB Server. Key rotation is only supported if the backend key management service (KMS) supports key rotation and if the corresponding key management and encryption plugin for MariaDB also supports key rotation. When a key management and encryption plugin supports key rotation, users can opt to rotate one or more encryption keys, which creates a new version of each rotated encryption key.

Key rotation allows users to improve data security in the following ways:

• If the server is configured to automatically re-encrypt table data with the newer version of the encryption key after the key is rotated, then that prevents an encryption key from being used for long periods of time.

• If the server is configured to simultaneously encrypt table data with multiple versions of the encryption key after the key is rotated, then that prevents all data from being leaked if a single encryption key version is compromised.

The has that can .

The does .

Support for Key Rotation in Encryption Plugins

Encryption Plugins with Key Rotation Support

• The supports encryption key rotation, and the corresponding also supports encryption key rotation.

• HashiCorp Key Management Plugin: The HashiCorp Key Management Plugin integrates MariaDB with for centralized encryption key storage and lifecycle management environments.

Encryption Plugins without Key Rotation Support

• The does not support encryption key rotation because it does not use a backend key management service (KMS).

Encryption Plugin API

New key management and encryption plugins can be developed using the .

_{This page is licensed: CC BY-SA / Gnu FDL}

In order to enable data-at-rest encryption for tables using the InnoDB storage engines, you first need to configure the server to use an Encryption Key Management plugin. Once this is done, you can enable encryption by setting the innodb_encrypt_tables system variable to encrypt the InnoDB system and file tablespaces and setting the innodb_encrypt_log system variable to encrypt the InnoDB Redo Log.

Setting these system variables enables the encryption feature for InnoDB tables on your server. To use the feature, you need to use the ENCRYPTION_KEY_ID table option to set what encryption key you want to use and set the ENCRYPTED table option to enable encryption.

When encrypting any InnoDB tables, the best practice is also enable encryption for the Redo Log. If you have encrypted InnoDB tables and have not encrypted the Redo Log, data written to an encrypted table may be found unencrypted in the Redo Log.

Enabling Encryption for Automatically Encrypted Tablespaces

The system variable controls the configuration of automatic encryption of InnoDB tables. It has the following possible values:

When is set to ON, InnoDB tables are automatically encrypted by default. For example, the following statements create an encrypted table and confirm that it is encrypted:

When is set to ON, an unencrypted InnoDB table can be created by setting the table option to NO for the table. For example, the following statements create an unencrypted table and confirm that it is not encrypted:

When is set to FORCE, InnoDB tables are automatically encrypted by default, and unencrypted InnoDB tables can not be created. In this scenario, if you set the table option to NO for a table, then you will encounter an error. For example:

When is set to ON or FORCE, then you must ensure that is set to a non-zero value, so that InnoDB can perform any necessary encryption operations in the background. See for more information about that. must also be set to a non-zero value for the initial encryption operations to happen in the background. See for more information about that.

Enabling Encryption for Manually Encrypted Tablespaces

If you do not want to automatically encrypt every InnoDB table, then it is possible to manually enable encryption for just the subset of InnoDB tables that you would like to encrypt. MariaDB provides the and table options that can be used to manually enable encryption for specific InnoDB tables. These table options can be used with and statements. These table options can only be used with InnoDB tables that have their own , meaning that tables that were created with set.

You can manually enable or disable encryption for a table by using the table option. If you only need to protect a subset of InnoDB tables with encryption, then it can be a good idea to manually encrypt each table that needs the extra protection, rather than encrypting all InnoDB tables globally with . This allows you to balance security with speed, as it means the encryption and decryption performance overhead only applies to those tables that require the additional security.

If a manually encrypted InnoDB table contains a , then the internal table for the full-text index will not also be manually encrypted. To encrypt internal tables for InnoDB full-text indexes, you must by setting to ON or FORCE.

You can also manually specify a for a table by using the table option. This allows you to use different encryption keys for different tables. For example, you might create a table using a statement like this:

If the table option is not specified, then the table will be encrypted with the key identified by the system variable. For example, you might create a table using a statement like this:

In the event that you have an existing table and you want to manually enable encryption for that table, then you can do the same with an statement. For example:

InnoDB does not permit manual encryption changes to tables in the tablespace using . Encryption of the tablespace can only be configured by setting the value of the system variable. This means that when you want to encrypt or decrypt the tablespace, you must also set a non-zero value for the system variable, and you must also set the system variable to 1 to ensure that the system tablespace is properly encrypted or decrypted by the background threads. See for more information.

Enabling Encryption for Temporary Tablespaces

The system variable controls the configuration of encryption for the . It has the following possible values:

This system variable can be specified as a command-line argument to or it can be specified in a relevant server in an . For example:

Enabling Encryption for the Redo Log

InnoDB uses the in crash recovery. By default, these events are written to file in an unencrypted state. In configuring MariaDB for data-at-rest encryption, ensure that you also enable encryption for the Redo Log.

To encrypt the Redo Log, first the server process. Then, set the to ON in a relevant server in an . For example:

Then, start MariaDB. When the server starts back up, it checks to recover InnoDB in the event of a crash. Once it is back online, it begins writing encrypted data to the Redo Log.

Key rotation for the Redo Log is supported. See for more information.

See Also

_{This page is licensed: CC BY-SA / Gnu FDL}

The Hashicorp Key Management Plugin is used to implement encryption using keys stored in the Hashicorp Vault KMS. For more information, see Hashicorp Vault and MariaDB, and for how to install Vault, see Install Vault, as well as MySQL/MariaDB Database Secrets Engine.

The current version of this plugin implements the following features:

• Authentication is done using Hashicorp Vault's token authentication method.

• If additional client authentication is required, then the path to the CA authentication bundle file may be passed as a plugin parameter;

• The creation of the keys and their management is carried out using the Hashicorp Vault KMS and its tools.

• The plugin uses libcurl (https) as an interface to the HashiCorp Vault server.

• JSON parsing is performed through the JSON service (through the include/mysql/service_json.h).

• HashiCorp Vault 1.2.4 was used for development and testing.

• As of MariaDB 10.6.24, the plugin is configured to use cached keys for all communication errors, not just for timeouts. This ensures continuous operation when the Vault server is temporarily unreachable.

• As of MariaDB 10.6.24, the default setting for cache usage on error is ON.

Since we require support for key versioning, the key-value storage must be configured in Hashicorp Vault as a key-value storage that uses the interface of the second version. For example, you can create it as follows:

Key names must correspond to their numerical identifiers. Key identifiers themselves, their possible values, and rules of use are described in more detail in the MariaDB main documentation.

From the point of view of the key-value storage (in terms of Hashicorp Vault), the key is a secret containing one key-value pair with the name "data" and a value representing a binary string containing the key value, for example:

Key values are strings containing binary data. MariaDB currently uses the AES algorithm with 256-bit keys as the default encryption method. In this case, the keys that will be stored in the Hashicorp Vault should be 32-byte strings. Most likely, you will use some utilities for creating and administering keys designed to work with Hashicorp Vault. But in the simplest case, keys can be created from the command line through the vault utility, for example, as follows:

If you use default encryption (AES), you should ensure that the key length is 32 bytes, as it may fail to use InnoDB as a data storage.

The plugin currently does not unseal Hashicorp Vault on its own; you must do this in advance and on your own.

To use Hashicorp Vault KMS, the plugin must be preloaded and activated on the server. Most of its parameters should not be changed during plugin operation and therefore must be preconfigured as part of the server configuration through configuration file or command line options:

Options

The plugin supports the following parameters, which must be set in advance and cannot be changed during server operation:

hashicorp-key-management-vault-url

• Description: HTTP[s] URL that is used to connect to the Hashicorp Vault server. It must include the name of the scheme (https:// for a secure connection) and, according to the API rules for storage of the key-value type in Hashicorp Vault, after the server address, the path must begin with the "/v1/" string (as prefix), for example: https://127.0.0.1:8200/v1/my_secrets. By default, the path is not set; therefore, you must replace it with the correct path to your secrets.

• Command line: --[loose-]hashicorp-key-management-vault-url="<url>"

hashicorp-key-management-token

• Description: An Authentication token that is passed to the Hashicorp Vault in the request header. By default, this parameter contains an empty string, so you must specify the correct value for it, otherwise the Hashicorp Vault server will refuse authorization. Alternatively, you can define an environment variable VAULT_TOKEN and store the token there.

• Command line: --[loose-]hashicorp-key-management-token="<token>"

hashicorp-key-management-vault-ca

• Description: Path to the Certificate Authority (CA) bundle (is a file that contains root and intermediate certificates). By default, this parameter contains an empty string, which means no CA bundle.

• Command line: --[loose-]hashicorp-key-management-vault-ca="<path>"

hashicorp-key-management-timeout

• Description: Set the duration (in seconds) for the Hashicorp Vault server connection timeout. The default value is 15 seconds. The allowed range is from 1 to 86400 seconds. The user can also specify a zero value, which means the default timeout value set by the libcurl library (currently 300 seconds).

• Command line: --[loose-]hashicorp-key-management-timeout=<timeout>

hashicorp-key-management-max-retries

• Description: Number of server request retries in case of timeout. Default is three retries.

• Command line: ----[loose-]hashicorp-key-management-max-retries=<retries>

hashicorp-key-management-caching-enabled

• Description: Enable key caching (storing key values received from the Hashicorp Vault server in the local memory). By default, caching is enabled.

• Command line: --[loose-]hashicorp-key-management-caching-enabled="on"|"off"

hashicorp-key-management-use-cache-on-timeout

• Description: This parameter instructs the plugin to use the key values or version numbers taken from the cache in the event of a timeout when accessing the vault server. By default, this option is disabled. Please note that key values or version numbers will be read from the cache when the timeout expires, only after the number of attempts to read them from the storage server that specified by the parameter has been exhausted.

• Command line: --[loose-]hashicorp-key-management-use-cache-on-timeout="on"|"off"

• Deprecated in MariaDB 10.11.16

hashicorp-key-management-cache-timeout

• Description: The time (in milliseconds) after which the value of the key stored in the cache becomes invalid and an attempt to read this data causes a new request to be sent to the vault server. By default, cache entries become invalid after 60,000 milliseconds (after one minute). If the value of this parameter is zero, then the keys will always be considered invalid, but they still can be used if the vault server is unavailable and the corresponding cache operating mode (--[loose-]hashicorp-key-management-use-cache-on-timeout="on") is enabled.

• As of MariaDB 10.6.24, the default value is 1 year (specified in milliseconds).

• Command line: --[loose-]hashicorp-key-management-cache-timeout=<timeout>

hashicorp-key-management-cache-version-timeout

• Description: The time (in milliseconds) after which the information about the latest version number of the key (which is stored in the cache) becomes invalid and an attempt to read this information causes a new request to be sent to the vault server. If the value of this parameter is zero, then information about the latest key version numbers is always considered invalid, unless there is no communication with the vault server, and use of the cache is allowed when the server is unavailable. By default, this parameter is zero, that is, the latest version numbers for the keys stored in the cache are considered always invalid, except when the vault server is unavailable and use of the cache is allowed on server failures.

• Command line: --[loose-]hashicorp-key-management-cache-version-timeout=<timeout>

hashicorp-key-management-check-kv-version

• Description: This parameter enables ("on", this is the default value) or disables ("off") checking the kv storage version during plugin initialization. The plugin requires storage version 2 or later in order for it to work properly.

• When this option is enabled, the configured Vault token must also have read access to the sys/mounts/my_vault/tune endpoint, allowing the plugin to determine the kv storage version. See for details.

• Command line: --[loose-]hashicorp-key-management-check-kv-version="on"|"off"

Required Vault Token Permissions

The token provided through hashicorp-key-management-token must have the following Vault access privileges.

Given a hashicorp-key-management-vault-url of , the token requires:

Note: During plugin initialization, the kv storage version is verified using the sys/mounts/my_vault/tune path. Most configurations require this permission because hashicorp-key-management-check-kv-version is set to on by default.

Example Minimal Vault Policy for Read-Only Access

The following example provides a minimal Vault policy that grants the required privileges:

Replace my_vault with the path segment of your hashicorp-key-management-vault-url configuration.

This ensures that the plugin does not require additional permissions to access encryption keys or verify the kv storage version.

Key Rotation and Cache Flushing

The HashiCorp Key Management plugin supports key versioning provided by the HashiCorp Vault Server. In previous versions, rotating keys required a server restart to clear the internal cache. As of MariaDB 12.3, you can flush the plugin cache manually while the server is running.

Flushing the Cache

To rotate keys, you must flush the cached keys using the FLUSH command. This clears the local cache, forcing the server to re-fetch the latest key versions from the HashiCorp Vault server upon the next access.

Executing this command requires the RELOAD privilege.

Verifying Key Versions

To view the current Key IDs and Key Versions stored in the latest version cache, you can query the Information Schema table or use the SHOW command.

See for table details.

Using the SHOW command:

See Also

_{This page is licensed: CC BY-SA / Gnu FDL}

Overview

MariaDB contains a robust, full instance, at-rest encryption. This feature uses a flexible plugin interface to allow actual encryption to be done using a key management approach that meets the customer's needs. MariaDB Server includes a plugin that uses the Amazon Web Services (AWS) Key Management Service (KMS) to facilitate separation of responsibilities and remote logging & auditing of key access requests.

Rather than storing the encryption key in a local file, this plugin keeps the master key in AWS KMS. When you first start MariaDB, the AWS KMS plugin will connect to the AWS Key Management Service and ask it to generate a new key. MariaDB will store that key on-disk in an encrypted form. The key stored on-disk cannot be used to decrypt the data; rather, on each startup, MariaDB connects to AWS KMS and has the service decrypt the locally-stored key(s). The decrypted key is stored in-memory as long as the MariaDB server process is running, and that in-memory decrypted key is used to encrypt the local data.

This guide is based on CentOS 7, using systemd with SELinux enabled. Some steps will differ if you use other operating systems or configurations.

Installing the Plugin's Package

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.

Installing from Source

When , the AWS Key Management plugin is built by default on systems that support it.

Compilation is controlled by the -DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC -DAWS_SDK_EXTERNAL_PROJECT=1 arguments.

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, or Visual Studio 2013 or later.

• On Unix, the libcurl development package (e.g.,

Installing the Plugin

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:

Sign up for Amazon Web Services

If you already have an AWS account, you can skip this section.

1. Load.

2. Click "Create a Free Account" and complete the steps.

3. You'll need to enter credit card information. Charges related only to your use of the AWS KMS service should be limited to about $1/month for the single master key we will create. If you use other services, additional charges may apply. Consult AWS Cloud Pricing Principles for more information about the pricing of AWS services.

Create an IAM User and/or Role

After creating an account or logging in to an existing account, follow these steps to create an IAM User or Role with restricted privileges that will use (but not administer) your master encryption key.

If you intend to run MariaDB Server on an EC2 instance, you should create a Role (or modify an existing Role already attached to your instance). If you intend to run MariaDB Server outside of AWS, you may want to create a User.

Creating an IAM Role

1. Load the Identity and Access Management Console at.

2. Click "Roles" in the left-hand sidebar

3. Click "Create new role"

4. Select "AWS Service Role"

Creating an IAM User

1. Load the Identity and Access Management Console at.

2. Click "Users" in the left-hand sidebar.

3. Click the "Create New Users" button

4. Enter a single User Name of your choosing. We'll use "MDBEnc" for this demonstration. Keep the "Generate an access key for each user" box checked.

1. Click "Close". If prompted because you did not Download Credentials, ensure that you've saved them somewhere, and click "Close".

Create a Master Encryption Key

Now, we'll create a master encryption key. This key can never be retrieved by any application or user. This key is used remotely to encrypt (and decrypt) the actual encryption keys that will be used by MariaDB. If this key is deleted or you lose access to it, you will be unable to use the contents of your MariaDB data directory.

1. Click "Encryption Keys" in the left-hand sidebar.

2. Click the "Get Started Now" button.

3. Use the "Filter" dropdown to choose the region where you'd like to create your master key.

4. Click the "Create Key" button.

You should now see your key listed in the console:

You'll use the "Alias" you provided when you configure MariaDB later.

We now have a Customer Master Key and an IAM user that has privileges to access it using access credentials. This is enough to begin using the AWS KMS plugin.

Configure AWS Credentials

There are a number of ways to give the IAM credentials to the AWS KMS plugin. The plugin supports reading credentials from all standard locations used across the various AWS API clients.

The easiest approach is to run MariaDB Server in an EC2 instance that has an IAM Role with User access to the CMK you wish to use. You can give key access privileges to a Role already attached to your EC2 instance, or you can create a new IAM Role and attach it to an already-running EC2 instance. If you've done that, no further credentials management is required, and you do not need to create a credentials file.

If you're not running MariaDB Server on an EC2 instance, you can also place the credentials in the MariaDB data directory. The AWS API client looks for a credentials file in the .aws subdirectory of the home directory of the user running the client process. In the case of MariaDB, its home directory is its datadir.

1. Create a credentials file that MariaDB can read. Use the region you selected when creating the key. Master keys cannot be used across regions. For example:

1. Change the permissions of the file so that it is owned by, and can only be read by, the mysql user:

Configure MariaDB

1. Create a new option file to tell MariaDB to enable encryption functionality and to use the AWS KMS plugin. Create a new file under /etc/my.cnf.d/ (or wherever your OS may have you create such files) with contents like this:

1. Append the "Alias" value you copied above to alias/ to use as the value for the aws-key-management-master-key-id option.

Note that you must include aws-key-management-region in your .cnf file if you are not using the us-east-1 region.

Now, you have told MariaDB to use the AWS KMS plugin, and you've put credentials for the plugin in a location where the plugin will find them. The /etc/my.cnf.d/enable_encryption.preset file contains a set of options that enable all available encryption functionality.

When you start MariaDB, the AWS KMS plugin will connect to the AWS Key Management Service and ask it to generate a new key. MariaDB will store that key on-disk in an encrypted form. The key stored on-disk cannot be used to decrypt the data; rather, on each startup, MariaDB must connect to AWS KMS and have the service decrypt the locally-stored key. The decrypted version is stored in-memory as long as the MariaDB server process is running, and that in-memory decrypted key is used to encrypt the local data.

SELinux and Outbound Connections from MariaDB

Because MariaDB needs to connect to the AWS KMS service, you must ensure that the host has outbound network connectivity over port 443 to AWS, and you must ensure that local policies allow the MariaDB server process to make those outbound connections. By default, SELinux restricts MariaDB from making such connections.

The most simple way to cause SELinux to allow outbound HTTPS connections from MariaDB is to enable to mysql_connect_any boolean, like this:

There are more complex alternatives that have a more granular effect, but those are beyond the scope of this document.

Start MariaDB

Start MariaDB using the systemctl tool:

If you do not use systemd, you may have to start MariaDB using some other mechanism.

You should see journal output similar to this:

Note the several lines of output that refer explicitly to the "AWS KMS plugin". You can see that the plugin generates a "datakey", loads that data key, and then later generates and loads a second data key. The 2nd data key is used to encrypt temporary files and temporary tables.

You can see the encrypted keys stored on-disk in the datadir:

Note that those keys are not useful alone. They are encrypted. When MariaDB starts up, the AWS KMS plugin decrypts those keys by interacting with AWS KMS.

For maximum security, you should start from an empty datadir and run after configuring encryption. Then you should re-import your data so that it is fully encrypted. Use sudo to run mariadb-install-db so that it finds your credentials file:

Create Encrypted Tables

With innodb-encrypt-tables=ON, new InnoDB tables will be encrypted by default, using the key ID set in innodb_default_encryption_key_id (default 1). With innodb-encrypt-tables=FORCE enabled, it is not possible to manually bypass encryption when creating a table.

You can cause the AWS KMS plugin to create new encryption keys at-will by specifying a new ENCRYPTION_KEY_ID when creating a table:

Read more about encrypting data in the section of the MariaDB Documentation.

AWS KMS Plugin Option Reference

• aws_key_management_master_key_id: AWS KMS Customer Master Key ID (ARN or alias prefixed by alias/) for master encryption key. Used to create new data keys. If not set, no new data keys will be created.

• aws_key_management_rotate_key: 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.

Next Steps

For more information about advanced usage, including strategies to manage credentials, enforce separation of responsibilities, and even require 2-factor authentication to start your MariaDB server, please review .

_{This page is licensed: CC BY-SA / Gnu FDL}

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

Overview

The File Key Management plugin is the for users who want to use . Some of the plugin's primary features are:

• It reads encryption keys from a plain-text key file.

• As an extra protection mechanism, the plain-text key file can be encrypted.

• It supports multiple encryption keys.

• It supports key rotation with MariaDB Enterprise Server from MariaDB Enterprise Server 11.8.

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 plug-in must be installed into MariaDB however as follows.

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

Uninstalling the Plugin

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.

Creating the Key File

In order to encrypt your tables with encryption keys using the File Key Management plugin, create the file containing the encryption keys. File name and location don't matter; see in the following what configuration is needed.

For each encryption key, the file contains these options, separated by a semicolon:

• The key identifier (format: 32-bit integer)

• The key version (optional, and only available as of Enterprise Server 11.8)

• The key itself (format: hex-encoded)

Entries look like this:

You can also optionally encrypt the key file to make it less accessible from the file system. That is explained further in the section below.

The File Key Management plugin uses to encrypt data. It supports 128-bit, 192-bit, and 256-bit encryption keys, just like the plugin does.

Generate random encryption keys using the command. To create a random 256-bit (32-byte) encryption key, run the following command:

The key file needs to have a key identifier for each encryption key added to the beginning of each line. Key identifiers do not have to be contiguous. For example, to append three new encryption keys to a new key file, issue these commands:

The resulting key file looks like this:

The key identifiers give you a way to reference the encryption keys from MariaDB. In the example above, you could reference these encryption keys using the key identifiers 1, 2 or 100 with the table option or with system variables such as . You do not necessarily need multiple encryption keys; an encryption key with the key identifier 1 is the only mandatory one.

If the key file is left unencrypted, the File Key Management plugin only requires the system variable to be configured.

This system variable can be specified as a command-line argument to mariadbd , or it can be specified in a server of an , like this:

Encrypting the Key File

If you use an unencrypted key file, keys are stored in plain text on your system, posing a security risk. It's recommended to encrypt the key file, with these hints in mind:

• MariaDB only supports the mode of .

• The encryption key size can be 128-bits, 192-bits, or 256-bits.

• The encryption key is created from the hash of the encryption password.

Generate a random encryption password using the command. To create a random 256 character encryption password, execute the following:

Encrypt the key file using the command. To encrypt the key file with the encryption password created in the previous step, execute for example one of the following commands:

The resulting keys.enc file is the encrypted version of keys.txt file. Delete the unencrypted key file.

Having the key file encrypted requires both the and the system variables to be configured.

The file_key_management_filekey variable can be provided in two forms:

• As a plain-text encryption password. This is not recommended, since the plain-text encryption password would be visible in the output of the statement.

• Prefixed with FILE:, it can be a path to a file that contains the plain-text encryption password.

These variables can be specified as command-line arguments to mariadbd, or they can be specified in a relevant server in an :

Choosing an Encryption Algorithm

The File Key Management plugin currently supports two encryption algorithms for encrypting data: AES_CBC and AES_CTR. Both of these algorithms use in different modes. AES uses 128-bit blocks, and supports 128-bit, 192-bit, and 256-bit keys. The modes are:

• The AES_CBC mode uses AES in the mode.

• The AES_CTR mode uses AES in two slightly different modes in different contexts. When encrypting tablespace pages (such as pages in InnoDB, XtraDB, and Aria tables), it uses AES in the mode. When encrypting temporary files (where the cipher text is allowed to be larger than the plain text), it uses AES in the authenticated .

The recommended algorithm is AES_CTR, but this algorithm is only available when MariaDB is built with . If the server is built with then this algorithm is not available. See for more information about which libraries are used on which platforms.

Configuring the Encryption Algorithm

The encryption algorithm can be configured by setting the system variable.

This system variable can be set to one of the following values:

This system variable can be specified as command-line arguments to mariadbd, or it can be specified in a relevant server in an . For example:

Note that the option prefix is specified. This option prefix is used in case the plugin hasn't been installed yet.

Note that this variable does not affect the algorithm that MariaDB uses to decrypt the key file. This variable only affects the encryption algorithm that MariaDB uses to encrypt and decrypt data. The only algorithm that MariaDB currently supports to encrypt the key file is mode of .

Using the File Key Management Plugin

Once the File Key Management Plugin is enabled, you can use it by creating an encrypted table:

Now, table t will be encrypted using the encryption key from the key file. For more information on how to use encryption, see .

The provides information about files stored in tablespaces, such as those used by the InnoDB storage engine.

Using Multiple Encryption Keys

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

When , the key that is used to encrypt tables . When , the key that is used to encrypt tables .

Key Rotation

Versions

System Variables

file_key_management_encryption_algorithm

• This system variable is used to determine which algorithm the plugin will use to encrypt data.

  • The recommended algorithm is AES_CTR, but this algorithm is only available when MariaDB is built with . If the server is built with then this algorithm is not available. See for more information about which libraries are used on which platforms.

• Command line: --file-key-management-encryption-algorithm=

file_key_management_digest

• Specifies the digest function to use in key derivation of the key used for decrypting the key file.

• Command line: --file-key-management-digest=value

• Scope: Global

file_key_management_filekey

• Used to determine the encryption password that is used to decrypt the key file defined by .

  • If this system variable's value is prefixed with FILE:, then it is interpreted as a path to a file that contains the plain-text encryption password.

  • If this system variable's value is not prefixed with FILE:, then it is interpreted as the plain-text encryption password. However, this is not recommended.

file_key_management_filename

• Used to determine the path to the file that contains the encryption keys. If is set, this file can be encrypted with mode of .

• Command line: --file-key-management-filename=value

• Scope: Global

file_key_management_use_pbkdf2

• Specifies whether pbkdf2 is used in key derivation, and if so, how many iterations.

• Command line: --file-key-management-use-pbkdf2=number

• Scope: Global

Options

file_key_management

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

This document assumes you've already set up an Amazon Web Services (AWS) account, created a master key in the Key Management Service (KMS), and have done the basic work to set up the MariaDB AWS KMS plugin. These steps are all described in .

Ultimately, keeping all the credentials required to read the key on a single host means that a user who has gained access to the host has enough information to read the encrypted files in the datadir, read the encrypted keys from the datadir, interact with AWS KMS to decrypt the encrypted keys, and then used the decrypted keys to decrypt the encrypted data.

Theoretically, a superuser can read the memory of the MariaDB server process to read the decrypted keys or restart MariaDB with password authentication disabled in order to dump data, or add new users to MariaDB in order to allow a user to connect and dump the data. Resolving these issues is beyond the scope of this document. A user who gains root access to your operating system or root access to your MariaDB server will have the ability to decrypt your data. Plan accordingly.

InnoDB performs some encryption and decryption operations with background encryption threads. The innodb_encryption_threads system variable controls the number of threads that the storage engine uses for encryption-related background operations, including encrypting and decrypting pages after key rotations or configuration changes, and scrubbing data to permanently delete it.

Background Operations

InnoDB performs the following encryption and decryption operations using background encryption threads:

• When , InnoDB's background encryption threads re-encrypt pages that use key versions older than to the new key version.

• When changing the system variable to FORCE, InnoDB's background encryption threads encrypt the tablespace and any tablespaces that have the table option set to DEFAULT.

• When changing the system variable to OFF, InnoDB's background encryption threads decrypt the tablespace and any tablespacs that have the ENCRYPTED table option set to DEFAULT.

The system variable can be used to configure how many I/O operations you want to allow for the operations performed by InnoDB's background encryption threads.

Whenever you change the value on the system variable, InnoDB's background encryption threads perform the necessary encryption or decryption operations. Because of this, you must have a non-zero value set for the system variable. InnoDB also considers these operations to be key rotations internally. Because of this, you must have a non-zero value set for the system variable. For more information, see .

Non-Background Operations

InnoDB performs the following encryption and decryption operations without using background encryption threads:

• When a tablespaces and using to manually set the table option to YES, InnoDB does not use background threads to encrypt the tablespaces.

• Similarly, when using file-per-table tablespaces and using to manually set the table option to NO, InnoDB does not use background threads to decrypt the tablespaces.

In these cases, InnoDB performs the encryption or decryption operation using the server thread for the client connection that executes the statement. This means that you can update encryption on tablespaces with an statement, even when the and/or the system variables are set to 0.

InnoDB does not permit manual encryption changes to tables in the tablespace using . Encryption of the tablespace can only be configured by setting the value of the system variable. This means that when you want to encrypt or decrypt the tablespace, you must also set a non-zero value for the system variable, and you must also set the system variable to 1 to ensure that the system tablespace is properly encrypted or decrypted by the background threads. See for more information.

Checking the Status of Background Operations

InnoDB records the status of background encryption operations in the table in the database.

For example, to see which InnoDB tablespaces are currently being decrypted or encrypted on by background encryption, you can check which InnoDB tablespaces have the ROTATING_OR_FLUSHING column set to 1:

And to see how many InnoDB tablespaces are currently being decrypted or encrypted by background encryption threads, you can call the aggregate function.

And to see how many InnoDB tablespaces are currently being decrypted or encrypted by background encryption threads, while comparing that to the total number of InnoDB tablespaces and the total number of encrypted InnoDB tablespaces, you can join the table with the table in the database:

_{This page is licensed: CC BY-SA / Gnu FDL}

Overview

Decryption for InnoDB is more complex than Aria because it involves background threads and the Redo Log.

This guide covers the process for safely decrypting InnoDB tablespaces, the system tablespace, and the Redo Log.

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.