Warning: the instructions below generate version 1 certificates only. These work fine with servers and clients using OpenSSL, but fail if WolfSSL is used instead, as is the case for our Windows MSI packages and our binary tarballs for Linux. WolfSSL requires version 3 certificates instead when using TLS v1.2 or higher, and so won't work with certificates generated as shown here when using two-way TLS with explicit client certificates. Generating version 3 certificates requires a few more minor steps, we will upgrade the instructions below soon to include these. See also: MDEV-25701

In order to secure communications with the MariaDB Server using TLS, you need to create a private key and an X509 certificate for the server. You may also want to create additional private keys and X509 certificates for any clients that need to connect to the server with TLS. This guide covers how to create a private key and a self-signed X509 certificate with OpenSSL.

Certificate Creation

The OpenSSL library provides a command-line tool called , which can be used for performing various tasks with the library, such as generating private keys, creating X509 certificate requests, signing X509 certificates as a Certificate Authority (CA), and verifying X509 certificates.

Creating a Certificate Authority Private Key and Certificate

The Certificate Authority (CA) is typically an organization (such as ) that signs the X509 certificate and validates ownership of the domain. However, when you would like to use self-signed certificates, you need to create the private key and certificate for the CA yourself, and then you can use them to sign your own X509 certificates.

To start, generate a private key for the CA using the command. For example:

After that, you can use the private key to generate the X509 certificate for the CA using the command. For example:

The above commands create two files in the working directory: The ca-key.pem private key and the ca.pem X509 certificate are both are used by the CA to create self-signed X509 certificates below.

Creating a Private Key and a Self-signed Certificate

Once you have the CA's private key and X509 certificate, you can create the self-signed X509 certificates to use for the MariaDB Server, client, replication and other purposes.

To start, generate a private key and create a certificate request using the command. For example:

After that, process the key to remove the passphrase using the command. For example:

Lastly, using the certificate request and the CA's private key and X509 certificate, you can generate a self-signed X509 certificate from the certificate request using the command. For example:

This creates a server-cert.pem file, which is the self-signed X509 certificate.

Certificate Verification

Once you have created the CA's X509 certificate and a self-signed X509 certificate, you can verify that the X509 certificate was correctly generated using the command. For example:

You can add as many X509 certificates to check against the CA's X509 certificate as you want to verify. A value of OK indicates that you can use it was correctly generated and is ready for use with MariaDB.

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

Overview

MariaDB Server and MariaDB Community Server support data-in-transit encryption, which secures data transmitted over the network. The server and the clients encrypt data using the Transport Layer Security (TLS) protocol, which is a newer version of the Secure Socket Layer (SSL) protocol.

TLS must be manually enabled on the server.

Enabling TLS

1. Acquire an X509 certificate and a private key for the server. If it is a test or development server, then self-signed certificates and keys might be sufficient.

2. Determine which and you need to configure.

Mandatory system variables and options for TLS include:

Useful system variables and options for TLS include:

1. Choose a configuration file in which to configure your system variables and options. It is not recommended to make custom changes to one of the bundled configuration files. Instead, it is recommended to create a custom configuration file in one of the included directories. Configuration files in included directories are read in alphabetical order. If you want your custom configuration file to override the bundled configuration files, then it is a good idea to prefix the custom configuration file's name with a string that will be sorted last, such as z-.

• On RHEL, CentOS, Rocky Linux, and SLES, a good custom configuration file would be: /etc/my.cnf.d/z-custom-my.cnf

• On Debian and Ubuntu, a good custom configuration file would be: /etc/mysql/mariadb.conf.d/z-custom-my.cnf

1. Set your system variables and options in the configuration file. They need to be set in a group that will be read by , such as [mariadb] or [server]. For example:

1. Restart the server.

1. Connect to the server using :

1. Confirm that TLS is enabled by confirming that the have_ssl system variable is YES with the SHOW GLOBAL VARIABLES statement:

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

Overview

and MariaDB Community Server support data-in-transit encryption, which secures data transmitted over the network. The server and the clients encrypt data using the Transport Layer Security (TLS) protocol, which is a newer version of the Secure Socket Layer (SSL) protocol.

TLS must be manually enabled on the server.

When MariaDB Server is compiled with TLS and cryptography support, it is usually either statically linked with MariaDB's bundled TLS and cryptography library or dynamically linked with the system's library. MariaDB's bundled TLS library is either or , depending on the server version.

When a MariaDB client or client library is compiled with TLS and cryptography support, it is usually either statically linked with MariaDB's bundled TLS and cryptography library or dynamically linked with the system's TLS and cryptography library, which might be , , or .

Checking Dynamically vs. Statically Linked

Dynamically linking MariaDB to the system's TLS and cryptography library can often be beneficial, since this allows you to fix bugs in the system's TLS and cryptography library independently of MariaDB. For example, when information on the

Nearly everyone owns data of immense value: customer data, construction plans, recipes, product designs and other information. These data are stored in clear text on your storage media. Everyone with file system access is able to read and modify the data. If this data falls into the wrong hands (criminals or competitors) this may result in serious consequences.

With encryption you protect Data At Rest (see the Wikipedia article). That way, the database files are protected against unauthorized access.

When Does Encryption Help to Protect Your Data?

Encryption helps in case of threats against the database files:

• An attacker gains access to the system and copies the database files to avoid the MariaDB authorization check.

• MariaDB is operated by a service provider who should not gain access to the sensitive data.

When is Encryption No Help?

Encryption provides no additional protection against threats caused by authorized database users. Specifically, SQL injections aren’t prevented.

What to Encrypt?

All data that is not supposed to fall into possible attackers hands should be encrypted. Especially information, subject to strict data protection regulations, is to be protected by encryption (e.g. in the healthcare sector: patient records). Additionally, data being of interest for criminals should be protected. Data which should be encrypted are:

• Personal related information

• Customer details

• Financial and credit card data

• Public authorities' data

How to Handle Key Management?

There are currently three options for key management:

See for details.

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

OpenSSL 1.1.1 introduced support for TLSv1.3. TLSv1.3 is a major rewrite of the TLS protocol. Some even argued it should've been called TLSv2.0. One of the changes is that it introduces a new set of cipher suites that only work with TLSv1.3. Additionally, TLSv1.3 does not support cipher suites from previous TLS protocol versions.

This incompatible change had a non-obvious consequence. If a user had been explicitly specifying cipher suites to disable old and obsolete TLS protocol version, then that user may have also inadvertently prevented TLSv1.3 from working, unless the user remembered to add the TLSv1.3 cipher suites to their cipher list. After upgrading to OpenSSL 1.1.1, this user might believe they are using TLSv1.3, when their existing cipher suite configuration might be preventing it.

To avoid this problem, OpenSSL developers decided that TLSv1.3 cipher suites should not be affected by the normal cipher-selecting API. This means that ssl_cipher system variable has no effect on the TLSv1.3 cipher suites.

See this OpenSSL blog post and GitHub issue for more information.

See Also

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

As with other storage engines that support data-at-rest encryption, Aria relies on an Encryption Key Management plugin to handle its encryption keys. Where the support is available, Aria can use multiple keys.

Encryption Keys

MariaDB keeps track of each encryption key internally using a 32-bit integer, which serves as the key identifier. Unlike InnoDB, Aria does not support the ENCRYPTION_KEY_ID table option (for more information, see MDEV-18049), which allows the user to specify the encryption key to use. Instead, Aria defaults to specific encryption keys provided by the Encryption Key Management plugin.

• When working with user-created tables, Aria encrypts them to disk using the ID 1 key.

• When working with internal temporary tables written to disk, Aria encrypts them to disk using the ID 2 key, unless there is no ID 2 key, then it falls back on the ID 1 key.

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. However, Aria does not have a similar mechanism, which means that the tables remain encrypted with the older key version. 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.

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

The process involved in safely disabling data-at-rest encryption for your Aria tables is very similar to that of enabling encryption. To disable, you need to set the relevant system variables and then rebuild each table into an unencrypted state.

Don't remove the Encryption Key Management plugin from your configuration file until you have unencrypted all tables in your database. MariaDB cannot read encrypted tables without the relevant encryption key.

Disabling Encryption on User-created Tables

With tables that the user creates, you can disable encryption by setting the aria_encrypt_tables system variable to OFF. Once this is set, MariaDB no longer encrypts new tables created with the Aria storage engine.

SET GLOBAL aria_encrypt_tables = OFF;

Unlike , Aria does not currently use background encryption threads. Before removing the plugin from the configuration file, you first need to manually rebuild each table to an unencrypted state.

To find the encrypted tables, query the Information Schema, filtering the table for those that use the Aria storage engine and the PAGE .

Each table in the result-set was potentially written to disk in an encrypted state. Before removing the configuration for the encryption keys, you need to rebuild each of these to an unencrypted state. This can be done with an statement.

Once all of the Aria tables are rebuilt, they're safely unencrypted.

Disabling Encryption for Internal On-disk Temporary Tables

MariaDB routinely creates internal temporary tables. When these temporary tables are written to disk and the system variable is set to ON, MariaDB uses the Aria storage engine.

To decrypt these tables, set the to OFF. Once set, all internal temporary tables that are created from that point on are written unencrypted to disk.

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

In certain situations, you may need to turn off data-at-rest encryption in a standalone or single-node MariaDB Enterprise Server deployment. For instance, you might have originally enabled encryption using a key management plugin, but later determine that encryption is no longer necessary.

This page explains how to safely disable data-at-rest encryption on a single server. The steps assume that your server already contains encrypted tables or logs, and that your goal is to revert the system to an unencrypted state without losing any data.

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 aria_encrypt_tables and encrypt_tmp_disk_tables.

Users of data-at-rest encryption will also need to have a key management and encryption plugin configured. Some examples are File Key Management Plugin and AWS Key Management Plugin.

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 about that.

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

In order to enable data-at-rest encryption for tables using the storage engine, you first need to configure the server to use an plugin. Once this is done, you can enable encryption by setting the relevant system variables.

Encrypting User-created Tables

With tables that the user creates, you can enable encryption by setting the system variable to ON, then restart the Server. Once this is set, Aria automatically enables encryption on all tables you create after with the table option set to PAGE.

Currently, Aria does not support encryption on tables where the

If you have Aria tables encrypted, you must first decrypt them:

Repeat this for each Aria table that is encrypted.

• Ensure the server can currently read encrypted data Keep your key management/encryption plugin configured and loaded so MariaDB can read existing encrypted Aria tables. Don’t remove the plugin yet.

When data-at-rest encryption is enabled, InnoDB tables and tablespaces are transparently encrypted and decrypted by the storage engine. In some cases, administrators may need to decrypt an InnoDB table—for example, when migrating data to an environment where encryption is not required, or when disabling encryption to simplify configuration.

This page covers how to confirm that binlogs are encrypted, recommended approaches for getting decrypted output.

When binary log encryption is enabled, the server writes binlog files to disk in encrypted form. This ensures that anyone with direct access to the filesystem cannot read the contents.

The encryption keys are managed through a keyring or key-management plugin. Whenever the server itself needs to access a binlog—such as during replication, recovery, or when tools like mysqlbinlog connect to it—the server transparently decrypts the events using the appropriate active keys.

Since the keys are stored in a server-accessible keyring, the most reliable and secure method to access decrypted binlog data is to request it directly from the running server. In other words, instead of trying to decrypt raw encrypted files offline, you should allow the server to stream already-decrypted events to you.

MariaDB Server can encrypt the server's binary logs and relay logs. This ensures that your binary logs are only accessible through MariaDB.

Basic Configuration

Since , MariaDB can also encrypt binary logs (including relay logs). Encryption of binary logs is configured by the encrypt_binlog system variable.

Users of data-at-rest encryption will also need to have a key management and encryption plugin configured. Some examples are the File Key Management Plugin and AWS Key Management Plugin.

Encryption Keys

support . Each encryption key can be defined with a different 32-bit integer as a key identifier.

MariaDB uses the encryption key with ID 1 to encrypt .

Key Rotation

Some allow you to automatically rotate and version your encryption keys. If a plugin supports 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. However, the binary log does not have a similar mechanism, which means that existing binary logs remain encrypted with the older key version, but new binary logs will be encrypted with the new key version. 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.

Enabling Encryption

Encryption of binary logs can be enabled by following the process:

• First, stop the server.

• Then, set in the MariaDB configuration file.

• Then, start the server.

From that point forward, any new will be encrypted. To delete old unencrypted , you can use or .

Disabling Encryption

Encryption of can be disabled by following the process:

• First, stop the server.

• Then, set in the MariaDB configuration file.

• Then, start the server.

From that point forward, any new will be unencrypted. If you would like the server to continue to have access to old encrypted , then make sure to keep your loaded.

Understanding Binlog Encryption

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's 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 , it is completely supported to have different encryption keys on the master and slave. The master decrypts encrypted binary log events as it reads them from disk, and before its sends them to the slave, so the slave actually receives the unencrypted binary log events.

If you want to ensure that binary log events are encrypted as they are transmitted between the master and slave, then you will have to use .

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

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

Note, using the --read-from-remote-server option on versions of the mariadb-binlog utility that do not have the fix (<=, , ) can corrupt binlog positions when the binary log is encrypted.

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

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 rotating encryption keys, 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}

When data-at-rest encryption is enabled in MariaDB Enterprise Server, InnoDB can encrypt redo logs. If you later disable encryption or need to recover data from encrypted redo logs, you may need to decrypt the redo log files before MariaDB can process them.

1. Stop MariaDB Enterprise Server

2. Locate the redo log files By default, InnoDB redo log files are stored in the data directory, typically as:

   or in the #innodb_redo directory for MariaDB versions using the new redo log format.

3. Prepare configuration for decryption

   • Make sure innodb_redo_log_encrypt is set to ON (to ensure the redo logs are recognized as encrypted).

   • Ensure that the key management plugin (such as file_key_management or aws_key_management) is configured exactly as it was when the redo logs were created.

4. Start MariaDB with decryption enabled

   • Start the server normally. MariaDB will automatically attempt to decrypt redo logs at startup using the configured key management plugin.

   • If successful, the redo logs are decrypted on-the-fly and crash recovery proceeds.

5. Disable redo log encryption if no longer required After recovery or once you confirm that decrypted redo logs are no longer needed, you can disable redo log encryption in the configuration:

   Then restart the server. New redo logs will be created in plaintext.

Verification

You can verify the redo log encryption status with:

Example output:

MariaDB supports data-at-rest encryption for tables using the 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 to automatically have all new InnoDB tables automatically encrypted, or specify encrypt per table.

For encrypting data with the Aria storage engine, see .

Basic Configuration

Using data-at-rest encryption requires that you first configure an plugin, such as the or 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

MariaDB's 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

By default, MariaDB replicates data between primaries and replicas without encrypting it. This is generally acceptable when the primary and replica run are in networks where security is guaranteed through other means. However, in cases where the primary and replica exist on separate networks or they are in a high-risk network, the lack of encryption does introduce security concerns as a malicious actor could potentially eavesdrop on the traffic as it is sent over the network between them.

To mitigate this concern, MariaDB allows you to encrypt replicated data in transit between primaries and replicas using the Transport Layer Security (TLS) protocol. TLS was formerly known as Secure Socket Layer (SSL), but strictly speaking the SSL protocol is a predecessor to TLS and, that version of the protocol is now considered insecure. The documentation still uses the term SSL often and for compatibility reasons TLS-related server system and status variables still use the prefix ssl_, but internally, MariaDB only supports its secure successors.

In order to secure connections between the primary and replica, you need to ensure that both servers were compiled with TLS support. See to determine how to check whether a server was compiled with TLS support.

You also need an X509 certificate, a private key, and the Certificate Authority (CA) chain to verify the X509 certificate for the primary. If you want to use two-way TLS, then you will also an X509 certificate, a private key, and the Certificate Authority (CA) chain to verify the X509 certificate for the replica. If you want to use self-signed certificates that are created with OpenSSL, then see for information on how to create those.

Securing Replication Traffic

In order to secure replication traffic, you will need to ensure that TLS is enabled on the primary. If you want to use two-way TLS, then you will also need to ensure that TLS is enabled on the replica. See for information on how to do that.

For example, to set the TLS system variables for each server, add them to a relevant server in an on each server:

And then restart the server to make the changes persistent.

At this point, you can reconfigure the replicas to use TLS to encrypt replicated data in transit. There are two methods available to do this:

• Executing the statement to set the relevant TLS options.

• Setting TLS client options in an .

Executing CHANGE MASTER

TLS can be enabled on a replication replica by executing the statement. In order to do so, there are a number of options that you would need to set. The specific options that you would need to set would depend on whether you want one-way TLS or two-way TLS, and whether you want to verify the server certificate.

Enabling Two-Way TLS with CHANGE MASTER

Two-way TLS means that both the client and server provide a private key and an X509 certificate. It is called "two-way" TLS because both the client and server can be authenticated. In this case, the "client" is the replica. To configure two-way TLS, you would need to set the following options:

• You need to set the path to the server's certificate by setting the option.

• You need to set the path to the server's private key by setting the option.

• You need to set the path to the certificate authority (CA) chain that can verify the server's certificate by setting either the or the options.

• If you want , then you also need to set the option (enabled by default from

If the are currently running, you first need to stop them by executing the statement. For example:

Then, execute the statement to configure the replica to use TLS. For example:

At this point, you can start replication by executing the statement. For example:

The replica now uses TLS to encrypt data in transit as it replicates it from the primary.

Enabling One-Way TLS with CHANGE MASTER

Enabling One-Way TLS with CHANGE MASTER with Server Certificate Verification

One-way TLS means that only the server provides a private key and an X509 certificate. When TLS is used without a client certificate, it is called "one-way" TLS, because only the server can be authenticated, so authentication is only possible in one direction. However, encryption is still possible in both directions. means that the client verifies that the certificate belongs to the server. In this case, the "client" is the replica. This mode is enabled by default starting from . To configure one-way TLS in earlier versions, you would need to set the following options:

• You need to set the path to the certificate authority (CA) chain that can verify the server's certificate by setting either the or the options.

• You need to set the option.

• If you want to restrict the server to certain ciphers, then you also need to set the option.

If the are currently running, you first need to stop them by executing the statement. For example:

Then, execute the statement to configure the replica to use TLS. For example:

At this point, you can start replication by executing the statement. For example:

The replica now uses TLS to encrypt data in transit as it replicates it from the primary.

Enabling One-Way TLS with CHANGE MASTER without Server Certificate Verification

One-way TLS means that only the server provides a private key and an X509 certificate. When TLS is used without a client certificate, it is called "one-way" TLS, because only the server can be authenticated, so authentication is only possible in one direction. However, encryption is still possible in both directions. In this case, the "client" is the replica. To configure two-way TLS without server certificate verification, you would need to set the following options:

• You need to configure the replica to use TLS by setting the option.

• If you want to restrict the server to certain ciphers, then you also need to set the option.

• Starting from you need to disable the option.

If the are currently running, you first need to stop them by executing the statement. For example:

Then, execute the statement to configure the replica to use TLS. For example:

At this point, you can start replication by executing the statement. For example:

The replica now uses TLS to encrypt data in transit as it replicates it from the primary.

Setting TLS Client Options in an Option File

In cases where you don't mind restarting the server or you are setting the server up from scratch for the first time, you may find it more convenient to configure TLS options for replication through an . This is done the same way as it is for other clients. The specific options that you would need to set would depend on whether you want one-way TLS or two-way TLS, and whether you want to verify the server certificate. See for more information. For example, to enable two-way TLS with , then you could specify the following options in a relevant client in an :

Before you restart the server, you may also want to set the option in a server in an . This option prevents the from restarting automatically when the server starts. Instead, they will have to be restarted manually. After these changes have been made, you can restart the server. Once the server is back online, set the option by executing the statement. This will enable TLS. For example:

The certificate and keys will be read from the option file. At this point, you can start replication by executing the statement.

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

The process involved in safely disabling encryption for your InnoDB tables is a little more complicated than that of enabling encryption. Turning off the relevant system variables doesn't decrypt the tables. If you turn it off and remove the encryption key management plugin, it'll render the encrypted data inaccessible.

In order to safely disable encryption, you first need to decrypt the tablespaces and the Redo Log, then turn off the system variables. The specifics of this process depends on whether you are using automatic or manual encryption of the InnoDB tablespaces.

Disabling Encryption for Automatically Encrypted Tablespaces

When an InnoDB tablespace has the ENCRYPTED table option set to DEFAULT and the innodb_encrypt_tables system variable is set to ON or FORCE, the tablespace's encryption is automatically managed by the background encryption threads. When you want to disable encryption for these tablespaces, you must ensure that the background encryption threads decrypt the tablespaces before removing the encryption keys. Otherwise, the tablespace remains encrypted and becomes inaccessible once you've removed the keys.

To safely decrypt the tablespaces, first, set the system variable to OFF:

Next, set the system variable to a non-zero value:

Then, set the system variable to 1:

Once set, any InnoDB tablespaces that have the table option set to DEFAULT will be in the background by the InnoDB .

Decryption Status

You can of the decryption process using the table in the database.

This query shows the number of InnoDB tablespaces that currently using background encryption threads. Once the count reaches 0, then all of your InnoDB tablespaces are unencrypted. Be sure to also remove encryption on the and the storage engine before removing the encryption key management settings from your configuration file.

Disabling Encryption for Manually Encrypted Tablespaces

In the case of manually encrypted InnoDB tablespaces, (that is, those where the table option is set to YES), you must issue an statement to decrypt each tablespace before removing the encryption keys. Otherwise, the tablespace remains encrypted and becomes inaccessible without the keys.

First, query the Information Schema table to find the encrypted tables. This can be done with a WHERE clause filtering the CREATE_OPTIONS column.

For each table in the result-set, issue an statement, setting the table option to NO.

Once you have removed encryption from all the tables, your InnoDB deployment is unencrypted. Be sure to also remove encryption from the as well as and any other storage engines that support encryption before removing the encryption key management settings from your configuration file.

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.

Disabling Encryption for Temporary Tablespaces

The system variable controls the configuration of encryption for the . To disable it, remove the system variable from your server's , and then restart the server.

Disabling Encryption for the Redo Log

InnoDB uses the in crash recovery. By default, these events are written to file in an unencrypted state. In removing data-at-rest encryption for InnoDB, be sure to also disable encryption for the Redo Log before removing encryption key settings. Otherwise the Redo Log can become inaccessible without the encryption keys.

First, set the system variable to OFF in a server in an . Once this is done, restart the MariaDB Server. When the Server comes back online, it begins writing unencrypted data to the Redo Log.

After the server has been successfully restarted with encryption disabled, you may remove the that had been used. If you try to disable encryption for the Redo Log and remove the plugin in a single step, InnoDB will be unable to decrypt the log in order to remove the encryption.

See Also

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

Wrong Create Options

With InnoDB tables using encryption, there are several cases where a or statement can throw Error 1005, due to the InnoDB error 140, Wrong create options. For instance,

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

This error is known to occur in the following cases:

Overview

Having tables encrypted makes it almost impossible for someone to access or steal a hard disk and get access to the original data. This functionality is also known as Transparent Data Encryption (TDE).

Starting from 11.4 MariaDB, it encrypts the transmitted data between the server and clients by default unless the server and client run on the same host.

Before that the default behavior was to transmit the data unencrypted over the network introducing a security concerns as a malicious actor could potentially eavesdrop on the traffic as it is sent over the network between them.

The data in transit are encrypted (by default or if enabled manually) using the Transport Layer Security (TLS) protocol. TLS was formerly known as Secure Socket Layer (SSL), but strictly speaking the SSL protocol is a predecessor to TLS and, that version of the protocol is now considered insecure. The documentation still uses the term SSL often and for compatibility reasons TLS-related server system and status variables still use the prefix ssl_, but internally, MariaDB only supports its secure successors.

Enabling TLS

InnoDB uses plugins to support the use of multiple .

Encryption Keys

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

The default key is set using the 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

The Hashicorp Key Management Pugin is used to implement encryption using keys stored in the Hashicorp Vault KMS. For more information, see , and for how to install Vault, see , as well as .

The current version of this plugin implements the following features:

The system variables listed on this page relate to encrypting data during transfer between servers and clients using the Transport Layer Security (TLS) protocol. Often, the term Secure Sockets Layer (SSL) is used interchangeably with TLS, although strictly speaking the SSL protocol is the predecessor of TLS and is no longer considered secure.

For compatibility reasons, the TLS system variables in MariaDB still use the ssl_ prefix, but MariaDB only supports its more secure successors. For more information on SSL/TLS in MariaDB, see Secure Connections Overview.

Variables

have_openssl

• Description: This variable shows whether the server is linked with rather than MariaDB's bundled TLS library, which might be or .

  • I this system variable shows YES, the server is linked with OpenSSL.

  • See for more information about which libraries are used on which platforms.

have_ssl

• Description: This variable shows whether the server supports using to secure connections.

  • If the value is YES, then the server supports TLS, and TLS is enabled.

  • If the value is DISABLED, then the server supports TLS, but TLS is not enabled.

ssl_ca

• Description: Defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs) to use for . This system variable requires that you use the absolute path, not a relative path. This system variable implies the option.

  • See for more information.

• Command line: --ssl-ca=file_name

ssl_capath

• Description: Defines a path to a directory that contains one or more PEM files that should each contain one X509 certificate for a trusted Certificate Authority (CA) to use for . This system variable requires that you use the absolute path, not a relative path. The directory specified by this variable needs to be run through the command. This system variable implies the option.

  • See for more information.

• Command line: --ssl-capath=directory_name

ssl_cert

• Description: Defines a path to the X509 certificate file to use for . This system variable requires that you use the absolute path, not a relative path. This system variable implies the option.

• Command line: --ssl-cert=name

• Scope: Global

• Dynamic: No

ssl_cipher

• Description: List of permitted ciphers or cipher suites to use for . Besides cipher names, if MariaDB was compiled with OpenSSL, this variable could be set to "SSLv3" or "TLSv1.2" to allow all SSLv3 or all TLSv1.2 ciphers. Note that the TLSv1.3 ciphers cannot be excluded when using OpenSSL, even by using this system variable. See for details. This system variable implies the option.

• Command line: --ssl-cipher=name

• Scope: Global

ssl_crl

• Description: Defines a path to a PEM file that should contain one or more revoked X509 certificates to use for . This system variable requires that you use the absolute path, not a relative path.

  • See for more information.

  • This variable is only valid if the server was built with OpenSSL. If the server was built with or , then this variable is not supported. See for more information about which libraries are used on which platforms.

ssl_crlpath

• Description: Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for . This system variable requires that you use the absolute path, not a relative path. The directory specified by this variable needs to be run through the command.

  • See for more information.

  • This variable is only supported if the server was built with OpenSSL. If the server was built with or , then this variable is not supported. See for more information about which libraries are used on which platforms.

ssl_key

• Description: Defines a path to a private key file to use for . This system variable requires that you use the absolute path, not a relative path. This system variable implies the option.

• Command line: --ssl-key=name

• Scope: Global

• Dynamic: No

ssl_passphrase

• Description: SSL certificate key passphrase. Works similarly to the --passout/--passin openssl command-line parameters. The pass phrase value can be formatted as follows:

  • pass:password — Provide the actual password.

  • env:

tls_version

• Description: This system variable accepts a comma-separated list (with no whitespaces) of TLS protocol versions. A TLS protocol version will only be enabled if it is present in this list. All other TLS protocol versions will not be permitted.

  • See for more information.

• Command line: --tls-version=value

version_ssl_library

• Description: The version of the library that is being used. Note that the version returned by this system variable does not always necessarily correspond to the exact version of the OpenSSL package installed on the system. OpenSSL shared libraries tend to contain interfaces for multiple versions at once to allow for backward compatibility. Therefore, if the OpenSSL package installed on the system is newer than the OpenSSL version that the MariaDB server binary was built with, then the MariaDB server binary might use one of the interfaces for an older version.

  • See for more information.

• Scope: Global

See Also

• for a complete list of system variables and instructions on setting them.

_{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 plugin. Once this is done, you can enable encryption by setting the system variable to encrypt the InnoDB and tablespaces and setting the system variable to encrypt the InnoDB .

Setting these system variables enables the encryption feature for InnoDB tables on your server. To use the feature, you need to use the table option to set what encryption key you want to use and set the 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.

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., libcurl3-dev on Debian Jessie), the uuid

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.

4. You'll need to complete the AWS identity verification process.

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.

• aws_key_management_key_spec

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}

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 for details.

MariaDB's requires the use of a . 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 . Each encryption key uses a 32-bit integer as a key identifier. If the specific plugin supports , then encryption keys can also be rotated, which creates a new version of the encryption key.

The AWS Key Management plugin is a that uses the .

Overview