MariaDB starting with 10.1.3
- Which storage engines does MariaDB encryption support?
- Encryption key management
- file_key_management plugin
- eperi Gateway for Databases
- Encrypting data
- XtraDB and InnoDB
- Encryption of Aria tables
- Encryption of Aria temporary tables
- Encryption of temporary files
- Encryption of binary logs
- Encryption and compression
- See Also
Having tables encrypted makes it almost impossible for someone to access or steal a hard disk and get access to the original data. This assumes that encryption keys are stored on another system.
Using encryption has an overhead of roughly 3-5%.
Which storage engines does MariaDB encryption support?
MariaDB encryption is fully supported for the XtraDB and InnoDB
storage engines. Additionally, encryption is supported for the Aria storage
engine, but only for tables created with
ROW_FORMAT=PAGE (the default).
MariaDB allows the user to configure flexibly what to encrypt. In XtraDB or InnoDB, one can choose to encrypt:
- everything — all tablespaces (with all tables)
- individual tables
- everything, excluding individual tables
Additionally, one can choose to encrypt XtraDB/InnoDB log files (recommended).
These limitations exist in the data-at-rest encryption implementation in MariaDB 10.1:
- Only data and only at rest is encrypted. Metadata (for example
.frmfiles) and data sent to the client are not encrypted (but see Secure Connections).
- Only the MariaDB server knows how to decrypt the data, in particular
- The disk-based Galera gcache is not encrypted (MDEV-9639).
- The Audit plugin cannot create encrypted output. Send it to syslog and configure the protection there instead.
- File-based general query log and slow query log cannot be encrypted (MDEV-9639).
- The Aria log is not encrypted (MDEV-9639). This affects only non-temporary Aria tables though.
- The MariaDB error log is not encrypted. The error log can contain query text and data in some cases, including crashes, assertion failures, and cases where InnoDB/XtraDB write monitor output to the log to aid in debugging. It can be sent to syslog too, if needed.
Encryption key management
MariaDB encryption supports multiple encryption keys, they are identified by a key identifier — a 32-bit integer. To support automatic key rotation every key additionally might have different versions. XtraDB and InnoDB can automatically re-encrypt the data from an older to a newer version of the same key. But how different keys are stored and rotated depends on the key management solution that you choose.
Key management in MariaDB is provided by encryption plugins. MariaDB includes the file_key_management plugin that can also serve as an example and starting point on how to write encryption plugins.
The file_key_management plugin is an encryption plugin that reads encryption keys from a file. This plugin has the following configuration options:
file_key_management_filename: Where the file is located. This option is required, the plugin will not work without it.
file_key_management_filekey: An optional key to decrypt the key file. If the key starts with
FILE:the rest of the value is interpreted as a path to the file that contains the key. You will most likely want to use the form
FILE:/path/to/filekeyso that the actual filekey cannot be read by anyone via a SHOW command. Consequently, that file would need the proper permissions so that mysql can read it, but not unauthorized users.
file_key_management_encryption_algorithm: the encryption algorithm to use.
The key file contains encryption keys identifiers (32-bit numbers) and hex-encoded encryption keys, separated by a semicolon. 128, 192 or 256-bit keys are supported. You can generate a random 128-bit encryption key with
openssl rand 16 -hex
or even with
hexdump -v -n16 -e '1/1 "%02x"' < /dev/urandom
Here is an example key file entry:
# this is a comment 1;770A8A65DA156D24EE2A093277530142 18;F5502320F8429037B8DAEF761B189D12F5502320F8429037B8DAEF761B189D12
1 is the key identifier which can be used for table creation, it is followed by the encryption key, in hex. Comments start from the hash character.
Key identifiers can be specified per table, but the system XtraDB/InnoDB tablespace and log files always use the key number 1, so it must always exist. Key number 2 is optional, but if it exists, it will be used for temporary tables and temporary files.
This plugin does not support key rotation — all keys always have the version 1.
If the key file can not be read at server startup, for example if the file key is not present, the encryption will not work and encrypted tables will be unreadable.
The key file (from above) may be encrypted and the key to decrypt the file can be given
with the optional
To encrypt the key file use the The OpenSSL command line utility. For example:
openssl enc -aes-256-cbc -md sha1 -k secret -in keys.txt -out keys.enc
Note, that you must use
sha1 otherwise the plugin won't be able to decrypt the key file.
file_key_management_encryption_algorithm can be set to
AES_CTR is not always available (only if MariaDB was built with recent openSSL) but in case it is available, we recommend to use it. If set to
AES_CBC, the plugin will use AES with 128-bit keys in the CBC mode. If set to
AES_CTR, the plugin will use AES with the 128-bit keys in the CTR mode for encrypting tablespace pages (InnoDB, XtraDB, and Aria), and it will use AES in the authenticated GCM mode for temporary files (where the cyphertext is allowed to be larger than the plaintext).
Example usage in a my.cnf/my.ini file:
[mysqld] file_key_management_encryption_algorithm=aes_cbc file_key_management_filename = /home/mdb/keys.enc file_key_management_filekey = secret
eperi Gateway for Databases
eperi provides a key management and encryption solution for MariaDB.
The keys are stored at the key server and optionally all encryption is done on the key server as well. This prevents an attacker with file system access from unauthorized reading the database files (see Why Encrypt MariaDB Data?).
The eperi Gateway for Databases provides the following key benefits:
- Key management outside the database
- No keys on the databases server hard disk
- Graphical user interface for configuration
- Encryption and decryption outside the database, supporting HSMs for maximum security
To enable encryption you have to load an encryption plugin, for example a file_key_management plugin, and configure storage engines to use it. The latter is storage engine specific:
XtraDB and InnoDB
To fine-tune the encryption, you can use following variables:
|innodb-encrypt-tables||Enable encryption for tables|
|innodb-encrypt-log||Boolean||Enable encryption for log files|
|innodb-encryption-rotate-key-age||Positive integer||Re-encrypt in background all pages that were encrypted with a key at least that many versions old|
|innodb-encryption-rotation-iops||Positive integer||Use this many Input/Output operations per second for background key rotation|
|innodb-encryption-threads||Positive integer||Number of threads performing background key rotation and scrubbing|
Note, that generally you should not enable only
innodb-encrypt-tables while keeping
innodb-encrypt-log disabled. In this setup log files will contain your data unencrypted. The opposite case is fine, you may want to enable only
innodb-encrypt-tables, and activate encryption per table with the
Also it'a good idea to enable encryption for temporary tables (see below).
Example my.cnf/my.ini to enable XtraDB encryption:
[mysqld] plugin-load-add=file_key_management file-key-management file-key-management-filename = /mount/usb1/keys.txt innodb-encrypt-tables innodb-encrypt-log innodb-encryption-threads=4
Specifying which tables to encrypt
You can choose which tables to encrypt. This allows you to balance security with speed. In order to use these options, innodb_file_per_table must be set to ON (the default).
|YES or NO|
CREATE TABLE T (id int, value varchar(255)) ENCRYPTED=YES ENCRYPTION_KEY_ID=17;
This creates table
T which is encrypted with key 17.
ALTER TABLE T ENCRYPTED=YES ENCRYPTION_KEY_ID=18;
T to be encrypted with key 18. If it was encrypted before,
it's first decrypted and then re-encrypted.
ALTER TABLE T encrypted=NO;
Disables the encryption of table
T. If it was encrypted before, it's
If innodb_file_per_table is OFF, or the ENCRYPTION_KEY_ID is not found, these statements will fail with
errno: 140 "Wrong create options".
Related configuration variables:
|innodb_encrypt_tables||Whether to encrypt tables that don't have |
|innodb_default_encryption_key_id||Positive integer||The default value of the |
Encryption of Aria tables
Only tables created with
ROW_FORMAT=PAGE can be encrypted.
This is the default row format for Aria.
You can specify that all Aria tables of the above type are encrypted by specifying:
Encryption of Aria temporary tables
MariaDB uses Aria for on-disk temporary tables that don't fit into MEMORY tables.
To ensure that no one can access data stored in temporary tables created as part of query execution, you can encrypt the temporary data by specifying in your my.cnf/my.ini file:
This works by creating and using a random encryption key for every new temporary table.
Encryption of temporary files
MariaDB might create temporary files on disk. For example, temporary files are created for binary log transactional caches and for filesort.
Since MariaDB 10.1.5, these temporary files can also be encrypted if encrypt_tmp_files is set.
From MariaDB 10.1.27, MariaDB 10.2.9 and MariaDB 10.3.2, temporary files created by merge sort and row log are encrypted if innodb_encrypt_log is set to
1, regardless of whether the table encrypted or not, or whether encrypt_tmp_files is set or not.
Encryption of binary logs
Encryption and compression
Encryption and compression (a feature usable with FusionIO) can be used together. This works by first compressing the data and then encrypting it. In this case you save space and still have your data protected.
- Tablespace encryption was donated to the MariaDB project by Google.
- Per-table encryption and key identifier support was donated to the MariaDB project by eperi.
We are grateful to these companies for their support of MariaDB!