Enhance MariaDB Server security with encryption. This section covers data-at-rest and in-transit encryption, helping you protect sensitive information and meet compliance requirements.
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 OpenSSL library. MariaDB's bundled TLS library is either wolfSSL or yaSSL, 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 OpenSSL, GnuTLS, or Schannel.
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 Heartbleed Bug in OpenSSL was released in 2014, the bug could be mitigated by simply updating your system to use a fixed version of the OpenSSL library, and then restarting the MariaDB Server.
You can verify that mysqld is in fact dynamically linked to the OpenSSL shared library on your system by using the ldd command:
$ ldd $(which mysqld) | grep -E '(libssl|libcrypto)'
libssl.so.10 => /lib64/libssl.so.10 (0x00007f8736386000)
libcrypto.so.10 => /lib64/libcrypto.so.10 (0x00007f8735f25000)If the command does not return any results, then either your mysqld is statically linked to the TLS and cryptography library on your system or your mysqld is not built with TLS and cryptography support at all.
If you aren't sure whether your server is linked with OpenSSL or the bundled TLS library, then you can check the value of the have_openssl system variable. For example:
SHOW GLOBAL VARIABLES LIKE 'have_openssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_openssl | YES |
+---------------+-------+If you want to see what version of OpenSSL your server is using, then you can check the value of the version_ssl_library system variable. For example:
SHOW GLOBAL VARIABLES LIKE 'version_ssl_library';
+---------------------+---------------------------------+
| Variable_name | Value |
+---------------------+---------------------------------+
| version_ssl_library | OpenSSL 1.0.1e-fips 11 Feb 2013 |
+---------------------+---------------------------------+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 MDEV-15848 for more information. For example:
$ cat /etc/redhat-release
Red Hat Enterprise Linux Server release 7.5 (Maipo)
$ rpm -q openssl
openssl-1.0.2k-12.el7.x86_64
$ mysql -u root --batch --execute="SHOW GLOBAL VARIABLES LIKE 'version_ssl_library';"
Variable_name Value
version_ssl_library OpenSSL 1.0.1e-fips 11 Feb 2013
$ ldd $(which mysqld) | grep libcrypto
libcrypto.so.10 => /lib64/libcrypto.so.10 (0x00007f3dd3482000)
$ readelf -a /lib64/libcrypto.so.10 | grep SSLeay_version
1374: 000000000006f5d0 21 FUNC GLOBAL DEFAULT 13 SSLeay_version@libcrypto.so.10
1375: 000000000006f5f0 21 FUNC GLOBAL DEFAULT 13 SSLeay_version@OPENSSL_1.0.1
1377: 000000000006f580 70 FUNC GLOBAL DEFAULT 13 SSLeay_version@@OPENSSL_1.0.2Federal Information Processing Standards (FIPS) are standards published by the U.S. federal government that are used to establish requirements for various aspects of computer systems. FIPS 140-2 is a set of standards for security requirements for cryptographic modules.
This standard is relevant when discussing the TLS and cryptography libraries used by MariaDB. Some of these libraries have been certified to meet the standards set by FIPS 140-2.
The OpenSSL library has a special FIPS mode that has been certified to meet the FIPS 140-2 standard. In FIPS mode, only algorithms and key sizes that meet the FIPS 140-2 standard are enabled by the library.
MariaDB does not yet support enabling FIPS mode within the database server. See MDEV-20260 for more information. Therefore, if you would like to use OpenSSL's FIPS mode with MariaDB, then you would either need to enable FIPS mode at the kernel level or enable it via the OpenSSL configuration file, system-wide or only for the MariaDB process.. See the following resources for more information on how to do that:
The standard version of the wolfSSL library has not been certified to meet the FIPS 140-2 standard, but a special "FIPS-ready" version has been certified. Unfortunately, the "FIPS-ready" version of wolfSSL uses a license that is incompatible with MariaDB's license, so it cannot be used with MariaDB.
The yaSSL library has not been certified to meet the FIPS 140-2 standard.
MariaDB Server is statically linked with the bundled wolfSSL library in MSI and ZIP packages on Windows.
MariaDB Server in Binary Tarballs
MariaDB Server is statically linked with the bundled wolfSSL library in binary tarballs on Linux.
MariaDB Server in DEB Packages
MariaDB Server is dynamically linked with the system's OpenSSL library in .deb packages.
See Differences in MariaDB in Debian (and Ubuntu) for more information.
MariaDB Server in RPM Packages
MariaDB Server is dynamically linked with the system's OpenSSL library in .rpm packages.
MariaDB Connector/C has been included with MariaDB Server, and the bundled and the clients and utilities are linked with it. On some platforms, MariaDB Connector/C and these clients and utilities may use a different TLS library than the one used by MariaDB Server and libmysqlclient.
MariaDB's clients and utilities and MariaDB Connector/C are dynamically linked with the system's Schannel libraries in MSI and ZIP packages on Windows. libmysqlclient is still statically linked with the bundled wolfSSL library. <>
MariaDB Clients and Utilities in Binary Tarballs
MariaDB's clients and utilities and MariaDB Connector/C are statically linked with the GnuTLS library in binary tarballs on Linux. libmysqlclient is still statically linked with the bundled wolfSSL library. <>
MariaDB Clients and Utilities in DEB Packages
MariaDB's clients and utilities, libmysqlclient, and MariaDB Connector/C are dynamically linked with the system's OpenSSL library in .deb packages.
See Differences in MariaDB in Debian (and Ubuntu) for more information.
MariaDB Clients and Utilities in RPM Packages
MariaDB's clients and utilities, libmysqlclient, and MariaDB Connector/C are dynamically linked with the system's OpenSSL library in .rpm packages.
When the MariaDB Server or clients and utilities are dynamically linked to the system's OpenSSL library, it makes it very easy to update the libraries. The information below will show how to update these libraries for each platform.
On RHEL, CentOS, Fedora, and other similar Linux distributions, it is highly recommended to update the libraries using yum or dnf. Starting with RHEL 8 and Fedora 22, yum has been replaced by dnf, which is the next major version of yum. However, yum commands still work on many systems that use dnf. For example:
Update the package by executing the following command:
sudo yum update opensslAnd then restart MariaDB server and any clients or applications that use the library.
On Debian, Ubuntu, and other similar Linux distributions, it is highly recommended to recommended to update the libraries using apt-get. For example:
First update the package cache by executing the following command:
sudo apt updateAnd then update the package by executing the following command:
sudo apt-get update opensslAnd then restart MariaDB server and any clients or applications that use the library.
On SLES, OpenSUSE, and other similar Linux distributions, it is highly recommended to recommended to update the libraries using zypper. For example:
Update the package by executing the following command:
sudo zypper update opensslAnd then restart MariaDB server and any clients or applications that use the library.
This page is licensed: CC BY-SA / Gnu FDL
Secure MariaDB Server data in transit with encryption. This section covers configuring SSL/TLS to protect communication between clients and the database, ensuring confidentiality and integrity.
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.
The OpenSSL library provides a command-line tool called openssl, 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.
The Certificate Authority (CA) is typically an organization (such as Let's Encrypt) 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 openssl genrsa command. For example:
# openssl genrsa 2048 > ca-key.pemAfter that, you can use the private key to generate the X509 certificate for the CA using the openssl req command. For example:
# openssl req -new -x509 -nodes -days 365000 \
-key ca-key.pem -out ca.pemThe 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.
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 openssl req command. For example:
# openssl req -newkey rsa:2048 -days 365000 \
-nodes -keyout server-key.pem -out server-req.pemAfter that, process the key to remove the passphrase using the openssl rsa command. For example:
# openssl rsa -in server-key.pem -out server-key.pemLastly, 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 openssl x509 command. For example:
# openssl x509 -req -in server-req.pem -days 365000 \
-CA ca.pem -CAkey ca-key.pem -set_serial 01 \
-out server-cert.pemThis creates a server-cert.pem file, which is the self-signed X509 certificate.
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 openssl verify command. For example:
# openssl verify -CAfile ca.pem server-cert.pem
server-cert.pem: OKYou 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
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.
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.
Determine which system variables and options you need to configure.
Mandatory system variables and options for TLS include:
Useful system variables and options for TLS include:
When this option is enabled, connections attempted using insecure transport will be rejected. Secure transports are SSL/TLS, Unix sockets, or named pipes.
CA directory
SSL cipher to use
CRL file in PEM format
CRL directory
TLS protocol version for secure connections.
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
Set your system variables and options in the configuration file. They need to be set in a group that will be read by MariaDB Server, such as [mariadb] or [server]. For example:
[mariadb]
...
ssl_cert = /certs/server-cert.pem
ssl_key = /certs/server-key.pem
ssl_ca = /certs/ca-cert.pemRestart the server.
$ sudo systemctl restart mariadbConnect to the server using MariaDB Client:
$ sudo mariadbConfirm that TLS is enabled by confirming that the have_ssl system variable is YES with the SHOW GLOBAL VARIABLES statement:
SHOW GLOBAL VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl | YES |
+---------------+-------+This page is: Copyright © 2025 MariaDB. All rights reserved.
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.
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.
Determine which system variables and options you need to configure. Mandatory system variables and options for TLS include:
When this option is enabled, connections attempted using insecure transport will be rejected. Secure transports are SSL/TLS, Unix sockets, or named pipes.
X509 cert in PEM format
X509 key in PEM format
JCA file in PEM format
Useful system variables and options for TLS include:
CA directory
SSL cipher to use
CRL file in PEM format
CRL directory
TLS protocol version for secure connections.
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
Set your system variables and options in the configuration file. They need to be set in a group that will be read by MariaDB Server, such as [mariadb] or [server]. For example:
[mariadb]
...
ssl_cert = /certs/server-cert.pem
ssl_key = /certs/server-key.pem
ssl_ca = /certs/ca-cert.pemRestart the server.
$ sudo systemctl restart mariadbConnect to the server using MariaDB Client:
$ sudo mariadbConfirm that TLS is enabled by confirming that the have_ssl system variable is YES with the SHOW GLOBAL VARIABLES statement:
SHOW GLOBAL VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl | YES |
+---------------+-------+This page is: Copyright © 2025 MariaDB. All rights reserved.
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 Secure Connections Overview 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 Certificate Creation with OpenSSL for information on how to create those.
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 Securing Connections for Client and Server for information on how to do that.
For example, to set the TLS system variables for each server, add them to a relevant server option group in an option file on each server:
[mariadb]
...
ssl_cert = /etc/my.cnf.d/certificates/server-cert.pem
ssl_key = /etc/my.cnf.d/certificates/server-key.pem
ssl_ca = /etc/my.cnf.d/certificates/ca.pemAnd 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 CHANGE MASTER statement to set the relevant TLS options.
Setting TLS client options in an option file.
TLS can be enabled on a replication replica by executing the CHANGE MASTER 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.
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 MASTER_SSL_CERT option.
You need to set the path to the server's private key by setting the MASTER_SSL_KEY option.
You need to set the path to the certificate authority (CA) chain that can verify the server's certificate by setting either the MASTER_SSL_CA or the MASTER_SSL_CAPATH options.
If you want server certificate verification, then you also need to set the MASTER_SSL_VERIFY_SERVER_CERT option (enabled by default from MariaDB 11.3).
If you want to restrict the server to certain ciphers, then you also need to set the MASTER_SSL_CIPHER option.
If the replica threads are currently running, you first need to stop them by executing the STOP SLAVE statement. For example:
STOP SLAVE;Then, execute the CHANGE MASTER statement to configure the replica to use TLS. For example:
CHANGE MASTER TO
MASTER_SSL_CERT = '/path/to/client-cert.pem',
MASTER_SSL_KEY = '/path/to/client-key.pem',
MASTER_SSL_CA = '/path/to/ca/ca.pem',
MASTER_SSL_VERIFY_SERVER_CERT=1;At this point, you can start replication by executing the START SLAVE statement. For example:
START SLAVE;The replica now uses TLS to encrypt data in transit as it replicates it from the primary.
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. Server certificate verification 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 MariaDB 11.3. 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 MASTER_SSL_CA or the MASTER_SSL_CAPATH options.
You need to set the MASTER_SSL_VERIFY_SERVER_CERT option.
If you want to restrict the server to certain ciphers, then you also need to set the MASTER_SSL_CIPHER option.
If the replica threads are currently running, you first need to stop them by executing the STOP SLAVE statement. For example:
STOP SLAVE;Then, execute the CHANGE MASTER statement to configure the replica to use TLS. For example:
CHANGE MASTER TO
MASTER_SSL_CA = '/path/to/ca/ca.pem',
MASTER_SSL_VERIFY_SERVER_CERT=1;At this point, you can start replication by executing the START SLAVE statement. For example:
START SLAVE;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 MASTER_SSL option.
If you want to restrict the server to certain ciphers, then you also need to set the MASTER_SSL_CIPHER option.
Starting from MariaDB 11.3 you need to disable the MASTER_SSL_VERIFY_SERVER_CERT option.
If the replica threads are currently running, you first need to stop them by executing the STOP SLAVE statement. For example:
STOP SLAVE;Then, execute the CHANGE MASTER statement to configure the replica to use TLS. For example:
CHANGE MASTER TO
MASTER_SSL=1, MASTER_SSL_VERIFY_SERVER_CERT=0;At this point, you can start replication by executing the START SLAVE statement. For example:
START SLAVE;The replica now uses TLS to encrypt data in transit as it replicates it from the primary.
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 option file. 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 Securing Connections for Client and Server: Enabling TLS for MariaDB Clients for more information. For example, to enable two-way TLS with server certificate verification, then you could specify the following options in a relevant client option group in an option file:
[client-mariadb]
...
ssl_cert = /etc/my.cnf.d/certificates/client-cert.pem
ssl_key = /etc/my.cnf.d/certificates/client-key.pem
ssl_ca = /etc/my.cnf.d/certificates/ca.pem
ssl-verify-server-certBefore you restart the server, you may also want to set the --skip-slave-start option in a server option group in an option file. This option prevents the replica threads 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 MASTER_SSL option by executing the CHANGE MASTER statement. This will enable TLS. For example:
CHANGE MASTER TO
MASTER_SSL=1;The certificate and keys will be read from the option file. At this point, you can start replication by executing the START SLAVE statement.
START SLAVE;This page is licensed: CC BY-SA / Gnu FDL
Prior to MariaDB 11.4, by default, MariaDB transmits data between the server and clients without encrypting it. This is generally acceptable when the server and client run on the same host or in networks where security is guaranteed through other means. However, in cases where the server and client 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 data in transit between the server and clients 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 for MariaDB Server to use TLS, it needs to be compiled with TLS support. All MariaDB packages distributed by MariaDB Foundation and MariaDB Corporation are compiled with TLS support.
If you aren't sure whether your MariaDB Server binary was compiled with TLS support, then you can check the value of the have_ssl system variable. For example:
SHOW GLOBAL VARIABLES LIKE 'have_ssl';
+---------------+----------+
| Variable_name | Value |
+---------------+----------+
| have_ssl | DISABLED |
+---------------+----------+The possible values are:
If it is DISABLED, then the server was compiled with TLS support, but TLS is not enabled.
If it is YES, then the server was compiled with TLS support, and TLS is enabled.
If it is NO, then the server was not compiled with TLS support.
When MariaDB is compiled with TLS and cryptography support, it is usually either statically linked with MariaDB's bundled TLS and cryptography library, which might be wolfSSL or yaSSL, or dynamically linked with the system's TLS and cryptography library, which might be OpenSSL, GnuTLS, or Schannel.
See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
There are 4 versions of the TLS protocol:
TLSv1.0
TLSv1.1
TLSv1.2
TLSv1.3
In some cases, it might make sense to only enable specific TLS protocol versions. For example, it would make sense if your organization has to comply with a specific security standard. It would also make sense if a vulnerability is found in a specific TLS protocol version, and you would like to ensure that your server does not use the vulnerable protocol version.
The PCI DSS v3.2 recommends using a minimum protocol version of TLSv1.2.
On the server side, users can enable specific TLS protocol versions by setting the tls_version system variable. This system variable accepts a comma-separated list 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. This system variable can be specified as a command-line argument to mariadbd or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
tls_version = TLSv1.2,TLSv1.3You can check which TLS protocol versions are enabled on a server by executing SHOW GLOBAL VARIABLES. For example:
SHOW GLOBAL VARIABLES LIKE 'tls_version';On the client side, users can enable specific TLS protocol versions by setting the --tls-version option. This option accepts a comma-separated list 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. For example, to specify this option in a relevant client option group in an option file, you could set the following:
[client-mariadb]
...
tls_version = TLSv1.2,TLSv1.3Or if you wanted to specify it on the command-line with the mariadb client, then you could execute something like this:
$ mariadb -u myuser -p -h myserver.mydomain.com \
--ssl \
--tls-version="TLSv1.2,TLSv1.3"The TLS protocol versions that are supported depend on the underlying TLS library used by the specific MariaDB binary.
openSSL
TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
wolfSSL
TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
yaSSL
TLSv1, TLSv1.1
Schannel
TLSv1, TLSv1.1, TLSv1.2
GnuTLS
TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used by the server and by clients on each platform.
MariaDB binaries built with the OpenSSL library (OpenSSL 1.0.1 or later) support TLSv1.1 and TLSv1.2 since MariaDB 5.5.41, MariaDB 10.0.15, and MariaDB 10.1.4.
MariaDB binaries built with the OpenSSL library (OpenSSL 1.1.1 or later) support TLSv1.3 since MariaDB 10.2.16 and MariaDB 10.3.8.
If your MariaDB Server binary is built with OpenSSL, then you can set the ssl_cipher system variable to values like SSLv3 or TLSv1.2 to allow all SSLv3.0 or all TLSv1.2 ciphers. However, this does not necessarily limit the protocol version to TLSv1.2. See MDEV-14101 for more information about that.
Note that the TLSv1.3 ciphers cannot be excluded when using OpenSSL, even by using the ssl_cipher system variable. See Using TLSv1.3 for details.
SSLv3.0 is known to be vulnerable to the POODLE attack, so it should not be used. SSLv2.0 and SSLv3.0 are disabled for MariaDB Server binaries linked with OpenSSL since MariaDB 5.5.41, MariaDB 10.0.15, and MariaDB 10.1.4. If you are using a MariaDB version older than that and you cannot upgrade, then please see the section titled "SSL 3.0 Fallback protection" in OpenSSL Security Advisory - 15 Oct 2014.
MariaDB binaries built with the bundled wolfSSL library support TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3.
MariaDB binaries built with the bundled yaSSL library support SSLv3.0, TLSv1.0, and TLSv1.1.
SSLv3.0 is known to be vulnerable to the POODLE attack, so it should not be used. SSLv2.0 and SSLv3.0 are disabled for MariaDB Server binaries linked with yaSSL since MariaDB 5.5.41, MariaDB 10.0.15, and MariaDB 10.1.4.
MariaDB binaries built with the Schannel library support different versions of TLS on different versions of Windows. See the Protocols in TLS/SSL (Schannel SSP) documentation from Microsoft to determine which versions of TLS are supported on each version of Windows.
MariaDB binaries built with the GnuTLS library support TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3.
See Securing Connections for Client and Server for information on how to enable TLS on the client and server.
Certificate verification is how TLS authenticates its connections by verifying that it is talking to who it says it is. There are multiple components to this verification process:
Was the certificate signed by a trusted Certificate Authority (CA)?
Is the certificate expired?
Is the certificate on my Certificate Revocation List (CRL)?
Does the certificate belong to who I believe that I'm communicating with?
Certificate Authorities (CAs) are entities that you trust to sign TLS certificates. Your organization might have its own internal CA, or it might use trusted third-party CAs.
CAs are specified on the server and client by using the ssl_ca and ssl_capath options.
The ssl_ca option defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs). This option requires that you use the absolute path, not a relative path.
The ssl_capath option 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). This option requires that you use the absolute path, not a relative path. The ssl_capath option is only supported if the server or client was built with OpenSSL, wolfSSL, or yaSSL. If the client was built with GnuTLS or Schannel, then the ssl_capath option is not supported.
See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
The directory specified by ssl_capath needs to be run through the openssl rehash command. For example, if the following is configured:
ssl_capath=/etc/my.cnf.d/certificates/ca/Then you would have to execute the following:
openssl rehash /etc/my.cnf.d/certificates/ca/The server can require a specific Certificate Authority (CA) for a client if the client's user account has been defined with REQUIRE ISSUER. See Securing Connections for Client and Server: Requiring TLS for more information.
Certificate Revocation Lists (CRLs) are lists of certificates that have been revoked by the Certificate Authority (CA) before they were due to expire.
CRLs are specified on the server and client by using the ssl_crl and ssl_crlpath options.
The ssl_crl option defines a path to a PEM file that should contain one or more X509 revoked certificates. This option requires that you use the absolute path, not a relative path. For servers, the ssl_crl option is only valid if the server was built with OpenSSL. If the server was built with wolfSSL or yaSSL, then the ssl_crl option is not supported. For clients, the ssl_crl option is only valid if the client was built with OpenSSL or Schannel. Likewise, if the client was built with GnuTLS, wolfSSL or yaSSL, then the ssl_crl option is not supported.
The ssl_crlpath option defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate. This option requires that you use the absolute path, not a relative path. The ssl_crlpath option is only supported if the server or client was built with OpenSSL. If the server was built with wolfSSL or yaSSL, then the ssl_crlpath option is not supported. Likewise, if the client was built with GnuTLS, Schannel, wolfSSL, or yaSSL, then the ssl_crlpath option is not supported.
See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
The directory specified by ssl_crlpath needs to be run through the openssl rehash command. For example, if the following is configured:
ssl_crlpath=/etc/my.cnf.d/certificates/crl/Then you would have to execute the following:
openssl rehash /etc/my.cnf.d/certificates/crl/Normally the TLS implementation performs numerous checks to verify whether the certificate is valid. It should be within its validity period, not revoked, signed by a trusted certificate authority, belong to the host that uses it.
Clients and utilities enable all these checks by default. Last two checks can be disabled with an option, such as disable-ssl-verify-server-cert. Before MariaDB 11.3, all server certificate verification checks were disabled by default, and could be enabled with the ssl-verify-server-cert option.
To verify whether the server's certificate belong to server's host, clients and utilities will check the Common Name (CN) attribute located in the Subject field of the certificate against the server's host name and IP address. If the Common Name (CN) matches either of those, then the certificate is verified.
The Subject Alternative Name (SAN) field, which is an X.509v3 extension, can also be used for server certificate verification, if it is present in the server certificate. This field is also sometimes called subjectAltName. When using a client or utility that supports server certificate verification with subjectAltName fields, if the server certificate contains any subjectAltName fields, then those fields will also be checked against the server's host name and IP address.
Whether server certificate verification with subjectAltName fields is supported depends on the underlying TLS library used by the client or utility.
See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
SAN Support with OpenSSL, wolfSSL, and yaSSL
For clients and utilities built with OpenSSL (OpenSSL 1.0.2 or later), support for server certificate verification with subjectAltName fields that contain the server's host name was added in MariaDB 10.1.23 and MariaDB 10.2.6. See MDEV-10594 for more information.
For clients and utilities built with OpenSSL (OpenSSL 1.0.2 or later), support for server certificate verification with subjectAltName fields that contain the server's IP address was added in MariaDB 10.1.39, MariaDB 10.2.24, MariaDB 10.3.15, and MariaDB 10.4.5. See MDEV-18131 for more information.
This support also applies to other TLS libraries that use OpenSSL's API. In OpenSSL's API, server certificate verification with subjectAltName fields depends on the X509_check_host and X509_check_ip functions. These functions are supported in the following TLS libraries:
OpenSSL 1.0.2 or later
And they are not supported in the following TLS libraries:
MariaDB's RPM packages were built with OpenSSL 1.0.1 on RHEL 7 and CentOS 7, even after OpenSSL 1.0.2 became available on those distributions. As a side effect, the clients and utilities bundled in these packages did not support server certificate verification with the subjectAltName field, even if the packages were installed on a system that had OpenSSL 1.0.2 installed. Starting with MariaDB MariaDB 10.1.39, MariaDB 10.2.23, MariaDB 10.3.14, and MariaDB 10.4.4, MariaDB's RPM packages on RHEL 7 and CentOS 7 are built with OpenSSL 1.0.2. See MDEV-18277 for more information.
SAN Support with Schannel
For clients and utilities linked with Schannel, support for server certificate verification with subjectAltName fields was added in MariaDB Connector/C 3.0.2. See CONC-250 for more information.
SAN Support with GnuTLS
For clients and utilities linked with GnuTLS, support for server certificate verification with subjectAltName fields was added in MariaDB Connector/C 3.0.0. See CONC-250 for more information.
The server verifies a client certificate by checking the client's known SUBJECT against the Subject attribute in the client's certificate. This is only done for user accounts that have been defined with REQUIRE SUBJECT. See Securing Connections for Client and Server: Requiring TLS for more information.
Mission Impossible: Zero-Configuration SSL (mariadb.org)
This page is licensed: CC BY-SA / Gnu FDL
Starting from 11.4 MariaDB 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.
MariaDB starting with 11.4
Starting from 11.4, MariaDB enables TLS automatically. Certificates are generated on startup and only stored in memory. Certificate verification is enabled by default on the client side and certificates are verified if the authentication plugin itself is MitM safe (mysql_native_password, ed25519, parsec). If you want to use externally generated certificates as with older MariaDB versions, see below.
MariaDB until 11.3
In order to enable TLS in a MariaDB server, you need to generate TLS certificates and configure the server to use them.
To do that there are a number of system variables that you need to set, such as:
You need to set the path to the server's X509 certificate by setting the ssl_cert system variable.
You need to set the path to the server's private key by setting the ssl_key system variable.
Unless you use a certificate which was signed by a trusted certificate authority (CA) you need to set the path to the certificate authority chain that can verify the server's certificate by setting either the ssl_ca or the ssl_capath system variables.
If you want to restrict the server to certain ciphers, then you also need to set the ssl_cipher system variable.
For example, to set these variables for the server, add the system variables to a relevant server option group in an option file:
[mariadb]
...
ssl_cert = /etc/my.cnf.d/certificates/server-cert.pem
ssl_key = /etc/my.cnf.d/certificates/server-key.pem
ssl_ca = /etc/my.cnf.d/certificates/ca.pemAnd then restart the server to make the changes persistent.
Once the server is back up, you can check that TLS is enabled by checking the value of the have_ssl system variable. For example:
SHOW VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl | YES |
+---------------+-------+The FLUSH SSL command can be used to dynamically reinitialize the server's TLS context.
See FLUSH SSL for more information.
Different clients and utilities may use different methods to enable TLS. You can let the client to use TLS without specifying client-side certificate — this is called a one-way TLS below — to have the connection encrypted. Or you can additionally provide client-side certificate — this is two-way TLS — which will allow the server to do the certificate based client authentication.
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 certificate based authentication is only possible in one direction. However, encryption is still possible in both directions. Server certificate verification means that the client verifies that the certificate belongs to the server.
MariaDB starting with 11.4
Starting from MariaDB 11.4 (Connector/C version 3.4) this mode is enabled by default. Connector/C will enable TLS automatically on all non-local connections and will require a verified server certificate to prevent man-in-the-middle attacks.
To enable one-way TLS manually (for older clients or if you want verification with CA certificate) you can specify these options in a relevant client option group in an option file:
[client-mariadb]
...
ssl_ca = /etc/my.cnf.d/certificates/ca.pem
ssl-verify-server-certOr if you wanted to specify them on the command-line with the mariadb client, then you could execute something like this:
$ mariadb -u myuser -p -h myserver.mydomain.com \
--ssl-ca=/etc/my.cnf.d/certificates/ca.pem \
--ssl-verify-server-certYou can disable server certificate verification with
[client-mariadb]
disable-ssl-verify-server-cert(or a similar command line option), but it creates a risk of a man-in-the-middle attack where the connection can be eavesdropped or manipulated even if it is being encrypted.
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.
For example, to specify these options in a relevant client option group in an option file, you could set the following:
[client-mariadb]
...
ssl_cert = /etc/my.cnf.d/certificates/client-cert.pem
ssl_key = /etc/my.cnf.d/certificates/client-key.pem
ssl_ca = /etc/my.cnf.d/certificates/ca.pem
ssl-verify-server-certOr if you wanted to specify them on the command-line with the mariadb client, then you could execute something like this:
$ mariadb -u myuser -p -h myserver.mydomain.com \
--ssl-cert=/etc/my.cnf.d/certificates/client-cert.pem \
--ssl-key=/etc/my.cnf.d/certificates/client-key.pem \
--ssl-ca=/etc/my.cnf.d/certificates/ca.pem \
--ssl-verify-server-certTwo-way SSL is required for an account if the REQUIRE X509, REQUIRE SUBJECT, and/or REQUIRE ISSUER clauses are specified for the account.
See the documentation on MariaDB Connector/C's TLS Options for information on how to enable TLS for clients that use MariaDB Connector/C.
See the documentation on MariaDB Connector/ODBC's TLS-Related Connection Parameters for information on how to enable TLS for clients that use MariaDB Connector/ODBC.
See the documentation on Using TLS/SSL with MariaDB Connector/J for information on how to enable TLS for clients that use MariaDB Connector/J.
You can verify that a connection is using TLS by checking the connection's Ssl_version status variable. It will either show the TLS version used, or be empty when no encryption is in effect. For example:
SHOW SESSION STATUS LIKE 'Ssl_version';
+---------------+---------------------------+
| Variable_name | Value |
+---------------+---------------------------+
| Ssl_version | TLSv1.3 |
+---------------+---------------------------+
1 row in set (0.00 sec)From MariaDB 10.5.2, the require_secure_transport system variable is available. When set (by default it is off), connections attempted using insecure transport will be rejected. Secure transports are SSL/TLS, Unix sockets or named pipes. Note that requirements set for specific user accounts will take precedence over this setting.
You can set certain TLS-related restrictions for specific user accounts. For instance, you might use this with user accounts that require access to sensitive data while sending it across networks that you do not control. These restrictions can be enabled for a user account with the CREATE USER, ALTER USER, or GRANT statements. For example:
A user account must connect via TLS if the user account is defined with the REQUIRE SSL clause.
ALTER USER 'alice'@'%'
REQUIRE SSL;A user account must connect via TLS with a specific cipher if the user account is defined with the REQUIRE CIPHER clause.
ALTER USER 'alice'@'%'
REQUIRE CIPHER 'ECDH-RSA-AES256-SHA384';A user account must connect via TLS with a valid client certificate if the user account is defined with the REQUIRE X509 clause.
ALTER USER 'alice'@'%'
REQUIRE X509;A user account must connect via TLS with a specific client certificate if the user account is defined with the REQUIRE SUBJECT clause.
ALTER USER 'alice'@'%'
REQUIRE SUBJECT '/CN=alice/O=My Dom, Inc./C=US/ST=Oregon/L=Portland';A user account must connect via TLS with a client certificate that must be signed by a specific certificate authority if the user account is defined with the REQUIRE ISSUER clause.
ALTER USER 'alice'@'%'
REQUIRE SUBJECT '/CN=alice/O=My Dom, Inc./C=US/ST=Oregon/L=Portland'
AND ISSUER '/C=FI/ST=Somewhere/L=City/ O=Some Company/CN=Peter Parker/emailAddress=p.parker@marvel.com';A user account can have different definitions depending on what host the user account is logging in from. Therefore, it is possible to have different TLS requirements for the same username for different hosts. For example:
CREATE USER 'alice'@'localhost'
REQUIRE NONE;
CREATE USER 'alice'@'%'
REQUIRE SUBJECT '/CN=alice/O=My Dom, Inc./C=US/ST=Oregon/L=Portland'
AND ISSUER '/C=FI/ST=Somewhere/L=City/ O=Some Company/CN=Peter Parker/emailAddress=p.parker@marvel.com'
AND CIPHER 'ECDHE-ECDSA-AES256-SHA384';In the above example, the alice user account does not require TLS when logging in from localhost. However, when the alice user account logs in from any other host, they must use TLS with the given cipher, and they must provide a valid client certificate with the given subject that must have been signed by the given issuer.
This page is licensed: CC BY-SA / Gnu FDL
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.
have_opensslDescription: This variable shows whether the server is linked with OpenSSL rather than MariaDB's bundled TLS library, which might be wolfSSL or yaSSL.
In MariaDB 10.0.1 and later, if this system variable shows YES, then the server is linked with OpenSSL.
In MariaDB 10.0.0 and before, this system variable was an alias for the have_ssl system variable.
See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
Scope: Global
Dynamic: No
have_sslDescription: This variable shows whether the server supports using TLS 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.
If the value is NO, then the server was not compiled with TLS support, so TLS cannot be enabled.
When TLS is supported, check the have_openssl system variable to determine whether the server is using OpenSSL or MariaDB's bundled TLS library. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
Scope: Global
Dynamic: No
ssl_caDescription: Defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs) to use for TLS. This system variable requires that you use the absolute path, not a relative path. This system variable implies the ssl option.
See Secure Connections Overview: Certificate Authorities (CAs) for more information.
Commandline: --ssl-ca=file_name
Scope: Global
Dynamic: No
Data Type: file name
ssl_capathDescription: 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 TLS. 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 openssl rehash command. This system variable implies the ssl option.
See Secure Connections Overview: Certificate Authorities (CAs) for more information.
Commandline: --ssl-capath=directory_name
Scope: Global
Dynamic: No
Data Type: directory name
ssl_certCommandline: --ssl-cert=name
Scope: Global
Dynamic: No
Data Type: file name
Default Value: None
ssl_cipherDescription: List of permitted ciphers or cipher suites to use for TLS. 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 Using TLSv1.3 for details. This system variable implies the ssl option.
Commandline: --ssl-cipher=name
Scope: Global
Dynamic: No
Data Type: string
Default Value: None
ssl_crlDescription: Defines a path to a PEM file that should contain one or more revoked X509 certificates to use for TLS. This system variable requires that you use the absolute path, not a relative path.
See Secure Connections Overview: Certificate Revocation Lists (CRLs) for more information.
This variable is only valid if the server was built with OpenSSL. If the server was built with wolfSSL or yaSSL, then this variable is not supported. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
Commandline: --ssl-crl=name
Scope: Global
Dynamic: No
Data Type: file name
Default Value: None
ssl_crlpathDescription: Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for TLS. 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 openssl rehash command.
See Secure Connections Overview: Certificate Revocation Lists (CRLs) for more information.
This variable is only supported if the server was built with OpenSSL. If the server was built with wolfSSL or yaSSL, then this variable is not supported. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
Commandline: --ssl-crlpath=name
Scope: Global
Dynamic: No
Data Type: directory name
Default Value: None
ssl_keyCommandline: --ssl-key=name
Scope: Global
Dynamic: No
Data Type: string
Default Value: None
tls_versionDescription: 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 Secure Connections Overview: TLS Protocol Versions for more information.
Commandline: --tls-version=value
Scope: Global
Dynamic: No
Data Type: enumerated
Default Value:
TLSv1.1,TLSv1.2,TLSv1.3 (<= MariaDB 10.4.31, MariaDB 10.5.22, MariaDB 10.6.15, MariaDB 10.11.5, MariaDB 11.0.3)
TLSv1.2,TLSv1.3 (>= MariaDB 10.4.32, MariaDB 10.5.23, MariaDB 10.6.16, MariaDB 10.11.6, MariaDB 11.0.4 and all later versions)
Valid Values: TLSv1.0,TLSv1.1,TLSv1.2,TLSv1.3
Introduced: MariaDB 10.4.6
version_ssl_libraryDescription: The version of the TLS 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 TLS and Cryptography Libraries Used by MariaDB: Checking the Server's OpenSSL Version for more information.
Scope: Global
Dynamic: No
Data Type: string
Default Value: None
System Variables for a complete list of system variables and instructions on setting them.
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.
This page is licensed: CC BY-SA / Gnu FDL
Secure MariaDB Server data at rest with encryption. This section details how to protect your sensitive information stored on disk, ensuring data confidentiality and compliance.
Having tables encrypted makes it almost impossible for someone to access or steal a hard disk and get access to the original data. MariaDB got Data-at-Rest Encryption with MariaDB 10.1. This functionality is also known as "Transparent Data Encryption (TDE)".
This assumes that encryption keys are stored on another system.
Using encryption has an overhead of roughly 3-5%.
MariaDB encryption is fully supported for the InnoDB storage engines. Encryption is also supported for the Aria storage engine, but only for tables created with ROW_FORMAT=PAGE (the default), and for the binary log (replication log).
MariaDB allows the user to configure flexibly what to encrypt. In or InnoDB, one can choose to encrypt:
everything — all tablespaces (with all tables) (with innodb_encrypt_tables=1)
individual tables
everything, excluding individual tables
Additionally, one can choose to encrypt InnoDB log files (recommended, with innodb_encrypt_log=1) and InnoDB Temporary Tables (with innodb_encrypt_temporary_tables=1).
When innodb_encrypt_log=1 or innodb_encrypt_temporary_tables=1 an encryption key of 1 must be defined. See Enabling InnoDB Encryption.
These limitations exist in the data-at-rest encryption implementation:
Only data and only at rest is encrypted. Metadata (for example .frm files) 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
mariadb-binlog can read encrypted binary logs only when --read-from-remote-server is used (MDEV-8813).
Percona XtraBackup cannot back up instances that use encrypted InnoDB. However, MariaDB's fork, MariaDB Backup, can back up encrypted instances.
The disk-based Galera gcache is not encrypted in the community version of MariaDB Server (MDEV-9639). However, this file is encrypted in MariaDB Enterprise Server 10.4.
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-8587). 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 write monitor output to the log to aid in debugging. It can sent to syslog too, if needed.
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.
How MariaDB manages encryption keys depends on which encryption key management solution you choose. Currently, MariaDB has four options:
Once you have an key management and encryption plugin set up and configured for your server, you can begin using encryption options to better secure your data.
Encryption occurs whenever MariaDB writes pages to disk. Encrypting table data requires that you install a key management and encryption plugin, such as the File Key Management plugin. Once you have a plugin set up and configured, you can enable encryption for your InnoDB and Aria tables.
MariaDB supports data-at-rest encryption for InnoDB and Aria storage engines. Additionally, it supports encrypting the InnoDB redo log and internal on-disk temporary tables that use the Aria storage engine..
MariaDB also creates temporary files on disk. For example, a binary log cache will be written to a temporary file if the binary log cache exceeds binlog_cache_size or binlog_stmt_cache_size, and temporary files are also often used for filesorts during query execution. Since MariaDB 10.1.5, these temporary files can also be encrypted if encrypt_tmp_files=ON is set.
Since MariaDB 10.1.27, MariaDB 10.2.9 and MariaDB 10.3.2, temporary files created internally by InnoDB, such as those used for merge sorts and row logs can also be encrypted if innodb_encrypt_log=ON is set. These files are encrypted regardless of whether the tables involved are encrypted or not, and regardless of whether encrypt_tmp_files is set or not.
MariaDB can also encrypt binary logs (including relay logs).
Data-at-rest encryption and InnoDB page compression can be used together. When they are used together, data is first compressed, and then it is encrypted. 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!
A blog post about table encryption with benchmark results
This page is licensed: CC BY-SA / Gnu FDL
MariaDB Server can encrypt the server's binary logs and relay logs. This ensures that your binary logs are only accessible through MariaDB.
Since MariaDB 10.1.7, 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 File Key Management Plugin and AWS Key Management Plugin.
[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
# Binary Log Encryption
encrypt_binlog=ONKey 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.
MariaDB uses the encryption key with ID 1 to encrypt binary logs.
Some key management and encryption plugins 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 background encryption threads 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 MDEV-20098.
In order for key rotation to work, both the backend key management service (KMS) and the corresponding key management and encryption plugin have to support key rotation. See Encryption Key Management: Support for Key Rotation in Encryption Plugins to determine which plugins currently support key rotation.
Encryption of binary logs can be enabled by doing the following process.
First, stop the server.
Then, set encrypt_binlog=ON in the MariaDB configuration file.
Then, start the server.
From that point forward, any new binary logs will be encrypted. To delete old unencrypted binary logs, you can use RESET MASTER or PURGE BINARY LOGS.
Encryption of binary logs can be disabled by doing the following process.
First, stop the server.
Then, set encrypt_binlog=OFF in the MariaDB configuration file.
Then, start the server.
From that point forward, any new binary logs will be unencrypted. If you would like the server to continue to have access to old encrypted binary logs, then make sure to keep your key management and encryption plugin loaded.
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.
When using encrypted binary logs with replication, 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 binary log dump thread 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 TLS with the replication connection.
mariadb-binlog does not currently have the ability to decrypt encrypted binary logs on its own (see MDEV-8813 about that). In order to use mariadb-binlog with encrypted binary logs, you have to use the --read-from-remote-server command-line option, so that the server can decrypt the binary logs for mariadb-binlog.
Note, using the --read-from-remote-server option on versions of the mariadb-binlog utility that do not have the MDEV-20574 fix (<=MariaDB 10.4.9, MariaDB 10.3.19, MariaDB 10.2.28) can corrupt binlog positions when the binary log is encrypted.
This page is licensed: CC BY-SA / Gnu FDL
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.
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.
Encryption provides no additional protection against threats caused by authorized database users. Specifically, SQL injections aren’t prevented.
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
Construction plans and research and development results
There are currently three options for key management:
See Encryption Key Management for details.
This page is licensed: CC BY-SA / Gnu FDL
Learn about Aria encryption in MariaDB Server for data at rest. This section details how to encrypt Aria tablespaces, providing enhanced security for your stored 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.
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.
[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
# Aria Encryption
aria_encrypt_tables=ON
encrypt_tmp_disk_tables=ONThe InnoDB storage engine has the information_schema.INNODB_TABLESPACES_ENCRYPTION table that can be used to get information about which tables are encrypted. Aria does not currently have anything like that (see MDEV-17324 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:
SELECT * FROM db1.aria_tab LIMIT 1;
+----+------+
| id | str |
+----+------+
| 1 | str1 |
+----+------+
1 row IN SET (0.00 secThen, we could search the data file that belongs to db1.aria_tab for str1 using a command-line tool, such as strings:
$ sudo strings /var/lib/mysql/db1/aria_tab.MAD | grep "str1"
str1If you can find the plain text of the string, then you know that the table is not encrypted.
Only Aria tables are currently encrypted. The Aria log is not yet encrypted. See MDEV-8587 about that.
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.
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 InnoDB, Aria does not currently use background encryption threads. Before removing the Encryption Key Management 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 TABLES table for those that use the Aria storage engine and the PAGE ROW_FORMAT.
SELECT TABLE_SCHEMA, TABLE_NAME
FROM information_schema.TABLES
WHERE ENGINE = 'Aria'
AND ROW_FORMAT = 'PAGE'
AND TABLE_SCHEMA != 'information_schema';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 ALTER TABLE statement.
ALTER TABLE test.aria_table ENGINE = Aria ROW_FORMAT = PAGE;Once all of the Aria tables are rebuilt, they're safely unencrypted.
MariaDB routinely creates internal temporary tables. When these temporary tables are written to disk and the aria_used_for_temp_tables system variable is set to ON, MariaDB uses the Aria storage engine.
To decrypt these tables, set the encrypt_tmp_disk_tables 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
In order to enable data-at-rest encryption for tables using the Aria storage engine, 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 relevant system variables.
With tables that the user creates, you can enable encryption by setting the aria_encrypt_tables system variable to ON, then restart the Server. Once this is set, Aria automatically enables encryption on all tables you create after with the ROW_FORMAT table option set to PAGE.
Currently, Aria does not support encryption on tables where the ROW_FORMAT table option is set to the FIXED or DYNAMIC values.
Unlike InnoDB, Aria does not support the ENCRYPTED table option (see MDEV-18049 about that). Encryption for Aria can only be enabled globally using the aria_encrypt_tables system variable.
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 background encryption threads to automatically perform encryption changes (see MDEV-18971 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.
SET GLOBAL aria_encrypt_tables=ON;Identify Aria tables that have the ROW_FORMAT table option set to PAGE.
SELECT TABLE_SCHEMA, TABLE_NAME
FROM information_schema.TABLES
WHERE ENGINE='Aria'
AND ROW_FORMAT='PAGE'
AND TABLE_SCHEMA != 'information_schema';For each table in the result-set, issue an ALTER TABLE statement to rebuild the table.
ALTER TABLE test.aria_table ENGINE=Aria ROW_FORMAT=PAGE;This statement causes Aria to rebuild the table using the ROW_FORMAT table option. In the process, with the new default setting, it encrypts the table when it writes to disk.
During the execution of queries, MariaDB routinely creates internal temporary tables. These internal temporary tables initially use the MEMORY storage engine, which is entirely stored in memory. When the table size exceeds the allocation defined by the max_heap_table_size system variable, MariaDB writes the data to disk using another storage engine. If you have the aria_used_for_temp_tables 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 encrypt_tmp_disk_tables system variable to ON. Once set, all internal temporary tables that are written to disk using Aria are automatically encrypted.
Currently, Aria does not support manually encrypting tables through the ENCRYPTED and ENCRYPTION_KEY_ID table options. For more information, see MDEV-18049.
In cases where you want to encrypt tables manually or set the specific encryption key, use InnoDB.
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.
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.
Some key management and encryption plugins 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 background encryption threads 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 MDEV-18971.
In order for key rotation to work, both the backend key management service (KMS) and the corresponding key management and encryption plugin have to support key rotation. See Encryption Key Management: Support for Key Rotation in Encryption Plugins to determine which plugins currently support key rotation.
This page is licensed: CC BY-SA / Gnu FDL
Learn about InnoDB encryption for data at rest. This section details how to encrypt InnoDB tablespaces, ensuring strong data security and compliance for your mission-critical applications.
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.
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.
[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
# InnoDB Encryption
innodb_encrypt_tables = ON
innodb_encrypt_temporary_tables = ON
innodb_encrypt_log = ON
innodb_encryption_threads = 4
innodb_encryption_rotate_key_age = 1For more information on system variables for encryption and other features, see the InnoDB system variables page.
To create encrypted tables, specify the table options ENCRYPTED=YES and ENCRYPTION_KEY_ID= with a corresponding key id;
CREATE TABLE t (i INT PRIMARY KEY) ENGINE=InnoDB ENCRYPTED=YES ENCRYPTION_KEY_ID=2;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:
SELECT st.SPACE, st.NAME, te.ENCRYPTION_SCHEME, te.ROTATING_OR_FLUSHING
FROM information_schema.INNODB_TABLESPACES_ENCRYPTION te
JOIN information_schema.INNODB_SYS_TABLES st
ON te.SPACE = st.SPACE \G
*************************** 1. row ***************************
SPACE: 0
NAME: SYS_DATAFILES
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 2. row ***************************
SPACE: 0
NAME: SYS_FOREIGN
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 3. row ***************************
SPACE: 0
NAME: SYS_FOREIGN_COLS
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 4. row ***************************
SPACE: 0
NAME: SYS_TABLESPACES
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 5. row ***************************
SPACE: 0
NAME: SYS_VIRTUAL
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 6. row ***************************
SPACE: 0
NAME: db1/default_encrypted_tab1
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 7. row ***************************
SPACE: 416
NAME: db1/default_encrypted_tab2
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 8. row ***************************
SPACE: 402
NAME: db1/tab
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 9. row ***************************
SPACE: 185
NAME: db1/tab1
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 10. row ***************************
SPACE: 184
NAME: db1/tab2
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 11. row ***************************
SPACE: 414
NAME: db1/testgb2
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 12. row ***************************
SPACE: 4
NAME: mysql/gtid_slave_pos
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 13. row ***************************
SPACE: 2
NAME: mysql/innodb_index_stats
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 14. row ***************************
SPACE: 1
NAME: mysql/innodb_table_stats
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
*************************** 15. row ***************************
SPACE: 3
NAME: mysql/transaction_registry
ENCRYPTION_SCHEME: 1
ROTATING_OR_FLUSHING: 0
15 rows in set (0.000 sec)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.
Beginning in MariaDB 10.4, 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.
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.
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 innodb_encrypt_tables system variable to OFF:
SET GLOBAL innodb_encrypt_tables = OFF;Next, set the innodb_encryption_threads system variable to a non-zero value:
SET GLOBAL innodb_encryption_threads = 4;Then, set the innodb_encryption_rotate_key_age system variable to 1:
SET GLOBAL innodb_encryption_rotate_key_age = 1;Once set, any InnoDB tablespaces that have the ENCRYPTED table option set to DEFAULT will be decrypted in the background by the InnoDB background encryption threads.
You can check the status of the decryption process using the INNODB_TABLESPACES_ENCRYPTION table in the information_schema database.
SELECT COUNT(*) AS "Number of Encrypted Tablespaces"
FROM information_schema.INNODB_TABLESPACES_ENCRYPTION
WHERE ENCRYPTION_SCHEME != 0
OR ROTATING_OR_FLUSHING != 0;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 Redo Log and the Aria storage engine before removing the encryption key management settings from your configuration file.
In the case of manually encrypted InnoDB tablespaces, (that is, those where the ENCRYPTED table option is set to YES), you must issue an ALTER TABLE 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 TABLES table to find the encrypted tables. This can be done with a WHERE clause filtering the CREATE_OPTIONS column.
SELECT TABLE_SCHEMA AS "Database", TABLE_NAME AS "Table"
FROM information_schema.TABLES
WHERE ENGINE='InnoDB'
AND CREATE_OPTIONS LIKE '%`ENCRYPTED`=YES%';For each table in the result-set, issue an ALTER TABLE statement, setting the ENCRYPTED table option to NO.
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 |
+----------+-------------------+----------------+
ALTER TABLE tab1
ENCRYPTED=NO;
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 | 0 | 100 |
+----------+-------------------+----------------+Once you have removed encryption from all the tables, your InnoDB deployment is unencrypted. Be sure to also remove encryption from the Redo Log as well as Aria 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 system tablespace using ALTER TABLE. Encryption of the system tablespace can only be configured by setting the value of the innodb_encrypt_tables system variable. This means that when you want to encrypt or decrypt the system tablespace, you must also set a non-zero value for the innodb_encryption_threads system variable, and you must also set the innodb_encryption_rotate_key_age system variable to 1 to ensure that the system tablespace is properly encrypted or decrypted by the background threads. See MDEV-14398 for more information.
The innodb_encrypt_temporary_tables system variable controls the configuration of encryption for the temporary tablespace. To disable it, remove the system variable from your server's option file, and then restart the server.
InnoDB uses the Redo Log 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 innodb_encrypt_log system variable to OFF in a server option group in an option file. 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 key management and encryption plugin 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.
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.
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 innodb_encryption_rotate_key_age to the new key version.
When changing the innodb_encrypt_tables system variable to FORCE, InnoDB's background encryption threads encrypt the system tablespace and any file-per-table tablespaces that have the ENCRYPTED table option set to DEFAULT.
When changing the innodb_encrypt_tables system variable to OFF, InnoDB's background encryption threads decrypt the system tablespace and any file-per-table tablespacs that have the ENCRYPTED table option set to DEFAULT.
The innodb_encryption_rotation_iops 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 innodb_encrypt_tables 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 innodb_encryption_threads 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 innodb_encryption_rotate_key_age system variable. For more information, see disabling key rotations.
InnoDB performs the following encryption and decryption operations without using background encryption threads:
When a file-per-table tablespaces and using ALTER TABLE to manually set the ENCRYPTED table option to YES, InnoDB does not use background threads to encrypt the tablespaces.
Similarly, when using file-per-table tablespaces and using ALTER TABLE to manually set the ENCRYPTED 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 file-per-table tablespaces with an ALTER TABLE statement, even when the innodb_encryption_threads and/or the innodb_rotate_key_age system variables are set to 0.
InnoDB does not permit manual encryption changes to tables in the system tablespace using ALTER TABLE. Encryption of the system tablespace can only be configured by setting the value of the innodb_encrypt_tables system variable. This means that when you want to encrypt or decrypt the system tablespace, you must also set a non-zero value for the innodb_encryption_threads system variable, and you must also set the innodb_system_rotate_key_age system variable to 1 to ensure that the system tablespace is properly encrypted or decrypted by the background threads. See MDEV-14398 for more information.
InnoDB records the status of background encryption operations in the INNODB_TABLESPACES_ENCRYPTION table in the information_schema 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:
SELECT SPACE, NAME
FROM information_schema.INNODB_TABLESPACES_ENCRYPTION
WHERE ROTATING_OR_FLUSHING = 1;And to see how many InnoDB tablespaces are currently being decrypted or encrypted by background encryption threads, you can call the COUNT() aggregate function.
SELECT COUNT(*) AS 'encrypting'
FROM information_schema.INNODB_TABLESPACES_ENCRYPTION
WHERE ROTATING_OR_FLUSHING = 1;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 INNODB_SYS_TABLESPACES table in the information_schema database:
/* information_schema.INNODB_TABLESPACES_ENCRYPTION does not always have rows for all tablespaces,
so let's join it with information_schema.INNODB_SYS_TABLESPACES */
WITH tablespace_ids AS (
SELECT SPACE
FROM information_schema.INNODB_SYS_TABLESPACES ist
UNION
/* information_schema.INNODB_SYS_TABLESPACES doesn't have a row for the system tablespace (MDEV-20802) */
SELECT 0 AS SPACE
)
SELECT NOW() as 'time',
'tablespaces', COUNT(*) AS 'tablespaces',
'encrypted', SUM(IF(ite.ENCRYPTION_SCHEME IS NOT NULL, ite.ENCRYPTION_SCHEME, 0)) AS 'encrypted',
'encrypting', SUM(IF(ite.ROTATING_OR_FLUSHING IS NOT NULL, ite.ROTATING_OR_FLUSHING, 0)) AS 'encrypting'
FROM tablespace_ids
LEFT JOIN information_schema.INNODB_TABLESPACES_ENCRYPTION ite
ON tablespace_ids.SPACE = ite.SPACEThis 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.
The innodb_encrypt_tables system variable controls the configuration of automatic encryption of InnoDB tables. It has the following possible values:
OFF
Disables table encryption.
ON
Enables table encryption, but allows unencrypted tables to be created.
FORCE
Enables table encryption, and doesn't allow unencrypted tables to be created. Added in MariaDB 10.1.4.
When innodb_encrypt_tables 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:
SET GLOBAL innodb_encryption_threads=4;
SET GLOBAL innodb_encrypt_tables=ON;
SET SESSION innodb_default_encryption_key_id=100;
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
);
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 |
+----------+-------------------+----------------+When innodb_encrypt_tables is set to ON, an unencrypted InnoDB table can be created by setting the ENCRYPTED table option to NO for the table. For example, the following statements create an unencrypted table and confirm that it is not encrypted:
SET GLOBAL innodb_encryption_threads=4;
SET GLOBAL innodb_encrypt_tables=ON;
SET SESSION innodb_default_encryption_key_id=100;
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTED=NO;
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 | 0 | 100 |
+----------+-------------------+----------------+When innodb_encrypt_tables 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 ENCRYPTED table option to NO for a table, then you will encounter an error. For example:
SET GLOBAL innodb_encryption_threads=4;
SET GLOBAL innodb_encrypt_tables='FORCE';
SET SESSION innodb_default_encryption_key_id=100;
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTED=NO;
ERROR 1005 (HY000): Can't create table `db1`.`tab1` (errno: 140 "Wrong create options")
SHOW WARNINGS;
+---------+------+----------------------------------------------------------------------+
| Level | Code | Message |
+---------+------+----------------------------------------------------------------------+
| Warning | 140 | InnoDB: ENCRYPTED=NO implies ENCRYPTION_KEY_ID=1 |
| Warning | 140 | InnoDB: ENCRYPTED=NO cannot be used with innodb_encrypt_tables=FORCE |
| Error | 1005 | Can't create table `db1`.`tab1` (errno: 140 "Wrong create options") |
| Warning | 1030 | Got error 140 "Wrong create options" from storage engine InnoDB |
+---------+------+----------------------------------------------------------------------+
4 rows in set (0.00 sec)When innodb_encrypt_tables is set to ON or FORCE, then you must ensure that innodb_encryption_threads is set to a non-zero value, so that InnoDB can perform any necessary encryption operations in the background. See background operations for more information about that. innodb_encryption_rotate_key_age must also be set to a non-zero value for the initial encryption operations to happen in the background. See disabling key rotations for more information about that.
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 ENCRYPTED and ENCRYPTION_KEY_ID table options that can be used to manually enable encryption for specific InnoDB tables. These table options can be used with CREATE TABLE and ALTER TABLE statements. These table options can only be used with InnoDB tables that have their own InnoDB's file-per-table tablespaces, meaning that tables that were created with innodb_file_per_table=ON set.
ENCRYPTED
Boolean
Defines whether to encrypt the table
ENCRYPTION_KEY_ID
32-bit integer
Defines the identifier for the encryption key to use
You can manually enable or disable encryption for a table by using the ENCRYPTED 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 innodb_encrypt_tables. 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 FULLTEXT INDEX, 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 enable automatic InnoDB encryption by setting innodb_encrypt_tables to ON or FORCE.
You can also manually specify a encryption key for a table by using the ENCRYPTION_KEY_ID 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:
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTED=YES ENCRYPTION_KEY_ID=100;
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 |
+----------+-------------------+----------------+If the ENCRYPTION_KEY_ID table option is not specified, then the table will be encrypted with the key identified by the innodb_default_encryption_key_id system variable. For example, you might create a table using a statement like this:
SET SESSION innodb_default_encryption_key_id=100;
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTED=YES;
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 |
+----------+-------------------+----------------+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 ALTER TABLE statement. For example:
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTED=NO;
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 | 0 | 100 |
+----------+-------------------+----------------+
ALTER TABLE tab1
ENCRYPTED=YES ENCRYPTION_KEY_ID=100;
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 |
+----------+-------------------+----------------+InnoDB does not permit manual encryption changes to tables in the system tablespace using ALTER TABLE. Encryption of the system tablespace can only be configured by setting the value of the innodb_encrypt_tables system variable. This means that when you want to encrypt or decrypt the system tablespace, you must also set a non-zero value for the innodb_encryption_threads system variable, and you must also set the innodb_system_rotate_key_age system variable to 1 to ensure that the system tablespace is properly encrypted or decrypted by the background threads. See MDEV-14398 for more information.
The innodb_encrypt_temporary_tables system variable controls the configuration of encryption for the temporary tablespace. It has the following possible values:
OFF
Disables temporary table encryption.
ON
Enables temporary table encryption.
This system variable can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
innodb_encrypt_temporary_tables=ONInnoDB uses the Redo Log 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 stop the server process. Then, set the innodb_encrypt_log to ON in a relevant server option group in an option file. For example:
[mariadb]
...
innodb_encrypt_log = ONThen, 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.
In MariaDB 10.3 and before, InnoDB does not support key rotation for the Redo Log. Key rotation for the Redo Log is supported in MariaDB 10.4 and later. See InnoDB Encryption Keys: Key Rotation for more information.
This page is licensed: CC BY-SA / Gnu FDL
InnoDB uses encryption key management 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 innodb_default_encryption_key_id system variable.
Encryption keys can also be specified with the ENCRYPTION_KEY_ID table option for tables that use file-per-table tablespaces.
InnoDB encrypts the temporary tablespace using the encryption key with the ID 1.
InnoDB encrypts the Redo Log using the encryption key with the ID 1.
With tables that use manually enabled encryption, one way to set the specific encryption key for the table is to use the ENCRYPTION_KEY_ID table option. For example:
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTED=YES ENCRYPTION_KEY_ID=100;
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 |
+----------+-------------------+----------------+If the ENCRYPTION_KEY_ID table option is not set for a table that uses manually enabled encryption, then it will inherit the value from the innodb_default_encryption_key_id system variable. For example:
SET SESSION innodb_default_encryption_key_id=100;
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTED=YES;
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 |
+----------+-------------------+----------------+With tables that use automatically enabled encryption, one way to set the specific encryption key for the table is to use the innodb_default_encryption_key_id system variable. For example:
SET GLOBAL innodb_encryption_threads=4;
SET GLOBAL innodb_encrypt_tables=ON;
SET SESSION innodb_default_encryption_key_id=100;
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
);
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 |
+----------+-------------------+----------------+InnoDB tables that are part of the system tablespace can only be encrypted using the encryption key set by the innodb_default_encryption_key_id system variable.
If the table is in a file-per-table tablespace, and if innodb_encrypt_tables is set to ON or FORCE, and if innodb_encryption_threads is set to a value greater than 0, then you can also set the specific encryption key for the table by using the ENCRYPTION_KEY_ID table option. For example:
SET GLOBAL innodb_encryption_threads=4;
SET GLOBAL innodb_encrypt_tables=ON;
CREATE TABLE tab1 (
id INT PRIMARY KEY,
str VARCHAR(50)
) ENCRYPTION_KEY_ID=100;
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 |
+----------+-------------------+----------------+However, if innodb_encrypt_tables is set to OFF or if innodb_encryption_threads is set to 0, then this will not work. See InnoDB Encryption Troubleshooting: Setting Encryption Key ID For an Unencrypted Table for more information.
Some key management and encryption plugins 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 background encryption threads 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 innodb_encryption_rotate_key_age 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 Redo Log is only supported in MariaDB 10.4.0 and later. For more information, see MDEV-12041.
In order for key rotation to work, both the backend key management service (KMS) and the corresponding key management and encryption plugin have to support key rotation. See Encryption Key Management: Support for Key Rotation in Encryption Plugins to determine which plugins currently support key rotation.
In the event that you encounter issues with background key encryption, you can disable it by setting the innodb_encryption_rotate_key_age 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 file_key_management plugin). For more information, see MDEV-14180.
There are, however, issues that can arise when the background key rotation is disabled.
Prior to MariaDB 10.2.24, MariaDB 10.3.15, and MariaDB 10.4.5, when you update the value on the innodb_encrypt_tables system variable InnoDB internally treats the subsequent background operations to encrypt and decrypt tablespaces as background key rotations. See MDEV-14398 for more information.
In older versions of MariaDB, if you have recently changed the value of the innodb_encrypt_tables system variable, then you must ensure that any pending background encryption or decryption operations are complete before disabling key rotation. You can check the status of background encryption operations by querying the INNODB_TABLESPACES_ENCRYPTION table in the information_schema database.
See InnoDB Background Encryption Threads: Checking the Status of Background Operations for some example queries.
Otherwise, in older versions of MariaDB, if you disable key rotation while there are background encryption threads at work, it may result in unencrypted tables that you want encrypted or vice versa.
For more information, see MDEV-14398.
This page is licensed: CC BY-SA / Gnu FDL
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. For instance,
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)Starting in MariaDB 10.1.39, MariaDB 10.2.23, and MariaDB 10.3.14, 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 will no longer fail, and it will no longer throw a warning.
For more information, see MDEV-18601.
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.
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 that was included in MariaDB 10.1.38, MariaDB 10.2.20, and MariaDB 10.3.12 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.
In MariaDB 10.4.3 and later, 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 will be guaranteed to be zero-initialized.
For more information, see MDEV-18097.
MariaDB 10.4.3 introduces 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.
In older versions of MariaDB, spatial index encryption is unsupported. Tables that contain spatial indexes store them unencrypted.
For more information, see MDEV-12026.
This page is licensed: CC BY-SA / Gnu FDL
Explore key management and encryption plugins for MariaDB Server. This section details how to manage encryption keys and leverage plugins for robust data-at-rest protection.
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 Amazon Web Services (AWS) Key Management Service (KMS) Encryption Plugin Setup Guide.
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.
Putting the AWS credentials in a file inside the MariaDB home directory is not ideal. By default, any user with the FILE privilege can read any files that the MariaDB server has permission to read, which would include the credentials file. To protect against this, you should set secure_file_priv to restrict the location the server will allow a user to read from when executing LOAD DATA INFILE or the LOAD_FILE() function.
But putting them in other locations requires passing additional data to the server, which in the case of CentOS 7 requires customizing the systemd startup procedure. This is most easily done by creating a "drop-in" file in /etc/systemd/system/mariadb.service.d/. The file should end in ".conf" but can otherwise be named whatever you like. After making any changes to systemd files, execute systemctl daemon-reload and then start (or restart) the service as usual.
You can place the credentials file in a location of your choosing and then refer to that file by setting the AWS_CREDENTIAL_PROFILES_FILE environment variable in the drop-in file:
[Service]
Environment=AWS_CREDENTIAL_PROFILES_FILE=/etc/aws-kms-credentialsThe credentials file will need to be readable by the "mysql" user, but it does not need to be readable by any other user.
AWS credentials can also be put directly into a "drop-in" systemd file that will be read when starting the MariaDB service:
# cat /etc/systemd/system/mariadb.service.d/aws-kms.conf
[Service]
Environment=AWS_ACCESS_KEY_ID=AKIAIRSG2XYZATCJLZ4A
Environment=AWS_SECRET_ACCESS_KEY=ux91LZIxCp4ZXabcdefgIViQNtTan42QAmJqJVqVHowever, any OS user can read this information from systemd, which could be considered a security risk. Another solution is to put the credentials in a separate file that is only readable by root and then refer to that file using an EnvironmentFile directive in a drop-in systemd file.
# cat /etc/systemd/system/mariadb.service.d/aws-kms.env
AWS_ACCESS_KEY_ID=AKIAIRSG2XYZATCJLZ4A
AWS_SECRET_ACCESS_KEY=ux91LZIxCp4ZXabcdefgIViQNtTan42QAmJqJVqV
# chown root /etc/systemd/system/mariadb.service.d/aws-kms.env
# chmod 600 /etc/systemd/system/mariadb.service.d/aws-kms.env
# cat /etc/systemd/system/mariadb.service.d/aws-kms.conf
[Service]
EnvironmentFile=/etc/systemd/system/mariadb.service.d/aws-kms.envThat has the advantage the credentials can only be read directly by root. systemd adds those variables to the environment of the MariaDB server when starting it, and MariaDB can use the credentials to interact with AWS. Note, though, that any process running as the "mysql" user can still read the credentials from the proc filesystem on Linux.
$ whoami
mysql
$ cat /proc/$(pgrep mysqld)/environ | tr '\0' '\n' | grep AWS
AWS_ACCESS_KEY_ID=AKIAIRSG2XYZATCJLZ4A
AWS_SECRET_ACCESS_KEY=ux91LZIxCp4ZXabcdefgIViQNtTan42QAmJqJVqVAWS KMS allows flexible, user-editable key policy. This offers fine-grained control over which users can operate on keys. The possibilities range from simply restricting which IP addresses are allowed to perform operations on the key, to requiring a MFA (Multi-Factor Authentication) device to use the key, to enforcing separation of responsibilities by creating an additional user with limited privileges to enable and disable the key. All 3 of these options will be outlined in this section.
For more details about customizing the Key Policy for your master keys, please consult the AWS Key Management Service Key Policy documentation.
A simple, common-sense restriction to put in place is to restrict the range of IP addresses that are allowed to use your master key. This way, even if someone obtains API credentials, they'll be unable to use them to decrypt your encryptions keys from a different host.
To restrict API access from only a specific IP address or range of IP addresses, you'll need to manually edit the key policy.
Load the IAM console at.
Click "Encryption Keys" in the left-hand sidebar.
Click the name of your encryption key to view its details.
Click the link labeled "Switch to policy view", to the right of the heading of the "Key Policy" section.
Locate the section that contains "Sid": "Allow use of the key".
Add this text below the "Sid" line:
"Condition": {
"IpAddress": {
"aws:SourceIp": [
"10.1.2.3/32"
]
}
},... replacing 10.1.2.3/32 above with an IP address or range of IP addresses in CIDR format. For example, a single address would be 192.168.12.34/32, while a range of addresses might be 192.168.0.0/24.
Click "Save Changes".
Click "Proceed" if prompted with a warning about using the default view in the future.
Access to the API will now be restricted to requests coming from the IP address or range of IP addresses specified in the policy.
One approach is to modify the key policy for the master key so that MFA (Multi-Factor Authentication) is required in order to use the key. This is achieved with a wrapper that handles prompting the user for an MFA token, acquires temporary, limited-privilege credentials from the AWS Security Token Service (STS), and puts those credentials into the environment of the MariaDB server process. The credentials can expire after as little as 15 minutes.
To require an MFA token for users of the key, you'll need to manually edit the key policy.
Load the IAM console at.
Click "Encryption Keys" in the left-hand sidebar.
Click the name of your encryption key to view its details.
Click the link labeled "Switch to policy view", to the right of the heading of the "Key Policy" section.
Locate the section that contains "Sid": "Allow use of the key".
Add this text below the "Sid" line:
"Condition": {
"Bool": {
"aws:MultiFactorAuthPresent": "True"
}
},Click "Save Changes".
Click "Proceed" if prompted with a warning about using the default view in the future.
Now, add an MFA device for your user. You'll need to have a hardware MFA device or an application such as Google Authenticator installed on your smartphone.
Click "Users" in the left-hand sidebar.
Click the name of your user.
Click the "Security Credentials" tab.
In the "Sign-In Credentials" section, click the "Manage MFA Device" button.
Complete the steps to activate your MFA device.
Copy the ARN for your MFA device. You will need to use this when configuring the wrapper program.
Now, set up the wrapper program.
Copy the iam-kms-wrapper file to /usr/local/bin/, and ensure that it is executable.
Create a drop-in systemd config file in /etc/systemd/system/mariadb.service.d/:
[Service]
EnvironmentFile=/etc/systemd/system/mariadb.service.d/aws-kms.env
ExecStart=
ExecStart=/usr/local/bin/iam-kms-wrapper --config=/etc/my.cnf.d/iam-kms-wrapper.config /usr/sbin/mysqld $MYSQLD_OPTSExecute systemctl daemon-reload.
Create a file at /etc/my.cnf.d/iam-kms-wrapper.config with these contents, using the ARN for your MFA device as the value for kms_mfa_id:
[kms]
kms_mfa_id = arn:aws:iam::551888187628:mfa/MDBEnc
kms_mfa_socket = /tmp/kms_mfa_socketWhen you start the MariaDB service now, the wrapper will temporarily create a socket file at the location given by the kms_mfa_socket option. The wrapper will read the MFA code from the socket and will use it to authenticate to KMS. To give the MFA code, simply write the digits to the socket file using echo: echo 111676 > /tmp/kms_mfa_socket.
The systemctl command will block until MariaDB starts, so you will need to write the code to the socket file via a separate terminal.
Note that the temporary credentials put into the environment of the MariaDB process will expire after a period of time defined by the request to the AWS Security Token Service (STS). In the example below, they will expire after 900 seconds. After that time, MariaDB may be unable to generate new encrypted data keys, which means that, for example, an attempt to create a table with a previously-unused key ID would fail.
Here's an example wrapper program written in go. Build this into an executable named iam-kms-wrapper and use it as instructed above. This could of course be written in any language for which an appropriate AWS SDK exists, but go has the benefit of compiling to a static binary, which means you do not have to worry about interpreter versions or installing complex dependencies on the host that runs your MariaDB server.
package main
import (
"syscall"
"os"
"log"
"flag"
"github.com/aws/aws-sdk-go/aws"
"github.com/aws/aws-sdk-go/aws/session"
"github.com/aws/aws-sdk-go/aws/awserr"
"github.com/aws/aws-sdk-go/service/sts"
"github.com/robfig/config"
)
func main() {
config_file_p := flag.String("config", "", "location of the config file")
flag.Parse()
if flag.NArg() < 1 {
log.Fatal("Command to wrap must be given as first command-line argument")
}
cmd := flag.Arg(0)
args := flag.Args()[0:]
conf, err := config.ReadDefault(*config_file_p)
if err != nil {
log.Fatal(err)
}
kms_mfa_id, err := conf.String("kms","kms_mfa_id")
mfa_socket_file, err := conf.String("kms","kms_mfa_socket")
sess := session.New()
svc := sts.New(sess)
syscall.Umask(0044)
log.Printf("Reading MFA token from %s\n",mfa_socket_file)
if err := syscall.Mknod(mfa_socket_file, syscall.S_IFIFO|uint32(os.FileMode(0622)), 0); err != nil {
log.Fatal(err)
}
file, err := os.Open(mfa_socket_file)
if err != nil {
log.Fatal(err)
}
token := make([]byte, 6)
if _, err := file.Read(token); err != nil {
log.Fatal(err)
}
file.Close()
if err := syscall.Unlink(mfa_socket_file); err != nil {
log.Fatal(err)
}
mfa_token := string(token)
token_params := &sts.GetSessionTokenInput{
DurationSeconds: aws.Int64(900),
SerialNumber: aws.String(kms_mfa_id),
TokenCode: aws.String(mfa_token),
}
resp, err := svc.GetSessionToken(token_params)
if err != nil {
if awsErr, ok := err.(awserr.Error); ok {
// Prints out full error message, including original error if there was one.
log.Fatal("Error:", awsErr.Error())
} else {
log.Fatal("Error:", err.Error())
}
}
creds := resp.Credentials
os.Setenv("AWS_ACCESS_KEY_ID",*creds.AccessKeyId)
os.Setenv("AWS_SECRET_ACCESS_KEY",*creds.SecretAccessKey)
os.Setenv("AWS_SESSION_TOKEN",*creds.SessionToken)
execErr := syscall.Exec(cmd, args, os.Environ())
if execErr != nil {
panic(execErr)
}
}Another possibility is to use the API to disable access to the master key and enable it only when a trusted administrator knows that the MariaDB service needs to be started. A specialized tool on a separate host could be used to enable the key for a very short period of time while the service starts and then quickly disable the key.
To do this, you can create an extra IAM User that can only use the kms:EnableKey and kms:DisableKey API endpoints for your key. This user will not be able to encrypt or decrypt any data using the key.
First, create a new user.
Load the IAM console at.
Click "Users" in the left-hand sidebar.
Click "Create New Users".
Enter a new user name. (The examples will use "MDBEncAdmin".)
Click "Show User Security Credentials".
Copy the credentials and put them in a credentials file with this structure:
[MDBEncAdmin]
aws_access_key_id=AKIAJMPPNO7EBKABCDEF
aws_secret_access_key=pVdGwbuK5/jG64aBK1oEJOXRlkdM0aAylgabCDefClick "Close".
Click "Close" again if prompted.
Click the name of your new user to open the details view.
Copy the "User ARN" value for your user (for example "arn:aws:iam::551888181234:user/MDBEncAdmin"). You will need this for the next step.
Now, give the new user permission to perform API operations on your key.
Click "Encryption Keys" in the left-hand sidebar.
Click the name of your key to open the details view.
Click "Switch to policy view" if it is not already open. (The "policy view" is a large text field that contains JSON describing the key policy.)
Create a new item in the Statement array with this structure:
{
"Sid": "Allow Enable and Disable of the key",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::551888181234:user/MDBEncAdmin"
},
"Action": [
"kms:EnableKey",
"kms:DisableKey"
]
},...so that your Key Policy looks like this:
{
"Version": "2012-10-17",
"Id": "key-consolepolicy-2",
"Statement": [
{
"Sid": "Allow Enable and Disable of the key",
"Effect": "Allow",
"Principal": {
...Click "Save Changes".
You've now added a new IAM user and you've given that user privileges to enable and disable your key. This user will be able to perform those operations using the AWS CLI or via a script of your own design using the AWS API. For example, using the AWS CLI:
$ cat ~/.aws/credentials
[MDBEncAdmin]
aws_access_key_id=AKIAJMPPNO7EBKABCDEF
aws_secret_access_key=pVdGwbuK5/jG64aBK1oEJOXRlkdM0aAylgabCDef
$ AWS_PROFILE=MDBEncAdmin aws --region us-east-1 kms disable-key --key-id arn:aws:kms:us-east-1:551888181234:key/abcdf8f6-084b-4cff-99ca-abcdef6c7907cIn order for MariaDB to start, this new user will have to enable the master key, then the DBA can start MariaDB, and this user can once again disable the master key after the service has started. Note that in this workflow, MariaDB will be unable to create new encryption keys, such as would be done when a user creates a table that refers to a non-existent key ID. The AWS KMS plugin will encounter an error if it tries to generate a new encryption key while the master key is disabled. In that scenario, the key administrator would have to enable the key before the operation could succeed. Here's what you should expect to see in the journal if MariaDB tries to interact with a disabled master key:
[ERROR] AWS KMS plugin : GenerateDataKeyWithoutPlaintext failed : DisabledException - Unable to parse ExceptionName: DisabledException Message: arn:aws:kms:us-east-1:551888181234:key/abcdf8f6-084b-4cff-99ca-abcdef6c7907c is disabled.It's also possible to add MFA to this technique so that the user that enables & disables the master key has to authenticate using an MFA device. Adapt the instructions in the MFA section above to add MFA to the policy section for the user with EnableKey and DisableKeys privileges, add an MFA device for that user, use Security Token Service (STS) to get temporary security credentials, and then use those credentials to make the API calls. Here's an example Python script that follows that workflow:
#!/usr/bin/env python
import boto3
import sys
# Command-line argument processing should be more robust than this...
action= sys.argv[1]
mfa_token= sys.argv[2]
# These should perhaps go into a config file instead of here
mfa_serial= 'arn:aws:iam::551888181234:mfa/MDBEncAdmin'
key_id= 'arn:aws:kms:us-east-1:551888181234:key/abcdf8f6-084b-4cff-99ca-abcdef6c7907c'
# Make the connection to the Security Token Service to get temporary credentials
token_client= boto3.client('sts')
token_response= token_client.get_session_token(
DurationSeconds= 900,
SerialNumber= mfa_serial,
TokenCode= mfa_token
)
cred= token_response['Credentials']
# Start new session using temporary, MFA-authenticated credentials
kms_session= boto3.session.Session(
aws_access_key_id= cred['AccessKeyId'],
aws_secret_access_key= cred['SecretAccessKey'],
aws_session_token= cred['SessionToken'],
region_name= key_id.split(':')[3]
)
# Start KMS client and execute operation against key
kms_client= kms_session.client('kms')
if action == 'enable' or action == 'e':
action_f= kms_client.enable_key
elif action == 'disable' or action == 'd':
action_f= kms_client.disable_key
else:
raise Exception('Action must be either "disable" or "enable"')
action_f(KeyId=key_id)$ AWS_PROFILE=MDBEncAdmin python kms-manage-key disable 575290
$ AWS_PROFILE=MDBEncAdmin python kms-manage-key enable 799870Amazon's CloudTrail service creates JSON-formatted text log files for every API interaction. Enabling CloudTrail requires S3, which incurs additional fees.
First, enable CloudTrail and add a trail.
Load the CloudTrail console at.
If you've never used CloudTrail before, click "Get Started Now".
Enter a value for "trail name". This example uses "mariadb-encryption-key".
Create a new S3 bucket, using a globally unique name, or use an existing S3 bucket, according to your needs.
Click "Turn On".
If you navigate to the S3 bucket you created, you should find log files that contain JSON-formatted descriptions of your API interactions.
Amazon's CloudWatch service allows you to create alarms and event rules that monitor log information.
First, send your CloudTrail logs to CloudWatch.
Load the CloudTrail console at.
Click "Trails" in the left-hand navigation sidebar.
Click the name of your trail to open the Configuration view.
In the "CloudWatch Logs" section, click "Configure".
Click "Continue".
Click "Allow".
Now, set up an SNS topic to facilitate email notifications.
Open.
Make sure the region in the console (look in the upper-right corner) is the same as the region where you created your key!
Click "Get Started" is prompted.
Click "Events" in the left-hand sidebar.
Click "Create new topic".
Enter a Topic name of your choosing.
Enter a Display name of your choosing.
Click "Create topic".
Click the ARN of your new SNS topic.
Click "Create Subscription".
Select "Email" from the Protocol dropdown.
Enter the desired notification email address in the Endpoint field.
Wait for the confirmation email to show up and follow the instructions.
Now, configure CloudWatch and create an Event Rule.
Open.
Make sure the region in the console (look in the upper-right corner) is the same as the region where you created your key and your SNS topic!
Click "Events" in the left-hand sidebar.
Click "Create rule".
Choose "AWS API call" from the "Select event source" dropdown.
Choose "KMS" from the "Service name" dropdown.
Decide which operations should trigger the event. (You can eep "Any operation" selected for simplicity.)
Click "Add target".
Select "SNS target" from the dropdown.
Select the SNS topic you created in the previous steps.
Click "Configure details".
Enter a Name and Description of your choosing.
Click "Create rule".
You should now get emails any time someone executes API calls on the KMS service in the region where you've created the CloudWatch Event rule. That means you should get email any time the key is enabled or disabled, and any time the AWS KMS plugin generates new keys or decrypts the keys stored on disk on the MariaDB server.
You may also wish to create an event rule (or an additional event) that matches only when an unauthorized user tries to access the key. You might accomplish that by manually editing the Event selector of the rule to look something like this:
{
"detail-type": [
"AWS API Call via CloudTrail"
],
"detail": {
"eventSource": [
"kms.amazonaws.com"
],
"errorCode": [
"AccessDenied",
"UnauthorizedOperation"
]
}
}The emails are formatted as JSON. Further customization of the CloudWatch email workflow is beyond the scope of this document.
There are many other workflows available using CloudWatch, including workflows with alarms and dashboards. Those are beyond the scope of this document.
This page is licensed: CC BY-SA / Gnu FDL
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, starting with MariaDB 10.2, 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.
The AWS Key Management plugin depends on the AWS SDK for C++, which uses the Apache License, Version 2.0. This license is not compatible with MariaDB Server's GPL 2.0 license, 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.
When compiling MariaDB from source, the AWS Key Management plugin is not built by default in MariaDB 10.1, but it is built by default in MariaDB 10.2 and later, on systems that support it.
Compilation is controlled by the -DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC -DAWS_SDK_EXTERNAL_PROJECT=1 cmake arguments.
The plugin uses AWS C++ SDK, 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, Visual Studio 2013 or later.
On Unix, the libcurl development package (e.g. libcurl3-dev on Debian Jessie), uuid development package and openssl need to be installed.
You may need to use a newer version of cmake than is provided by default in your OS.
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 INSTALL SONAME or INSTALL PLUGIN. For example:
INSTALL SONAME 'aws_key_management';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 --plugin-load or the --plugin-load-add options. This can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
plugin_load_add = aws_key_managementIf you already have an AWS account, you can skip this section.
Load.
Click "Create a Free Account" and complete the steps.
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 Principlesfor more information about pricing of AWS services.
You'll need to complete the AWS identify verification process.
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 intent to run MariaDB Server outside of AWS, you may want to create a User.
Load the Identity and Access Management Console at.
Click "Roles" in the left-hand sidebar
Click "Create new role"
Select "AWS Service Role"
Click the "Select" button next to "Amazon EC2 / Allows EC2 instances to call AWS services on your behalf."
Do not select any policies on the "Attach Policy" screen. Click "Next Step"
Click "Next Step"
Give your Role a "Role name"
Click "Create role"
Load the Identity and Access Management Console at.
Click "Users" in the left-hand sidebar.
Click the "Create New Users" button
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.
Click "Create".
Click "Show User Security Credentials".
Copy the Access Key ID and Secret Access Key. Optionally, you can click "Download Credentials". We will need these in order for local programs to interact with AWS using its API.
Create a file on your computer to hold the credentials for this user. We'll use this file later. It should have this structure:
[default]
aws_access_key_id = AKIAIG6IZ6TKF52FVV5A
aws_secret_access_key = o7CEf7KhZfsVF9cS0a2roqqZNmuzXtIR869zpSBTClick "Close". If prompted because you did not Download Credentials, ensure that you've saved them somewhere, and click "Close".
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.
Click "Encryption Keys" in the left-hand sidebar.
Click the "Get Started Now" button.
Use the "Filter" dropdown to choose the region where you'd like to create your master key.
Click the "Create Key" button.
Enter an Alias and Description of your choosing.
Click "Next Step".
Do not check the box to make your IAM Role or IAM User user a Key Administrator.
Click "Next Step" again.
Check the boxes to give your IAM Role and/or IAM User permissions to use this key.
Click "Next Step".
Click "Finish".
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.
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.
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:
$ cat /var/lib/mysql/.aws/credentials
[default]
aws_access_key_id = AKIAIG6IZ6TKF52FVV5A
aws_secret_access_key = o7CEf7KhZfsVF9cS0a2roqqZNmuzXtIR869zpSBT
region = us-east-1Change the permissions of the file so that it is owned by, and can only be read by, the mysql user:
chown mysql /var/lib/mysql/.aws/credentials
chmod 600 /var/lib/mysql/.aws/credentialsCreate 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:
[mariadb]
plugin_load_add = aws_key_management
aws-key-management = FORCE_PLUS_PERMANENT
aws-key-management-master-key-id = alias/mariadb-encryption
aws-key-management-region = us-east-1
!include /etc/my.cnf.d/enable_encryption.presetAppend 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.
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:
setsebool -P mysql_connect_any 1There are more complex alternatives that have a more granular effect, but those are beyond the scope of this document.
Start MariaDB using the systemctl tool:
systemctl start mariadbIf you do not use systemd, you may have to start MariaDB using some other mechanism.
You should see journal output similar to this:
# journalctl --no-pager -o cat -u mariadb.service
[Note] /usr/sbin/mysqld (mysqld 10.1.9-MariaDB-enterprise-log) starting as process 19831 ...
[Note] AWS KMS plugin: generated encrypted datakey for key id=1, version=1
[Note] AWS KMS plugin: loaded key 1, version 1, key length 128 bit
[Note] InnoDB: Using mutexes to ref count buffer pool pages
[Note] InnoDB: The InnoDB memory heap is disabled
[Note] InnoDB: Mutexes and rw_locks use GCC atomic builtins
[Note] InnoDB: Memory barrier is not used
[Note] InnoDB: Compressed tables use zlib 1.2.7
[Note] InnoDB: Using CPU crc32 instructions
[Note] InnoDB: Initializing buffer pool, size = 2.0G
[Note] InnoDB: Completed initialization of buffer pool
[Note] InnoDB: Highest supported file format is Barracuda.
[Note] InnoDB: 128 rollback segment(s) are active.
[Note] InnoDB: Waiting for purge to start
[Note] InnoDB: Percona XtraDB (http://www.percona.com) 5.6.26-74.0 started; log sequence number 1616819
[Note] InnoDB: Dumping buffer pool(s) not yet started
[Note] Plugin 'FEEDBACK' is disabled.
[Note] AWS KMS plugin: generated encrypted datakey for key id=2, version=1
[Note] AWS KMS plugin: loaded key 2, version 1, key length 128 bit
[Note] Using encryption key id 2 for temporary files
[Note] Server socket created on IP: '::'.
[Note] Reading of all Master_info entries succeded
[Note] Added new Master_info '' to hash table
[Note] /usr/sbin/mysqld: ready for connections.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:
# ls -l /var/lib/mysql/aws*
-rw-rw----. 1 mysql mysql 188 Feb 25 18:55 /var/lib/mysql/aws-kms-key.1.1
-rw-rw----. 1 mysql mysql 188 Feb 25 18:55 /var/lib/mysql/aws-kms-key.2.1Note 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 mariadb-install-db 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:
# sudo -u mysql mariadb-install-db
Installing MariaDB/MySQL system tables in '/var/lib/mysql' ...
2016-02-25 23:16:06 139731553998976 [Note] /usr/sbin/mysqld (mysqld 10.1.11-MariaDB-enterprise-log) starting as process 39551 ...
2016-02-25 23:16:07 139731553998976 [Note] AWS KMS plugin: generated encrypted datakey for key id=1, version=1
2016-02-25 23:16:07 139731553998976 [Note] AWS KMS plugin: loaded key 1, version 1, key length 128 bit
...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:
MariaDB [test]> CREATE TABLE t1 (id serial, v VARCHAR(32)) ENCRYPTION_KEY_ID=3;
Query OK, 0 rows affected (0.91 sec)[Note] AWS KMS plugin: generated encrypted datakey for key id=3, version=1
[Note] AWS KMS plugin: loaded key 3, version 1, key length 128 bit# ls -l /var/lib/mysql/aws*
-rw-rw----. 1 mysql mysql 188 Feb 25 18:55 /var/lib/mysql/aws-kms-key.1.1
-rw-rw----. 1 mysql mysql 188 Feb 25 18:55 /var/lib/mysql/aws-kms-key.2.1
-rw-rw----. 1 mysql mysql 188 Feb 25 19:10 /var/lib/mysql/aws-kms-key.3.1Read more about encrypting data in the Data at Rest Encryption section of the MariaDB Documentation.
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: Encryption algorithm used to create new keys. Allowed values are AES_128 (default) or AES_256.
aws_key_management_log_level: Logging for AWS API. Allowed values, in increasing verbosity, are "Off" (default), "Fatal", "Error", "Warn", "Info", "Debug", and "Trace".
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 Amazon Web Services (AWS) Key Management Service (KMS) Encryption Plugin Advanced Usage.
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 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.
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 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 uses the Amazon Web Services (AWS) Key Management Service (KMS) to generate and store AES keys on disk, in encrypted form, using the Customer Master Key (CMK) kept in AWS KMS. When MariaDB Server starts, the plugin will decrypt the encrypted keys, using the AWS KMS "Decrypt" API function. MariaDB data will then be encrypted and decrypted using the AES key. It supports multiple encryption keys. It supports key rotation.
Tutorials related to the AWS Key Management plugin can be found at the following pages:
Before you use the plugin, you need to create a Customer Master Key (CMK). Create a key using the AWS Console as described in the AMS KMS developer guide.
The easiest way to give the AWS key management plugin access to the key is to create an IAM Role with access to the key, and to apply that IAM Role to an EC2 instance where MariaDB Server runs.
Make sure that MariaDB Server runs under the correct AWS identity that has access to the above key. For example, you can store the AWS credentials in a AWS credentials file for the user who runs mysqld. More information about the credentials file can be found in the AWS CLI Getting Started Guide.
The AWS Key Management plugin depends on the AWS SDK for C++, which uses the Apache License, Version 2.0. This license is not compatible with MariaDB Server's GPL 2.0 license, 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.
When compiling MariaDB from source, the AWS Key Management plugin is not built by default in MariaDB 10.1, but it is built by default in MariaDB 10.2 and later, on systems that support it.
Compilation is controlled by the following cmake arguments:
-DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC to build a loadable plugin library
-DAWS_SDK_EXTERNAL_PROJECT=ON to download the AWS C++ SDK code
-DNOT_FOR_DISTRIBUTION=ON to confirm that you know to not distribute the resulting binaries
The plugin uses AWS C++ SDK, 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, Visual Studio 2013 or later.
On Unix, the libcurl development package (e.g. libcurl3-dev on Debian Jessie), uuid development package and openssl need to be installed.
You may need to use a newer version of cmake than is provided by default in your OS.
You do not need to download / install the AWS C++ SDK yourself, the correct version of the SDK github repository will be cloned into the build directory at build time, and only the libraries for AWS components actually needed by the key management plugin will be built, which takes much less time than building the full AWS C++ SDK.
With all prerequisites installed the actual build process pretty much comes down to:
# clone the MariaDB Server source code repository
git clone https://github.com/MariaDB/server.git
cd server
# prepare the build
mkdir _build
cd _build
cmake .. -DNOT_FOR_DISTRIBUTION=ON \
-DPLUGIN_AWS_KEY_MANAGEMENT=DYNAMIC \
-DAWS_SDK_EXTERNAL_PROJECT=1
# build the plugin only
cd plugin/aws_key_management
makeCmake will print the following warning as part of its output, please take it serious and do not distribute the aws_key_management.so file to any third parties:You have linked MariaDB with Apache 2.0 libraries! You may not distribute
the resulting binary. If you do, you will put yourself into a legal
problem with the Free Software Foundation.
After make succeeded you can copy the created aws_key_management.so plugin library file to the plugin directory of your actual MariaDB Server machines installation, e.g. /usr/lib64/mysql/plugin on RedHat/Fedora based systems or /usr/lib/mysql/plugin on Debian based systems.
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 INSTALL SONAME or INSTALL PLUGIN. For example:
INSTALL SONAME 'aws_key_management';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 --plugin-load or the --plugin-load-add options. This can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
plugin_load_add = aws_key_managementBefore you uninstall the plugin, you should ensure that data-at-rest encryption is completely disabled, and that MariaDB no longer needs the plugin to decrypt tables or other files.
You can uninstall the plugin dynamically by executing UNINSTALL SONAME or UNINSTALL PLUGIN. For example:
UNINSTALL SONAME 'aws_key_management';If you installed the plugin by providing the --plugin-load or the --plugin-load-add options in a relevant server option group in an option file, then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.
To enable the AWS Key Management plugin, you also need to set the plugin's system variables. The aws_key_management_master_key_id system variable is the primary one to set. These system variables can be specified as command-line arguments to mysqld or they can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
aws_key_management_master_key_id=alias/<your key's alias>Once you've updated the configuration file, restart the MariaDB server to apply the changes and make the key management and encryption plugin available for use.
Once the AWS Key Management Plugin is enabled, you can use it by creating an encrypted table:
CREATE TABLE t (i INT) ENGINE=InnoDB ENCRYPTED=YESNow, table t will be encrypted using the encryption key generated by AWS.
For more information on how to use encryption, see Data at Rest Encryption.
The AWS Key Management Plugin supports using multiple encryption keys. Each encryption key can be defined with a different 32-bit integer as a key identifier. If a previously unused identifier is used, then the plugin will automatically generate a new key.
When encrypting InnoDB tables, the key that is used to encrypt tables can be changed.
When encrypting Aria tables, the key that is used to encrypt tables cannot currently be changed.
The AWS Key Management plugin does support key rotation. To rotate a key, set the aws_key_management_rotate_key system variable. For example, to rotate key with ID 2:
SET GLOBAL aws_key_management_rotate_key=2;Or to rotate all keys, set the value to -1:
SET GLOBAL aws_key_management_rotate_key=-1;aws_key_management_key_specDescription: Encryption algorithm used to create new keys
Commandline: --aws-key-management-key-spec=value
Scope: Global
Dynamic: No
Data Type: enumerated
Default Value: AES_128
Valid Values: AES_128, AES_256
aws_key_management_log_levelDescription: Dump log of the AWS SDK to MariaDB error log. Permitted values, in increasing verbosity, are Off (default), Fatal, Error, Warn, Info, Debug, and Trace.
Commandline: --aws-key-management-log-level=value
Scope: Global
Dynamic: No
Data Type: enumerated
Default Value: Off
Valid Values: Off, Fatal, Warn, Info, Debug and Trace
aws_key_management_master_key_idDescription: AWS KMS Customer Master Key ID (ARN or alias prefixed by alias/) for the master encryption key. Used to create new data keys. If not set, no new data keys will be created.
Commandline: --aws-key-management-master-key-id=value
Scope: Global
Dynamic: No
Data Type: string
Default Value:
aws_key_management_mockDescription: Mock AWS KMS calls (for testing). Must be enabled at compile-time.
Commandline: --aws-key-management-mock
Scope: Global
Dynamic: No
Data Type: boolean
Default Value: OFF
Valid Values: OFF, ON
aws_key_management_regionDescription: AWS region name, e.g us-east-1 . Default is SDK default, which is us-east-1.
Commandline: --aws-key-management-region=value
Scope: Global
Dynamic: No
Data Type: string
Default Value: 'us-east-1'
aws_key_management_request_timeoutDescription: Timeout in milliseconds for create HTTPS connection or execute AWS request. Specify 0 to use SDK default.
Commandline: --aws-key-management-request-timeout=value
Scope: Global
Dynamic: No
Data Type: integer
Default Value: 0
aws_key_management_rotate_keyDescription: 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.
Commandline: --aws-key-management-rotate-key=value
Scope: Global
Dynamic: Yes
Data Type: integer
Default Value:
aws_key_managementDescription: 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 mysql.plugins table.
ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.
FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.
See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
Commandline: --aws-key-management=value
Data Type: enumerated
Default Value: ON
Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT
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.
How MariaDB manages encryption keys depends on which encryption key management solution you choose. Currently, MariaDB has three options:
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 example and as a starting point when developing a key management plugin.
For more information, see File 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 AWS SDK for C++, which uses the Apache License, Version 2.0. This license is not compatible with MariaDB Server's GPL 2.0 license, 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.
For more information, see AWS Key Management Plugin.
The Eperi Key Management plugin is a key management and encryption plugin that uses the eperi Gateway for Databases. The eperi Gateway for Databases stores encryption keys on the key server outside of the database server itself, which provides an extra level of security. The eperi Gateway for Databases also supports performing all data encryption operations on the key server as well, but this is optional.
For more information, see Eperi Key Management Plugin.
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. Encryption key 1 is intended for encrypting system data, such as InnoDB redo logs, binary logs, and so on. It must always exist when data-at-rest encryption is enabled. 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 encryption key 1 for these purposes instead.
When encrypting InnoDB tables, the key that is used to encrypt tables can be changed.
When encrypting Aria tables, the key that is used to encrypt tables cannot currently be changed.
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 InnoDB storage engine has background encryption threads that can automatically re-encrypt pages when key rotations occur.
The Aria storage engine does not currently have a similar mechanism to re-encrypt pages in the background when key rotations occur.
The AWS Key Management Service (KMS) supports encryption key rotation, and the corresponding AWS Key Management Plugin also supports encryption key rotation.
The eperi Gateway for Databases supports encryption key rotation, and the corresponding Eperi Key Management Plugin also supports encryption key rotation.
The File Key Management Plugin does not support encryption key rotation, because it does not use a backend key management service (KMS).
New key management and encryption plugins can be developed using the encryption plugin API.
This page is licensed: CC BY-SA / Gnu FDL
Eperi's Key Management Plugin Package no longer appears to be available.
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 Eperi Key Management plugin is a key management and encryption plugin that integrates with eperi Gateway for Databases.
The Eperi Key Management plugin is one of the key management and encryption plugins that can be set up for users who want to use data-at-rest encryption. Some of the plugin's primary features are:
It reads encryption keys from eperi Gateway for Databases.
It supports multiple encryption keys.
It supports key rotation.
It supports two different algorithms for encrypting data.
The eperi Gateway for Databases stores encryption keys on the key server outside of the database server itself, which provides an extra level of security. The eperi Gateway for Databases also supports performing all data encryption operations on the key server as well, but this is optional.
It also provides the following benefits:
Key management outside the database
No keys on database server hard disk
Graphical user interface for configuration
Encryption and decryption outside the database, supporting HSM's for maximum security.
Support for MariaDB is provided in eperi Gateway for Databases 3.4.
For information on how to install the package, see Eperi's documentation at the Eperi Customer Portal.
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. The plugin can be installed by providing the --plugin-load or the --plugin-load-add options. This can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
plugin_load_add = eperi_key_management_pluginBefore you uninstall the plugin, you should ensure that data-at-rest encryption is completely disabled, and that MariaDB no longer needs the plugin to decrypt tables or other files.
You can uninstall the plugin dynamically by executing UNINSTALL SONAME or UNINSTALL PLUGIN. For example:
UNINSTALL SONAME 'eperi_key_management_plugin';If you installed the plugin by providing the --plugin-load or the --plugin-load-add options in a relevant server option group in an option file, then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.
For information on how to configure the plugin, see Eperi's documentation at the Eperi Customer Portal.
Once the Eperi Key Management Plugin is enabled, you can use it by creating an encrypted table:
CREATE TABLE t (i INT) ENGINE=InnoDB ENCRYPTED=YESNow, table t will be encrypted using the encryption key from the key server.
For more information on how to use encryption, see Data at Rest Encryption.
The Eperi Key Management Plugin supports using multiple encryption keys. Each encryption key can be defined with a different 32-bit integer as a key identifier.
When encrypting InnoDB tables, the key that is used to encrypt tables can be changed.
When encrypting Aria tables, the key that is used to encrypt tables cannot currently be changed.
The Eperi Key Management plugin supports key rotation.
eperi_key_management_plugin_databaseIdDescription: Determines the database ID which is processed in the eperi Gateway.
Commandline: --eperi-key-management-plugin-databaseid=value
Scope: Global
Dynamic: No
Data Type: integer
Default Value: 1
eperi_key_management_plugin_encryption_algorithmDescription: 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 recent versions of OpenSSL. If the server is built with wolfSSL or yaSSL, then this algorithm is not available. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
Commandline: --eperi-key-management-plugin-encryption-algorithm=value
Scope: Global
Dynamic: No
Data Type: enumerated
Default Value: AES_CBC
Valid Values: AES_CBC, AES_CTR
eperi_key_management_plugin_encryption_modeDescription: Encryption mode.
Commandline: --eperi-key-management-plugin-encryption-mode=value
Scope: Global
Dynamic: No
Data Type: enumerated
Default Value: database
Valid Values: database, gateway
eperi_key_management_plugin_osslmtDescription: Determines, whether the plugin should register callback functions for OpenSSL thread support.
Commandline: --eperi-key-management-plugin-osslmt=value
Scope: Global
Dynamic: No
Data Type: boolean
Default Value: 0 (Linux), 1 (Windows)
eperi_key_management_plugin_portDescription: Listener port for plugin.
Commandline: --eperi-key-management-plugin-port=value
Scope: Global
Dynamic: No
Data Type: integer
Default Value: 14332
eperi_key_management_plugin_urlDescription: URL to key server. The expected format of the URL is :. The port number is optional, and the port number defaults to 14333 if it is not specified.
Commandline: --eperi-key-management-plugin-url=value
Scope: Global
Dynamic: No
Data Type: string
Default Value: NULL
eperi_key_management_plugin_url_check_disabledDescription: Determines, whether the connection between plugin and eperi Gateway is tested at server startup.
Commandline: --eperi-key-management-plugin-url-check-disabled=value
Scope: Global
Dynamic: No
Data Type: boolean
Default Value: 1
eperi_key_management_pluginDescription: 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 mysql.plugins table.
ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.
FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.
See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
Commandline: --eperi-key-management-plugin=value
Data Type: enumerated
Default Value: ON
Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT
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 plain-text file.
The File Key Management plugin is the easiest key management and encryption plugin to set up for users who want to use data-at-rest encryption. 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 does not support key rotation.
It supports two different algorithms for encrypting data.
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.
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.
Although the plugin's shared library is distributed with MariaDB by default, the plugin is not actually installed by MariaDB by default. The plugin can be installed by providing the --plugin-load or the --plugin-load-add options. This can be specified as a command-line argument to mysqld or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
plugin_load_add = file_key_managementBefore you uninstall the plugin, you should ensure that data-at-rest encryption is completely disabled, and that MariaDB no longer needs the plugin to decrypt tables or other files.
You can uninstall the plugin dynamically by executing UNINSTALL SONAME or UNINSTALL PLUGIN. For example:
UNINSTALL SONAME 'file_key_management';If you installed the plugin by providing the --plugin-load or the --plugin-load-add options in a relevant server option group in an option file, then those options should be removed to prevent the plugin from being loaded the next time the server is restarted.
In order to encrypt your tables with encryption keys using the File Key Management plugin, you first need to create the file that contains the encryption keys. The file needs to contain two pieces of information for each encryption key. First, each encryption key needs to be identified with a 32-bit integer as the key identifier. Second, the encryption key itself needs to be provided in hex-encoded form. These two pieces of information need to be separated by a semicolon. For example, the file is formatted in the following way:
<encryption_key_id1>;<hex-encoded_encryption_key1>
<encryption_key_id2>;<hex-encoded_encryption_key2>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 Advanced Encryption Standard (AES) to encrypt data, which supports 128-bit, 192-bit, and 256-bit encryption keys. Therefore, the plugin also supports 128-bit, 192-bit, and 256-bit encryption keys.
You can generate random encryption keys using the openssl rand command. For example, to create a random 256-bit (32-byte) encryption key, you would run the following command:
$ openssl rand -hex 32
a7addd9adea9978fda19f21e6be987880e68ac92632ca052e5bb42b1a506939aThe key file still needs to have a key identifier for each encryption key added to the beginning of each line. Key identifiers do not need to be contiguous.
For example, to append three new encryption keys to a new key file, you could execute the following:
$ (echo -n "1;" ; openssl rand -hex 32 ) | sudo tee -a /etc/mysql/encryption/keyfile
$ (echo -n "2;" ; openssl rand -hex 32 ) | sudo tee -a /etc/mysql/encryption/keyfile
$ (echo -n "100;" ; openssl rand -hex 32 ) | sudo tee -a /etc/mysql/encryption/keyfileThe new key file would look something like the following after this step:
1;a7addd9adea9978fda19f21e6be987880e68ac92632ca052e5bb42b1a506939a
2;49c16acc2dffe616710c9ba9a10b94944a737de1beccb52dc1560abfdd67388b
100;8db1ee74580e7e93ab8cf157f02656d356c2f437d548d5bf16bf2a56932954a3The 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 ENCRYPTION_KEY_ID table option or with system variables such as innodb_default_encryption_key_id. You do not necessarily need multiple encryption keys--the encryption key with the key identifier 1 is the only mandatory encryption key.
If the key file is unencrypted, then the File Key Management plugin only requires the file_key_management_filename system variable to be configured.
This system variable can be specified as command-line arguments to mysqld or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
loose_file_key_management_filename = /etc/mysql/encryption/keyfileNote that the loose option prefix is specified. This option prefix is used in case the plugin hasn't been installed yet.
By enabling the File Key Management plugin and setting the appropriate path on the file_key_management_filename system variable, you can begin using the plugin to manage your encryption keys. But, there is a security risk in doing so, given that the keys are stored in plain text on your system. You can reduce this exposure using file permissions, but it's better to encrypt the whole key file to further restrict access.
There are some important details to keep in mind about encrypting the key file, such as:
The only algorithm that MariaDB currently supports to encrypt the key file is Cipher Block Chaining (CBC) mode of Advanced Encryption Standard (AES).
The encryption key size can be 128-bits, 192-bits, or 256-bits.
The encryption key is created from the SHA-1 hash of the encryption password.
The encryption password has a max length of 256 characters.
You can generate a random encryption password using the openssl rand command. For example, to create a random 256 character encryption password, you could execute the following:
$ sudo openssl rand -hex 128 > /etc/mysql/encryption/keyfile.keyYou can encrypt the key file using the openssl enc command. For example, to encrypt the key file with the encryption password created in the previous step, you could execute the following:
$ sudo openssl enc -aes-256-cbc -md sha1 \
-pass file:/etc/mysql/encryption/keyfile.key \
-in /etc/mysql/encryption/keyfile \
-out /etc/mysql/encryption/keyfile.encNote: some more recent openssl versions may complain with
*** WARNING : deprecated key derivation used.
Using -iter or -pbkdf2 would be better.Keys generated that way won't work with the current implementation of the plugin though. Also as SHA1 is only used to generate the actual AES encryption key, from a long random string, it's not really an issue here. SHA1 deprecation is mostly related to checksum / signing use cases, not to what we are using it here for.
Running this command reads the unencrypted keyfile file created above and creates a new encrypted keyfile.enc file, using the encryption password stored in keyfile.key. Once you've finished preparing your system, you can delete the unencrypted keyfile file, as it's no longer necessary.
If the key file is encrypted, then the File Key Management plugin requires both the file_key_management_filename and the file_key_management_filekey system variables to be configured.
The file_key_management_filekey system variable can be provided in two forms:
It can be the actual plain-text encryption password. This is not recommended, since the plain-text encryption password would be visible in the output of the SHOW VARIABLES statement.
If it is prefixed with FILE:, then it can be a path to a file that contains the plain-text encryption password.
These system variables can be specified as command-line arguments to mysqld or they can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
loose_file_key_management_filename = /etc/mysql/encryption/keyfile.enc
loose_file_key_management_filekey = FILE:/etc/mysql/encryption/keyfile.keyNote that the loose option prefix is specified. This option prefix is used in case the plugin hasn't been installed yet.
The File Key Management plugin currently supports two encryption algorithms for encrypting data: AES_CBC and AES_CTR. Both of these algorithms use Advanced Encryption Standard (AES) 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 Cipher Block Chaining (CBC) 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 theCounter (CTR) mode. When encrypting temporary files (where the cipher text is allowed to be larger than the plain text), it uses AES in the authenticated Galois/Counter Mode (GCM).
The recommended algorithm is AES_CTR, but this algorithm is only available when MariaDB is built with recent versions of OpenSSL. If the server is built with wolfSSL or yaSSL, then this algorithm is not available. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
The encryption algorithm can be configured by setting the file_key_management_encryption_algorithm system variable.
This system variable can be set to one of the following values:
AES_CBC
Data is encrypted using AES in the Cipher Block Chaining (CBC) mode. This is the default value.
AES_CTR
Data is encrypted using AES either in the Counter (CTR) mode or in the authenticated Galois/Counter Mode (GCM) mode, depending on context. This is only supported in some builds. See the previous section for more information.
This system variable can be specified as command-line arguments to mysqld or it can be specified in a relevant server option group in an option file. For example:
[mariadb]
...
loose_file_key_management_encryption_algorithm = AES_CTRNote that the loose 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 Cipher Block Chaining (CBC) mode of Advanced Encryption Standard (AES).
Once the File Key Management Plugin is enabled, you can use it by creating an encrypted table:
CREATE TABLE t (i INT) ENGINE=InnoDB ENCRYPTED=YESNow, table t will be encrypted using the encryption key from the key file.
For more information on how to use encryption, see Data at Rest Encryption.
The File Key Management Plugin supports using multiple encryption keys. Each encryption key can be defined with a different 32-bit integer as a key identifier.
When encrypting InnoDB tables, the key that is used to encrypt tables can be changed.
When encrypting Aria tables, the key that is used to encrypt tables cannot currently be changed.
The File Key Management plugin does not currently support key rotation. See MDEV-20713 for more information.
file_key_management_encryption_algorithmDescription: 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 recent versions of OpenSSL. If the server is built with wolfSSL or yaSSL, then this algorithm is not available. See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
Commandline: --file-key-management-encryption-algorithm=value
Scope: Global
Dynamic: No
Data Type: enumerated
Default Value: AES_CBC
Valid Values: AES_CBC, AES_CTR
file_key_management_filekeyDescription: This system variable is used to determine the encryption password that is used to decrypt the key file defined by file_key_management_filename.
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.
The encryption password has a max length of 256 characters.
The only algorithm that MariaDB currently supports when decrypting the key file is Cipher Block Chaining (CBC) mode of Advanced Encryption Standard (AES). The encryption key size can be 128-bits, 192-bits, or 256-bits. The encryption key is calculated by taking a SHA-1 hash of the encryption password.
Commandline: --file-key-management-filekey=value
Scope: Global
Dynamic: No
Data Type: string
Default Value: (empty)
file_key_management_filenameDescription: This system variable is used to determine the path to the file that contains the encryption keys. If file_key_management_filekey is set, then this file can be encrypted with Cipher Block Chaining (CBC) mode of Advanced Encryption Standard (AES).
Commandline: --file-key-management-filename=value
Scope: Global
Dynamic: No
Data Type: string
Default Value: (empty)
file_key_managementDescription: 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 mysql.plugins table.
ON - Enables the plugin. If the plugin cannot be initialized, then the server will still continue starting up, but the plugin will be disabled.
FORCE - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error.
FORCE_PLUS_PERMANENT - Enables the plugin. If the plugin cannot be initialized, then the server will fail to start with an error. In addition, the plugin cannot be uninstalled with UNINSTALL SONAME or UNINSTALL PLUGIN while the server is running.
See Plugin Overview: Configuring Plugin Activation at Server Startup for more information.
Commandline: --file-key-management=value
Data Type: enumerated
Default Value: ON
Valid Values: OFF, ON, FORCE, FORCE_PLUS_PERMANENT
This page is licensed: CC BY-SA / Gnu FDL
MariaDB starting with 10.9
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 the 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 their 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.
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:
~$ vault secrets enable -path /test -version=2 kvKey names must correspond to their numerical identifiers. Key identifiers itself, 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:
~$ vault kv get /test/1
====== Metadata ======
Key Value
--- -----
created_time 2019-12-14T14:19:19.42432951Z
deletion_time n/a
destroyed false
version 1
==== Data ====
Key Value
--- -----
data 0123456789ABCDEF0123456789ABCDEFKeys 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:
~$ vault kv put /test/1 data="0123456789ABCDEF0123456789ABCDEF"If you use default encryption (AES), you should ensure that the key length is 32 bytes, otherwise 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:
--plugin-load-add=hashicorp_key_management.so
--loose-hashicorp-key-management
--loose-hashicorp-key-management-vault-url="$VAULT_ADDR/v1/test"
--loose-hashicorp-key-management-token="$VAULT_TOKEN"The plugin supports the following parameters, which must be set in advance and cannot be changed during server operation:
hashicorp-key-management-vault-urlDescription: 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 storages 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 with the correct path to your secrets.
Commandline: --[loose-]hashicorp-key-management-vault-url="<url>"
hashicorp-key-management-tokenDescription: Authentication token that 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.
Commandline: --[loose-]hashicorp-key-management-token="<token>"
hashicorp-key-management-vault-caDescription: 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.
Commandline: --[loose-]hashicorp-key-management-vault-ca="<path>"
hashicorp-key-management-timeoutDescription: 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).
Commandline: --[loose-]hashicorp-key-management-timeout=<timeout>
hashicorp-key-management-retriesDescription: Number of server request retries in case of timeout. Default is three retries.
Commandline: ----[loose-]hashicorp-key-management-retries=<retries>
hashicorp-key-management-caching-enabledDescription: Enable key caching (storing key values received from the Hashicorp Vault server in the local memory). By default caching is enabled.
Commandline: --[loose-]hashicorp-key-management-caching-enabled="on"|"off"
hashicorp-key-management-use-cache-on-timeoutDescription: 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 --[loose-]hashicorp-key-management-retries parameter has been exhausted.
Commandline: --[loose-]hashicorp-key-management-use-cache-on-timeout="on"|"off"
hashicorp-key-management-cache-timeoutDescription: 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 send 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.
Commandline: --[loose-]hashicorp-key-management-cache-timeout=<timeout>
hashicorp-key-management-cache-version-timeoutDescription: The time (in milliseconds) after which the information about latest version number of the key (which stored in the cache) becomes invalid and an attempt to read this information causes a new request send to the vault server. If the value of this parameter is zero, then information about latest key version numbers 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.
Commandline: --[loose-]hashicorp-key-management-cache-version-timeout=<timeout>
hashicorp-key-management-check-kv-versionDescription: This parameter enables ("on", this is the default value) or disables ("off") checking the kv storage version during plugin initialization. The plugin requires storage to be version 2 or older in order for it to work properly.
Commandline: --[loose-]hashicorp-key-management-check-kv-version="on"|"off"
This page is licensed: CC BY-SA / Gnu FDL