All pages
Powered by GitBook
1 of 9

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Data-in-Transit Encryption

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.

Certificate Creation with OpenSSL

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

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

Certificate Creation

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

Creating a Certificate Authority Private Key and Certificate

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

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

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

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

Creating a Private Key and a Self-signed Certificate

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

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

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

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

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

Certificate Verification

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

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

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

openssl
Let's Encrypt
openssl genrsa
openssl req
openssl req
openssl rsa
openssl x509
openssl verify
# 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: OK

Enabling TLS on MariaDB Server

Overview

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

TLS must be manually enabled on the server.

Enabling TLS

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

  2. Determine which and you need to configure.

Mandatory system variables and options for TLS include:

System Variable/Option
Description

Useful system variables and options for TLS include:

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

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

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

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

  1. Restart the server.

  1. Connect to the server using :

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

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

ssl_cert

X509 cert in PEM format

ssl_key

X509 key in PEM format

ssl_ca

JCA file in PEM format

require_secure_transport

When this option is enabled, connections attempted using insecure transport will be rejected. Secure transports are SSL/TLS, Unix sockets, or named pipes.

ssl_capath

CA directory

ssl_cipher

SSL cipher to use

ssl_crl

CRL file in PEM format

ssl_crlpath

CRL directory

tls_version

TLS protocol version for secure connections.

system variables
options
MariaDB Server
MariaDB Client
[mariadb]
...
ssl_cert = /certs/server-cert.pem
ssl_key = /certs/server-key.pem
ssl_ca = /certs/ca-cert.pem
$ sudo systemctl restart mariadb
$ sudo mariadb
SHOW GLOBAL VARIABLES LIKE 'have_ssl';

+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl      | YES   |
+---------------+-------+

Using TLSv1.3

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

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

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

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

See Also

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

Requiring TLS on MariaDB Server

Overview

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

TLS must be manually enabled on the server.

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

  2. Determine which system variables and options you need to configure. Mandatory system variables and options for TLS include:

System Variable/Option
Description

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:

System Variable/Option
Description

CA directory

SSL cipher to use

CRL file in PEM format

CRL directory

TLS protocol version for secure connections.

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

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

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

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

  1. Restart the server.

  1. Connect to the server using MariaDB Client:

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

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

MariaDB Server
[mariadb]
...
ssl_cert = /certs/server-cert.pem
ssl_key = /certs/server-key.pem
ssl_ca = /certs/ca-cert.pem
$ sudo systemctl restart mariadb
$ sudo mariadb
SHOW GLOBAL VARIABLES LIKE 'have_ssl';

+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl      | YES   |
+---------------+-------+
require_secure_transport
ssl_cert
ssl_key
ssl_ca
ssl_capath
ssl_cipher
ssl_crl
ssl_crlpath
tls_version

Replication with Secure Connections

The terms master and slave have historically been used in replication, and MariaDB has begun the process of adding primary and replica synonyms. The old terms will continue to be used to maintain backward compatibility - see MDEV-18777 to follow progress on this effort.

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

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

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

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

Securing Replication Traffic

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

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

And then restart the server to make the changes persistent.

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

  • Executing the statement to set the relevant TLS options.

  • Setting TLS client options in an .

Executing CHANGE MASTER

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

Enabling Two-Way TLS with CHANGE MASTER

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

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

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

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

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

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

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

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

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

Enabling One-Way TLS with CHANGE MASTER

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

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

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

  • You need to set the option.

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

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

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

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

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

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

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

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

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

  • Starting from you need to disable the option.

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

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

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

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

Setting TLS Client Options in an Option File

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

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

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

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

Securing Connections for Client and Server

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

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

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

Enabling TLS

Enabling TLS for MariaDB Server

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.

Reloading the Server's Certificates and Keys Dynamically

The FLUSH SSL command can be used to dynamically reinitialize the server's context.

See for more information.

Enabling TLS for MariaDB Clients

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.

Enabling One-Way TLS for MariaDB Clients

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.

Enabling Two-Way TLS for MariaDB Clients

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.

Enabling TLS for MariaDB Connector/C Clients

See the documentation on MariaDB Connector/C's for information on how to enable TLS for clients that use MariaDB Connector/C.

Enabling TLS for MariaDB Connector/ODBC Clients

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.

Enabling TLS for MariaDB Connector/J Clients

See the documentation on for information on how to enable TLS for clients that use MariaDB Connector/J.

Verifying that a Connection is Using TLS

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:

Requiring TLS

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.

Requiring TLS for Specific User Accounts

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.

Requiring TLS for Specific User Accounts from Specific Hosts

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.

  • Secure Connections Overview
    Certificate Creation with OpenSSL
    Securing Connections for Client and Server
    option group
    option file
    CHANGE MASTER
    option file
    CHANGE MASTER
    MASTER_SSL_CERT
    MASTER_SSL_KEY
    MASTER_SSL_CA
    MASTER_SSL_CAPATH
    server certificate verification
    MASTER_SSL_VERIFY_SERVER_CERT
    replica threads
    STOP SLAVE
    CHANGE MASTER
    START SLAVE
    Server certificate verification
    MASTER_SSL_CA
    MASTER_SSL_CAPATH
    MASTER_SSL_VERIFY_SERVER_CERT
    MASTER_SSL_CIPHER
    replica threads
    STOP SLAVE
    CHANGE MASTER
    START SLAVE
    MASTER_SSL
    MASTER_SSL_CIPHER
    MASTER_SSL_VERIFY_SERVER_CERT
    replica threads
    STOP SLAVE
    CHANGE MASTER
    START SLAVE
    option file
    Securing Connections for Client and Server: Enabling TLS for MariaDB Clients
    server certificate verification
    option group
    option file
    --skip-slave-start
    option group
    option file
    replica threads
    MASTER_SSL
    CHANGE MASTER
    START SLAVE

    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:

    ssl_cert
    TLS
    FLUSH SSL
    clients and utilities
    Server certificate verification
    11.4
    MariaDB 11.4
    option group
    option file
    mariadb
    option group
    option file
    mariadb
    Ssl_version
    require_secure_transport
    CREATE USER
    ALTER USER
    GRANT
    [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.pem
    SHOW VARIABLES LIKE 'have_ssl';
    
    +---------------+-------+
    | Variable_name | Value |
    +---------------+-------+
    | have_ssl      | YES   |
    +---------------+-------+

    SSL/TLS System Variables

    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 .

    Variables

    [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.pem
    STOP 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-cert
    CHANGE 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-cert
    SHOW 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_openssl
    • Description: 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

    have_ssl

    • 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

    ssl_ca

    • Description: Defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs) to use for 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

    ssl_capath

    • Description: Defines a path to a directory that contains one or more PEM files that should each contain one X509 certificate for a trusted Certificate Authority (CA) to use for 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

    ssl_cert

    • Description: Defines a path to the X509 certificate file 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.

    • Command line: --ssl-cert=name

    • Scope: Global

    • Dynamic: No

    • Data Type: file name

    • Default Value: None

    ssl_cipher

    • 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

    ssl_crl

    • 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

    ssl_crlpath

    • Description: Defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate to use for 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

    ssl_key

    • Description: Defines a path to a private key file 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.

    • Command line: --ssl-key=name

    • Scope: Global

    • Dynamic: No

    • Data Type: string

    • Default Value: None

    ssl_passphrase

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

      • pass:password — Provide the actual password.

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

    tls_version

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

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

    version_ssl_library

    • 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

    See Also

    • Secure Connections Overview

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

    • Full list of MariaDB options, system and status variables

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

    Secure Connections Overview
    have_openssl
    TLS and Cryptography Libraries Used by MariaDB
    SHOW VARIABLE
    MariaDB 12.0
    MariaDB 10.6.15
    MariaDB 10.11.5
    MariaDB 10.6.16
    MariaDB 10.11.6

    Secure Connections Overview

    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.

    Checking MariaDB Server for TLS Support

    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.

    TLS Libraries

    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.

    TLS Protocol Versions

    There are 4 versions of the TLS protocol:

    • TLSv1.0

    • TLSv1.1

    • TLSv1.2

    • TLSv1.3

    Enabling Specific TLS Protocol Versions

    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:

    TLS Protocol Version Support

    The TLS protocol versions that are supported depend on the underlying TLS library used by the specific MariaDB binary.

    TLS Library
    Supported TLS Protocol Versions

    See for more information about which libraries are used by the server and by clients on each platform.

    TLS Protocol Version Support in OpenSSL

    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 .

    TLS Protocol Version Support in wolfSSL

    MariaDB binaries built with the bundled library support TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3.

    TLS Protocol Version Support in yaSSL

    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 .

    TLS Protocol Version Support in Schannel

    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.

    TLS Protocol Version Support in GnuTLS

    MariaDB binaries built with the library support TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3.

    Enabling TLS

    See for information on how to enable TLS on the client and server.

    Certificate Verification

    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)

    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:

    Requiring a Specific Certificate Authority (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 for more information.

    Certificate Revocation Lists (CRLs)

    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:

    Server Certificate Verification

    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.

    Server Certificate Verification with Subject Alternative Names (SANs)

    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.

    Client Certificate Verification

    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.

    See Also

    • (mariadb.org)

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

    Replication with Secure Connections
  • SSL/TLS System Variables

  • Data-at-Rest Encryption

  • Cyberciti tutorial: How to setup MariaDB SSL and secure connections from clients

  • 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

    have_ssl
    wolfSSL
    yaSSL
    OpenSSL
    GnuTLS
    Schannel
    TLS and Cryptography Libraries Used by MariaDB
    PCI DSS v3.2
    tls_version
    mariadbd
    option group
    option file
    SHOW GLOBAL VARIABLES
    option group
    option file
    mariadb
    TLS and Cryptography Libraries Used by MariaDB
    OpenSSL
    OpenSSL 1.0.1
    OpenSSL
    OpenSSL 1.1.1
    OpenSSL
    ssl_cipher
    MDEV-14101
    OpenSSL
    ssl_cipher
    Using TLSv1.3
    POODLE attack
    OpenSSL
    OpenSSL Security Advisory - 15 Oct 2014
    wolfSSL
    yaSSL
    POODLE attack
    yaSSL
    Schannel
    Protocols in TLS/SSL (Schannel SSP)
    GnuTLS
    Securing Connections for Client and Server
    ssl_ca
    ssl_capath
    ssl_ca
    ssl_capath
    ssl_capath
    OpenSSL
    wolfSSL
    yaSSL
    GnuTLS
    Schannel
    ssl_capath
    TLS and Cryptography Libraries Used by MariaDB
    ssl_capath
    openssl rehash
    Securing Connections for Client and Server: Requiring TLS
    ssl_crl
    ssl_crlpath
    ssl_crl
    ssl_crl
    wolfSSL
    yaSSL
    ssl_crl
    ssl_crl
    OpenSSL
    Schannel
    GnuTLS
    wolfSSL
    yaSSL
    ssl_crl
    ssl_crlpath
    ssl_crlpath
    OpenSSL
    wolfSSL
    yaSSL
    ssl_crlpath
    GnuTLS
    Schannel
    wolfSSL
    yaSSL
    ssl_crlpath
    TLS and Cryptography Libraries Used by MariaDB
    ssl_crlpath
    openssl rehash
    Clients and utilities
    clients and utilities
    Subject
    Subject Alternative Name (SAN)
    client or utility
    client or utility
    TLS and Cryptography Libraries Used by MariaDB
    clients and utilities
    OpenSSL
    OpenSSL 1.0.2
    MDEV-10594
    clients and utilities
    OpenSSL
    OpenSSL 1.0.2
    MDEV-18131
    X509_check_host
    X509_check_ip
    OpenSSL
    wolfSSL
    yaSSL
    RPM packages
    OpenSSL
    clients and utilities
    RPM packages
    MDEV-18277
    clients and utilities
    Schannel
    CONC-250
    clients and utilities
    CONC-250
    Securing Connections for Client and Server: Requiring TLS
    Mission Impossible: Zero-Configuration SSL
    Securing Connections for Client and Server
    Using TLSv1.3
    Certificate Creation with OpenSSL
    SHOW GLOBAL VARIABLES LIKE 'have_ssl';
    +---------------+----------+
    | Variable_name | Value    |
    +---------------+----------+
    | have_ssl      | DISABLED |
    +---------------+----------+
    [mariadb]
    ...
    tls_version = TLSv1.2,TLSv1.3
    SHOW 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/
    TLS Options
    Using TLS/SSL with MariaDB Connector/J
    MariaDB Connector/C
    MariaDB Connector/C
    Securing Communications in Galera Cluster
    MariaDB 10.5.2
    MariaDB 11.3
    MariaDB 11.3
    MariaDB 11.3
    MariaDB 11.0.3
    MariaDB 11.0.4
    MariaDB 10.4.6
    MariaDB 5.5.41
    MariaDB 10.0.15
    MariaDB 10.1.4
    MariaDB 10.2.16
    MariaDB 10.3.8
    MariaDB 5.5.41
    MariaDB 10.0.15
    MariaDB 10.1.4
    MariaDB 5.5.41
    MariaDB 10.0.15
    MariaDB 10.1.4
    MariaDB 11.3
    MariaDB 10.1.23
    MariaDB 10.2.6
    MariaDB 10.1.39
    MariaDB 10.2.24
    MariaDB 10.3.15
    MariaDB 10.4.5
    MariaDB 10.1.39
    MariaDB 10.2.23
    MariaDB 10.3.14
    MariaDB 10.4.4