Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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 , 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 ) that signs the X509 certificate and validates ownership of the domain. However, when you would like to use self-signed certificates, you need to create the private key and certificate for the CA yourself, and then you can use them to sign your own X509 certificates.
To start, generate a private key for the CA using the command. For example:
After that, you can use the private key to generate the X509 certificate for the CA using the command. For example:
The above commands create two files in the working directory: The ca-key.pem private key and the ca.pem X509 certificate are both are used by the CA to create self-signed X509 certificates below.
Once you have the CA's private key and X509 certificate, you can create the self-signed X509 certificates to use for the MariaDB Server, client, replication and other purposes.
To start, generate a private key and create a certificate request using the command. For example:
After that, process the key to remove the passphrase using the command. For example:
Lastly, using the certificate request and the CA's private key and X509 certificate, you can generate a self-signed X509 certificate from the certificate request using the command. For example:
This creates a server-cert.pem file, which is the self-signed X509 certificate.
Once you have created the CA's X509 certificate and a self-signed X509 certificate, you can verify that the X509 certificate was correctly generated using the command. For example:
You can add as many X509 certificates to check against the CA's X509 certificate as you want to verify. A value of OK indicates that you can use it was correctly generated and is ready for use with MariaDB.
This page is licensed: CC BY-SA / Gnu FDL
# openssl genrsa 2048 > ca-key.pem# openssl req -new -x509 -nodes -days 365000 \
-key ca-key.pem -out ca.pem# openssl req -newkey rsa:2048 -days 365000 \
-nodes -keyout server-key.pem -out server-req.pem# openssl rsa -in server-key.pem -out server-key.pem# openssl x509 -req -in server-req.pem -days 365000 \
-CA ca.pem -CAkey ca-key.pem -set_serial 01 \
-out server-cert.pem# openssl verify -CAfile ca.pem server-cert.pem
server-cert.pem: OKMariaDB 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 and you need to configure.
Mandatory system variables and options for TLS include:
Useful system variables and options for TLS include:
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 , such as [mariadb] or [server]. For example:
Restart the server.
Connect to the server using :
Confirm that TLS is enabled by confirming that the have_ssl system variable is YES with the SHOW GLOBAL VARIABLES statement:
This page is: Copyright © 2025 MariaDB. All rights reserved.
X509 cert in PEM format
X509 key in PEM format
JCA file in PEM format
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.
[mariadb]
...
ssl_cert = /certs/server-cert.pem
ssl_key = /certs/server-key.pem
ssl_ca = /certs/ca-cert.pem$ sudo systemctl restart mariadb$ sudo mariadbSHOW GLOBAL VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl | YES |
+---------------+-------+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
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:
Restart the server.
Connect to the server using MariaDB Client:
Confirm that TLS is enabled by confirming that the have_ssl system variable is YES with the SHOW GLOBAL VARIABLES statement:
This page is: Copyright © 2025 MariaDB. All rights reserved.
[mariadb]
...
ssl_cert = /certs/server-cert.pem
ssl_key = /certs/server-key.pem
ssl_ca = /certs/ca-cert.pem$ sudo systemctl restart mariadb$ sudo mariadbSHOW GLOBAL VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl | YES |
+---------------+-------+By default, MariaDB replicates data between primaries and replicas without encrypting it. This is generally acceptable when the primary and replica run are in networks where security is guaranteed through other means. However, in cases where the primary and replica exist on separate networks or they are in a high-risk network, the lack of encryption does introduce security concerns as a malicious actor could potentially eavesdrop on the traffic as it is sent over the network between them.
To mitigate this concern, MariaDB allows you to encrypt replicated data in transit between primaries and replicas using the Transport Layer Security (TLS) protocol. TLS was formerly known as Secure Socket Layer (SSL), but strictly speaking the SSL protocol is a predecessor to TLS and, that version of the protocol is now considered insecure. The documentation still uses the term SSL often and for compatibility reasons TLS-related server system and status variables still use the prefix ssl_, but internally, MariaDB only supports its secure successors.
In order to secure connections between the primary and replica, you need to ensure that both servers were compiled with TLS support. See to determine how to check whether a server was compiled with TLS support.
You also need an X509 certificate, a private key, and the Certificate Authority (CA) chain to verify the X509 certificate for the primary. If you want to use two-way TLS, then you will also an X509 certificate, a private key, and the Certificate Authority (CA) chain to verify the X509 certificate for the replica. If you want to use self-signed certificates that are created with OpenSSL, then see for information on how to create those.
In order to secure replication traffic, you will need to ensure that TLS is enabled on the primary. If you want to use two-way TLS, then you will also need to ensure that TLS is enabled on the replica. See for information on how to do that.
For example, to set the TLS system variables for each server, add them to a relevant server in an on each server:
And then restart the server to make the changes persistent.
At this point, you can reconfigure the replicas to use TLS to encrypt replicated data in transit. There are two methods available to do this:
Executing the statement to set the relevant TLS options.
Setting TLS client options in an .
TLS can be enabled on a replication replica by executing the statement. In order to do so, there are a number of options that you would need to set. The specific options that you would need to set would depend on whether you want one-way TLS or two-way TLS, and whether you want to verify the server certificate.
Two-way TLS means that both the client and server provide a private key and an X509 certificate. It is called "two-way" TLS because both the client and server can be authenticated. In this case, the "client" is the replica. To configure two-way TLS, you would need to set the following options:
You need to set the path to the server's certificate by setting the option.
You need to set the path to the server's private key by setting the option.
You need to set the path to the certificate authority (CA) chain that can verify the server's certificate by setting either the or the options.
If you want , then you also need to set the option (enabled by default from
If the are currently running, you first need to stop them by executing the statement. For example:
Then, execute the statement to configure the replica to use TLS. For example:
At this point, you can start replication by executing the statement. For example:
The replica now uses TLS to encrypt data in transit as it replicates it from the primary.
Enabling One-Way TLS with CHANGE MASTER with Server Certificate Verification
One-way TLS means that only the server provides a private key and an X509 certificate. When TLS is used without a client certificate, it is called "one-way" TLS, because only the server can be authenticated, so authentication is only possible in one direction. However, encryption is still possible in both directions. means that the client verifies that the certificate belongs to the server. In this case, the "client" is the replica. This mode is enabled by default starting from . To configure one-way TLS in earlier versions, you would need to set the following options:
You need to set the path to the certificate authority (CA) chain that can verify the server's certificate by setting either the or the options.
You need to set the option.
If you want to restrict the server to certain ciphers, then you also need to set the option.
If the are currently running, you first need to stop them by executing the statement. For example:
Then, execute the statement to configure the replica to use TLS. For example:
At this point, you can start replication by executing the statement. For example:
The replica now uses TLS to encrypt data in transit as it replicates it from the primary.
Enabling One-Way TLS with CHANGE MASTER without Server Certificate Verification
One-way TLS means that only the server provides a private key and an X509 certificate. When TLS is used without a client certificate, it is called "one-way" TLS, because only the server can be authenticated, so authentication is only possible in one direction. However, encryption is still possible in both directions. In this case, the "client" is the replica. To configure two-way TLS without server certificate verification, you would need to set the following options:
You need to configure the replica to use TLS by setting the option.
If you want to restrict the server to certain ciphers, then you also need to set the option.
Starting from you need to disable the option.
If the are currently running, you first need to stop them by executing the statement. For example:
Then, execute the statement to configure the replica to use TLS. For example:
At this point, you can start replication by executing the statement. For example:
The replica now uses TLS to encrypt data in transit as it replicates it from the primary.
In cases where you don't mind restarting the server or you are setting the server up from scratch for the first time, you may find it more convenient to configure TLS options for replication through an . This is done the same way as it is for other clients. The specific options that you would need to set would depend on whether you want one-way TLS or two-way TLS, and whether you want to verify the server certificate. See for more information. For example, to enable two-way TLS with , then you could specify the following options in a relevant client in an :
Before you restart the server, you may also want to set the option in a server in an . This option prevents the from restarting automatically when the server starts. Instead, they will have to be restarted manually. After these changes have been made, you can restart the server. Once the server is back online, set the option by executing the statement. This will enable TLS. For example:
The certificate and keys will be read from the option file. At this point, you can start replication by executing the statement.
This page is licensed: CC BY-SA / Gnu FDL
Starting from 11.4 MariaDB, it encrypts the transmitted data between the server and clients by default unless the server and client run on the same host.
Before that the default behavior was to transmit the data unencrypted over the network introducing a security concerns as a malicious actor could potentially eavesdrop on the traffic as it is sent over the network between them.
The data in transit are encrypted (by default or if enabled manually) using the Transport Layer Security (TLS) protocol. TLS was formerly known as Secure Socket Layer (SSL), but strictly speaking the SSL protocol is a predecessor to TLS and, that version of the protocol is now considered insecure. The documentation still uses the term SSL often and for compatibility reasons TLS-related server system and status variables still use the prefix ssl_, but internally, MariaDB only supports its secure successors.
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).
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 system variable.
The FLUSH SSL command can be used to dynamically reinitialize the server's context.
See for more information.
Different 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. means that the client verifies that the certificate belongs to the server.
MariaDB starting with
Starting from (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 in an :
Or if you wanted to specify them on the command-line with the client, then you could execute something like this:
You can disable server certificate verification with
(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 in an , you could set the following:
Or if you wanted to specify them on the command-line with the client, then you could execute something like this:
Two-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 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 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 status variable. It will either show the TLS version used, or be empty when no encryption is in effect. For example:
From , the 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 , , or statements. For example:
A user account must connect via TLS if the user account is defined with the REQUIRE SSL clause.
A user account must connect via TLS with a specific cipher if the user account is defined with the REQUIRE CIPHER clause.
A user account must connect via TLS with a valid client certificate if the user account is defined with the REQUIRE X509 clause.
A user account must connect via TLS with a specific client certificate if the user account is defined with the REQUIRE SUBJECT clause.
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.
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:
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
If you want to restrict the server to certain ciphers, then you also need to set the MASTER_SSL_CIPHER option.
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:
And 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:
[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.pemSHOW VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl | YES |
+---------------+-------+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 .
[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.pemSTOP SLAVE;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;START SLAVE;STOP SLAVE;CHANGE MASTER TO
MASTER_SSL_CA = '/path/to/ca/ca.pem',
MASTER_SSL_VERIFY_SERVER_CERT=1;START SLAVE;STOP SLAVE;CHANGE MASTER TO
MASTER_SSL=1, MASTER_SSL_VERIFY_SERVER_CERT=0;START SLAVE;[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-certCHANGE MASTER TO
MASTER_SSL=1;START SLAVE;[client-mariadb]
...
ssl_ca = /etc/my.cnf.d/certificates/ca.pem
ssl-verify-server-cert$ mariadb -u myuser -p -h myserver.mydomain.com \
--ssl-ca=/etc/my.cnf.d/certificates/ca.pem \
--ssl-verify-server-cert[client-mariadb]
disable-ssl-verify-server-cert[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-cert$ 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-certSHOW SESSION STATUS LIKE 'Ssl_version';
+---------------+---------------------------+
| Variable_name | Value |
+---------------+---------------------------+
| Ssl_version | TLSv1.3 |
+---------------+---------------------------+
1 row in set (0.00 sec)ALTER USER 'alice'@'%'
REQUIRE SSL;ALTER USER 'alice'@'%'
REQUIRE CIPHER 'ECDH-RSA-AES256-SHA384';ALTER USER 'alice'@'%'
REQUIRE X509;ALTER USER 'alice'@'%'
REQUIRE SUBJECT '/CN=alice/O=My Dom, Inc./C=US/ST=Oregon/L=Portland';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';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';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.
I this system variable shows YES, the server is linked with OpenSSL.
See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.
Scope: Global
Dynamic: No
Description: 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 system variable to determine whether the server is using OpenSSL or MariaDB's bundled TLS library. See for more information about which libraries are used on which platforms.
Scope: Global
Dynamic: No
Description: 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.
Command line: --ssl-ca=file_name
Scope: Global
Dynamic: No
Data Type: file name
Description: Defines a path to a directory that contains one or more PEM files that should each contain one X509 certificate for a trusted Certificate Authority (CA) to use for 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.
Command line: --ssl-capath=directory_name
Scope: Global
Dynamic: No
Data Type: directory name
Command line: --ssl-cert=name
Scope: Global
Dynamic: No
Data Type: file name
Default Value: None
Description: 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.
Command line: --ssl-cipher=name
Scope: Global
Dynamic: No
Data Type: string
Default Value: None
Description: 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.
Command line: --ssl-crl=name
Scope: Global
Dynamic: No
Data Type: file name
Default Value: None
Description: Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for 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.
Command line: --ssl-crlpath=name
Scope: Global
Dynamic: No
Data Type: directory name
Default Value: None
Command line: --ssl-key=name
Scope: Global
Dynamic: No
Data Type: string
Default Value: None
Description: SSL certificate key passphrase. Works similarly to the --passout/--passin openssl command-line parameters. The pass phrase value can be formatted as follows:
pass:password — Provide the actual password.
env:var — Obtain the password from the environment variable var.
file:filename — Read the password from the specified file filename. Only the first line, up to the newline character, is read from the stream.
If ssl_passphrase is set, shows one of file:, env:, or pass: , and doesn't reveal sensitive data.
Command line: --ssl-passphrase=val
Scope: Global
Dynamic: No
Data Type: string
Default Value: None
Introduced:
Description: This system variable accepts a comma-separated list (with no whitespaces) of TLS protocol versions. A TLS protocol version will only be enabled if it is present in this list. All other TLS protocol versions will not be permitted.
See Secure Connections Overview: TLS Protocol Versions for more information.
Command line: --tls-version=value
Scope: Global
Dynamic: No
Data Type: enumerated
Default Value:
TLSv1.1,TLSv1.2,TLSv1.3 (<= , , )
TLSv1.2,TLSv1.3 (>= , , and later versions)
Valid Values: TLSv1.0,TLSv1.1,TLSv1.2,TLSv1.3
Introduced:
Description: 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
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 system variable. For example:
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 or , or dynamically linked with the system's TLS and cryptography library, which might be , , or .
See 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 recommends using a minimum protocol version of TLSv1.2.
On the server side, users can enable specific TLS protocol versions by setting the 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 or it can be specified in a relevant server in an . For example:
You can check which TLS protocol versions are enabled on a server by executing . For example:
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 in an , you could set the following:
Or if you wanted to specify it on the command-line with the client, then you could execute something like this:
The TLS protocol versions that are supported depend on the underlying TLS library used by the specific MariaDB binary.
See for more information about which libraries are used by the server and by clients on each platform.
MariaDB binaries built with the library ( or later) support TLSv1.1 and TLSv1.2 since , , and .
MariaDB binaries built with the library ( or later) support TLSv1.3 since and .
If your MariaDB Server binary is built with , then you can set the 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 for more information about that.
Note that the TLSv1.3 ciphers cannot be excluded when using , even by using the system variable. See for details.
SSLv3.0 is known to be vulnerable to the , so it should not be used. SSLv2.0 and SSLv3.0 are disabled for MariaDB Server binaries linked with since , , and . 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 .
MariaDB binaries built with the bundled library support TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3.
MariaDB binaries built with the bundled library support SSLv3.0, TLSv1.0, and TLSv1.1.
SSLv3.0 is known to be vulnerable to the , so it should not be used. SSLv2.0 and SSLv3.0 are disabled for MariaDB Server binaries linked with since , , and .
MariaDB binaries built with the library support different versions of TLS on different versions of Windows. See the documentation from Microsoft to determine which versions of TLS are supported on each version of Windows.
MariaDB binaries built with the library support TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3.
See 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 and options.
The 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 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 option is only supported if the server or client was built with , , or . If the client was built with or , then the option is not supported.
See for more information about which libraries are used on which platforms.
The directory specified by needs to be run through the command. For example, if the following is configured:
Then you would have to execute the following:
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 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 and options.
The 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 option is only valid if the server was built with OpenSSL. If the server was built with or , then the option is not supported. For clients, the option is only valid if the client was built with or . Likewise, if the client was built with , or , then the option is not supported.
The 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 option is only supported if the server or client was built with . If the server was built with or , then the option is not supported. Likewise, if the client was built with , , , or , then the option is not supported.
See for more information about which libraries are used on which platforms.
The directory specified by needs to be run through the command. For example, if the following is configured:
Then you would have to execute the following:
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.
enable all these checks by default. Last two checks can be disabled with an option, such as disable-ssl-verify-server-cert. Before , 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, will check the Common Name (CN) attribute located in the 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 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 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 .
See for more information about which libraries are used on which platforms.
SAN Support with OpenSSL, wolfSSL, and yaSSL
For built with ( or later), support for server certificate verification with subjectAltName fields that contain the server's host name was added in and . See for more information.
For built with ( or later), support for server certificate verification with subjectAltName fields that contain the server's IP address was added in , , , and . See 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 and functions. These functions are supported in the following TLS libraries:
1.0.2 or later
And they are not supported in the following TLS libraries:
MariaDB's were built with 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 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 , , , and , MariaDB's on RHEL 7 and CentOS 7 are built with OpenSSL 1.0.2. See for more information.
SAN Support with Schannel
For linked with , support for server certificate verification with subjectAltName fields was added in 3.0.2. See for more information.
SAN Support with GnuTLS
For linked with GnuTLS, support for server certificate verification with subjectAltName fields was added in 3.0.0. See 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 for more information.
(mariadb.org)
This page is licensed: CC BY-SA / Gnu FDL
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
SHOW GLOBAL VARIABLES LIKE 'have_ssl';
+---------------+----------+
| Variable_name | Value |
+---------------+----------+
| have_ssl | DISABLED |
+---------------+----------+[mariadb]
...
tls_version = TLSv1.2,TLSv1.3SHOW GLOBAL VARIABLES LIKE 'tls_version';[client-mariadb]
...
tls_version = TLSv1.2,TLSv1.3$ mariadb -u myuser -p -h myserver.mydomain.com \
--ssl \
--tls-version="TLSv1.2,TLSv1.3"ssl_capath=/etc/my.cnf.d/certificates/ca/openssl rehash /etc/my.cnf.d/certificates/ca/ssl_crlpath=/etc/my.cnf.d/certificates/crl/openssl rehash /etc/my.cnf.d/certificates/crl/