Secure Connections Overview

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 have_ssl system variable. For example:

SHOW GLOBAL VARIABLES LIKE 'have_ssl';
+---------------+----------+
| Variable_name | Value    |
+---------------+----------+
| have_ssl      | DISABLED |
+---------------+----------+

The possible values are:

  • If it is DISABLED, then the server was compiled with TLS support, but TLS is not enabled.
  • If it is YES, then the server was compiled with TLS support, and TLS is enabled.
  • If it is NO, then the server was not compiled with TLS support.

TLS Protocol Version Support

TLS Protocol Version Support in OpenSSL

MariaDB Server binaries linked with the OpenSSL libraries support TLSv1.1 and TLSv1.2 since MariaDB 5.5.41, MariaDB 10.0.15, and MariaDB 10.1.4.

MariaDB Server binaries linked with the OpenSSL libraries (OpenSSL 1.1.1 or later) support TLSv1.3 since MariaDB 10.2.16 and MariaDB 10.3.8.

SSLv3.0 is known to be vulnerable to the POODLE attack. SSLv2.0 and SSLv3.0 are disabled for MariaDB Server binaries linked with OpenSSL since MariaDB 5.5.41, MariaDB 10.0.15, and MariaDB 10.1.4. If you are using a MariaDB version older than that and you cannot upgrade, then please see the section titled "SSL 3.0 Fallback protection" in OpenSSL Security Advisory - 15 Oct 2014.

If your MariaDB Server binary is linked with OpenSSL, then you can set the ssl_cipher system variable to values like SSLv3 or TLSv1.2 to allow all SSLv3.0 or all TLSv1.2 ciphers. However, this does not necessarily limit the protocol version to TLSv1.2. See MDEV-14101 for more information about that.

Note that the TLSv1.3 ciphers cannot be excluded when using OpenSSL, even by using the ssl_cipher system variable. See Using TLSv1.3 for details.

TLS Protocol Version Support in yaSSL

MariaDB Server binaries linked with the bundled yaSSL libraries support SSLv3.0, TLSv1.0, and TLSv1.1. SSLv3.0 is known to be vulnerable to the POODLE attack, so it should not be used.

TLS Protocol Version Support in Schannel

MariaDB Connector/C 3.0 and later are linked with Schannel on Windows. In MariaDB 10.2 and later, many of the clients and utilities bundled with MariaDB Server are linked with MariaDB Connector/C 3.0 and later, so this also means that these clients and utilities would also be linked with Schannel on Windows.

See the Protocols in TLS/SSL (Schannel SSP) documentation from Microsoft to determine which versions of TLS are supported on each version of Windows.

TLS Libraries

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

See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.

Enabling TLS

See Securing Connections for Client and Server 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 ssl_ca and ssl_capath options.

The ssl_ca option defines a path to a PEM file that should contain one or more X509 certificates for trusted Certificate Authorities (CAs). This option requires that you use the absolute path, not a relative path.

The ssl_capath option defines a path to a directory that contains one or more PEM files that should each contain one X509 certificate for a trusted Certificate Authority (CA). This option requires that you use the absolute path, not a relative path. The ssl_capath option is only supported if the server or client was built with OpenSSL or yaSSL. If the client was built with Schannel, then the ssl_capath option is not supported.

See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.

The directory specified by ssl_capath needs to be run through the openssl rehash command. For example, if the following is configured:

ssl_ca=/etc/my.cnf.d/certificates/ca/

Then you would have to execute the following:

openssl rehash /etc/my.cnf.d/certificates/ca/

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 Securing Connections for Client and Server: Requiring TLS 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 ssl_crl and ssl_crlpath options.

The ssl_crl option defines a path to a PEM file that should contain one or more X509 revoked certificates. This option requires that you use the absolute path, not a relative path. For servers, the ssl_crl option is only valid if the server was built with OpenSSL. If the server was built with yaSSL, then the ssl_crl option is not supported. For clients, the ssl_crl option is only valid if the client was built with OpenSSL or Schannel. Likewise, if the client was built with yaSSL, then the ssl_crl option is not supported.

The ssl_crlpath option defines a path to a directory that contains one or more PEM files that should each contain one revoked X509 certificate. This option requires that you use the absolute path, not a relative path. The ssl_crlpath option is only supported if the server or client was built with OpenSSL. If the server was built with yaSSL, then the ssl_crlpath option is not supported. Likewise, if the client was built with yaSSL or Schannel, then the ssl_crlpath option is not supported.

See TLS and Cryptography Libraries Used by MariaDB for more information about which libraries are used on which platforms.

The directory specified by ssl_crlpath needs to be run through the openssl rehash command. For example, if the following is configured:

ssl_crl=/etc/my.cnf.d/certificates/crl/

Then you would have to execute the following:

openssl rehash /etc/my.cnf.d/certificates/crl/

Server Certificate Verification

Clients and utilities verify a server certificate by checking the server's host name and IP address against certain attributes in the certificate. For most clients and utilities, server certificate verification is disabled by default, and it is only enabled if an option, such as ssl-verify-server-cert is specified.

To verify the server's certificate, clients and utilities will check the Common Name (CN) attribute located in the Subject field of the certificate against the server's host name and IP address. If the Common Name (CN) matches either of those, then the certificate is verified.

The Subject Alternative Name (SAN) field, which is an X.509v3 extension, can also be used for server certificate verification, if it is present in the server certificate. This field is also sometimes called subjectAltName.

Support for server certificate verification with the subjectAltName field was added in MariaDB 10.1.23 for clients and utilities linked with OpenSSL 1.0.2 or later. See MDEV-10594 about that. When using supported clients and utilities, if the server certificate contains any subjectAltName fields, then those fields will also be checked against the server's host name.

On RHEL and CentOS 7, MariaDB's RPM packages were built with OpenSSL 1.0.1 for a long time, even after OpenSSL 1.0.2 became available on the platform. As a side effect, the clients and utilities bundled in these packages did not support server certificate verification with the subjectAltName field, even if the packages were installed on a system that had OpenSSL 1.0.2 installed. Starting with MariaDB 10.2.23, MariaDB 10.3.14, and MariaDB 10.4.4, MariaDB's RPM packages on RHEL and CentOS 7 are built with OpenSSL 1.0.2. Therefore, these are the minimum required versions to support server certificate verification with the subjectAltName field when using the clients and utilities bundled in MariaDB's RPM packages on RHEL and CentOS 7. See MDEV-18277 for more information.

Some subjectAltName-related bugs are still open, such as:

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 Securing Connections for Client and Server: Requiring TLS for more information.

See Also

Comments

Comments loading...