MySQL 8.0 Reference Manual Including MySQL NDB Cluster 8.0
MySQL supports multiple TLS protocols and ciphers, and enables configuring which protocols and ciphers to permit for encrypted connections. It is also possible to determine which protocol and cipher the current session uses.
MySQL supports encrypted connections using the TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3 protocols, listed in order from less secure to more secure. The set of protocols actually permitted for connections is subject to multiple factors:
MySQL configuration. Permitted TLS protocols can be configured on both the server side and client side to include only a subset of the supported TLS protocols. The configuration on both sides must include at least one protocol in common or connection attempts cannot negotiate a protocol to use. For details, see Connection TLS Protocol Negotiation.
System-wide host configuration. The host system may permit only certain TLS protocols, which means that MySQL connections cannot use nonpermitted protocols even if MySQL itself permits them:
Suppose that MySQL configuration permits TLSv1, TLSv1.1, and TLSv1.2, but your host system configuration permits only connections that use TLSv1.2 or higher. In this case, you cannot establish MySQL connections that use TLSv1 or TLSv1.1, even though MySQL is configured to permit them, because the host system does not permit them.
If MySQL configuration permits TLSv1, TLSv1.1, and TLSv1.2, but your host system configuration permits only connections that use TLSv1.3 or higher, you cannot establish MySQL connections at all, because no protocol permitted by MySQL is permitted by the host system.
Workarounds for this issue include:
Change the system-wide host configuration to permit
additional TLS protocols. Consult your operating system
documentation for instructions. For example, your system
may have an /etc/ssl/openssl.cnf file
that contains these lines to restrict TLS protocols to
TLSv1.2 or higher:
[system_default_sect] MinProtocol = TLSv1.2
Changing the value to a lower protocol version or
None makes the system more
permissive. This workaround has the disadvantage that
permitting lower (less secure) protocols may have
adverse security consequences.
If you cannot or prefer not to change the host system TLS configuration, change MySQL applications to use higher (more secure) TLS protocols that are permitted by the host system. This may not be possible for older versions of MySQL that support only lower protocol versions. For example, TLSv1 is the only supported protocol prior to MySQL 5.6.46, so attempts to connect to a pre-5.6.46 server fail even if the client is from a newer MySQL version that supports higher protocol versions. In such cases, an upgrade to a version of MySQL that supports additional TLS versions may be required.
The SSL library. If the SSL library does not support a particular protocol, neither does MySQL, and any parts of the following discussion that specify that protocol do not apply.
Support for the TLSv1.3 protocol is available as of MySQL 8.0.16 (as of MySQL 8.0.18 for the Group Replication component). In addition, to use TLSv1.3, both the MySQL server and the client application must be compiled using OpenSSL 1.1.1 or higher.
On the server side, the value of the
tls_version system variable
determines which TLS protocols a MySQL server permits for
encrypted connections. The
tls_version value applies to
connections from clients, regular source/replica replication
connections where this server instance is the source, Group
Replication group communication connections, and Group
Replication distributed recovery connections where this server
instance is the donor. The variable value is a list of one or
more comma-separated protocol versions from this list (not
case-sensitive): TLSv1, TLSv1.1, TLSv1.2, and (if available)
TLSV1.3. By default, this variable lists all protocols supported
by the SSL library used to compile MySQL. To determine the value
of tls_version at runtime, use
this statement:
mysql> SHOW GLOBAL VARIABLES LIKE 'tls_version';
+---------------+-----------------------+
| Variable_name | Value |
+---------------+-----------------------+
| tls_version | TLSv1,TLSv1.1,TLSv1.2 |
+---------------+-----------------------+
To change the value of
tls_version, set it at server
startup. For example, to permit connections that use the TLSv1.1
or TLSv1.2 protocol, but prohibit connections that use the
less-secure TLSv1 protocol, use these lines in the server
my.cnf file:
[mysqld] tls_version=TLSv1.1,TLSv1.2
To be even more restrictive and permit only TLSv1.2 connections,
set tls_version like this:
[mysqld] tls_version=TLSv1.2
As of MySQL 8.0.16, tls_version can also be
changed at runtime. See
Server-Side Runtime Configuration and Monitoring for Encrypted
Connections.
On the client side, the
--tls-version option specifies
which TLS protocols a client program permits for connections to
the server. The format of the option value is the same as for
the tls_version system variable
described previously (a list of one or more comma-separated
protocol versions).
For source/replica replication connections where this server
instance is the replica, the
SOURCE_TLS_VERSION |
MASTER_TLS_VERSION option for the
CHANGE REPLICATION SOURCE TO
statement (from MySQL 8.0.23) or CHANGE
MASTER TO statement (before MySQL 8.0.23) specifies
which TLS protocols the replica permits for connections to the
source. The format of the option value is the same as for the
tls_version system variable
described previously. See
Section 17.3.1, “Setting Up Replication to Use Encrypted Connections”.
The protocols that can be specified for
SOURCE_TLS_VERSION |
MASTER_TLS_VERSION depend on the SSL library.
This option is independent of and not affected by the server
tls_version value. For example,
a server that acts as a replica can be configured with
tls_version set to TLSv1.3 to
permit only incoming connections that use TLSv1.3, but also
configured with SOURCE_TLS_VERSION |
MASTER_TLS_VERSION set to TLSv1.2 to permit
only TLSv1.2 for outgoing replica connections to the source.
For Group Replication distributed recovery connections where
this server instance is the joining member that initiates
distributed recovery (that is, the client), the
group_replication_recovery_tls_version
system variable specifies which protocols are permitted by the
client. This option is independent of and not affected by the
server tls_version value, which
applies when this server instance is the donor. A Group
Replication server generally participates in distributed
recovery both as a donor and as a joining member over the course
of its group membership, so both these system variables should
be set. See
Section 18.5.2, “Securing Group Communication Connections with Secure Socket Layer (SSL)”.
TLS protocol configuration affects which protocol a given connection uses, as described in Connection TLS Protocol Negotiation.
Permitted protocols should be chosen such as not to leave “holes” in the list. For example, these server configuration values do not have holes:
tls_version=TLSv1,TLSv1.1,TLSv1.2,TLSv1.3 tls_version=TLSv1.1,TLSv1.2,TLSv1.3 tls_version=TLSv1.2,TLSv1.3 tls_version=TLSv1.3
These values do have holes and should not be used:
tls_version=TLSv1,TLSv1.2(TLSv1.1 is missing)tls_version=TLSv1.1,TLSv1.3(TLSv1.2 is missing)
The prohibition on holes also applies in other configuration contexts, such as for clients or replicas.
The list of permitted protocols should not be empty. If you set a TLS version parameter to the empty string, encrypted connections cannot be established:
tls_version: The server
does not permit encrypted incoming connections.
--tls-version: The client
does not permit encrypted outgoing connections to the
server.
MASTER_TLS_VERSION: The replica does not
permit encrypted outgoing connections to the source.
A default set of ciphers applies to encrypted connections, which can be overridden by explicitly configuring the permitted ciphers. During connection establishment, both sides of a connection must permit some cipher in common or the connection fails. Of the permitted ciphers common to both sides, the SSL library chooses the one supported by the provided certificate that has the highest priority.
To specify a cipher or ciphers applicable for encrypted connections that use TLS protocols up through TLSv1.2:
Set the ssl_cipher system
variable on the server side, and use the
--ssl-cipher option for
client programs.
For regular source/replica replication connections, where
this server instance is the source, set the
ssl_cipher system variable.
Where this server instance is the replica, use the
SOURCE_SSL_CIPHER |
MASTER_SSL_CIPHER option for the
CHANGE REPLICATION SOURCE TO
statement (from MySQL 8.0.23) or CHANGE
MASTER TO statement (before MySQL 8.0.23). See
Section 17.3.1, “Setting Up Replication to Use Encrypted Connections”.
For a Group Replication group member, for Group Replication
group communication connections and also for Group
Replication distributed recovery connections where this
server instance is the donor, set the
ssl_cipher system variable.
For Group Replication distributed recovery connections where
this server instance is the joining member, use the
group_replication_recovery_ssl_cipher
system variable. See
Section 18.5.2, “Securing Group Communication Connections with Secure Socket Layer (SSL)”.
For encrypted connections that use TLSv1.3, OpenSSL 1.1.1 and higher supports the following ciphersuites, the first three of which are enabled by default:
TLS_AES_128_GCM_SHA256 TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 TLS_AES_128_CCM_SHA256 TLS_AES_128_CCM_8_SHA256
To configure the permitted TLSv1.3 ciphersuites explicitly, set the following parameters. In each case, the configuration value is a list of zero or more colon-separated ciphersuite names.
On the server side, use the
tls_ciphersuites system
variable. If this variable is not set, its default value is
NULL, which means that the server permits
the default set of ciphersuites. If the variable is set to
the empty string, no ciphersuites are enabled and encrypted
connections cannot be established.
On the client side, use the
--tls-ciphersuites option.
If this option is not set, the client permits the default
set of ciphersuites. If the option is set to the empty
string, no ciphersuites are enabled and encrypted
connections cannot be established.
For regular source/replica replication connections, where
this server instance is the source, use the
tls_ciphersuites system
variable. Where this server instance is the replica, use the
SOURCE_TLS_CIPHERSUITES |
MASTER_TLS_CIPHERSUITES option for the
CHANGE REPLICATION SOURCE TO
statement (from MySQL 8.0.23) or CHANGE
MASTER TO statement (before MySQL 8.0.23). See
Section 17.3.1, “Setting Up Replication to Use Encrypted Connections”.
For a Group Replication group member, for Group Replication
group communication connections and also for Group
Replication distributed recovery connections where this
server instance is the donor, use the
tls_ciphersuites system
variable. For Group Replication distributed recovery
connections where this server instance is the joining
member, use the
group_replication_recovery_tls_ciphersuites
system variable. See
Section 18.5.2, “Securing Group Communication Connections with Secure Socket Layer (SSL)”.
Ciphersuite support is available as of MySQL 8.0.16, but requires that both the MySQL server and the client application be compiled using OpenSSL 1.1.1 or higher.
In MySQL 8.0.16 through 8.0.18, the
group_replication_recovery_tls_ciphersuites
system variable and the
SOURCE_TLS_CIPHERSUITES |
MASTER_TLS_CIPHERSUITES option for the
CHANGE REPLICATION SOURCE TO
statement (from MySQL 8.0.23) or CHANGE
MASTER TO statement (before MySQL 8.0.23) are not
available. In these releases, if TLSv1.3 is used for
source/replica replication connections, or in Group
Replication for distributed recovery (supported from MySQL
8.0.18), the replication source or Group Replication donor
servers must permit the use of at least one TLSv1.3
ciphersuite that is enabled by default. From MySQL 8.0.19, you
can use the options to configure client support for any
selection of ciphersuites, including only non-default
ciphersuites if you want.
A given cipher may work only with particular TLS protocols, which affects the TLS protocol negotiation process. See Connection TLS Protocol Negotiation.
To determine which ciphers a given server supports, check the
session value of the
Ssl_cipher_list status
variable:
SHOW SESSION STATUS LIKE 'Ssl_cipher_list';
The Ssl_cipher_list status
variable lists the possible SSL ciphers (empty for non-SSL
connections). If MySQL supports TLSv1.3, the value includes the
possible TLSv1.3 ciphersuites.
For encrypted connections that use TLS.v1.3, MySQL uses the SSL library default ciphersuite list.
For encrypted connections that use TLS protocols up through TLSv1.2, MySQL passes the following default cipher list to the SSL library.
ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES128-SHA256 ECDHE-RSA-AES128-SHA256 ECDHE-ECDSA-AES256-SHA384 ECDHE-RSA-AES256-SHA384 DHE-RSA-AES128-GCM-SHA256 DHE-DSS-AES128-GCM-SHA256 DHE-RSA-AES128-SHA256 DHE-DSS-AES128-SHA256 DHE-DSS-AES256-GCM-SHA384 DHE-RSA-AES256-SHA256 DHE-DSS-AES256-SHA256 ECDHE-RSA-AES128-SHA ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES256-SHA ECDHE-ECDSA-AES256-SHA DHE-DSS-AES128-SHA DHE-RSA-AES128-SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA AES128-GCM-SHA256 DH-DSS-AES128-GCM-SHA256 ECDH-ECDSA-AES128-GCM-SHA256 AES256-GCM-SHA384 DH-DSS-AES256-GCM-SHA384 ECDH-ECDSA-AES256-GCM-SHA384 AES128-SHA256 DH-DSS-AES128-SHA256 ECDH-ECDSA-AES128-SHA256 AES256-SHA256 DH-DSS-AES256-SHA256 ECDH-ECDSA-AES256-SHA384 AES128-SHA DH-DSS-AES128-SHA ECDH-ECDSA-AES128-SHA AES256-SHA DH-DSS-AES256-SHA ECDH-ECDSA-AES256-SHA DHE-RSA-AES256-GCM-SHA384 DH-RSA-AES128-GCM-SHA256 ECDH-RSA-AES128-GCM-SHA256 DH-RSA-AES256-GCM-SHA384 ECDH-RSA-AES256-GCM-SHA384 DH-RSA-AES128-SHA256 ECDH-RSA-AES128-SHA256 DH-RSA-AES256-SHA256 ECDH-RSA-AES256-SHA384 ECDHE-RSA-AES128-SHA ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES256-SHA ECDHE-ECDSA-AES256-SHA DHE-DSS-AES128-SHA DHE-RSA-AES128-SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA AES128-SHA DH-DSS-AES128-SHA ECDH-ECDSA-AES128-SHA AES256-SHA DH-DSS-AES256-SHA ECDH-ECDSA-AES256-SHA DH-RSA-AES128-SHA ECDH-RSA-AES128-SHA DH-RSA-AES256-SHA ECDH-RSA-AES256-SHA DES-CBC3-SHA
These cipher restrictions are in place:
The following ciphers are permanently restricted:
!DHE-DSS-DES-CBC3-SHA !DHE-RSA-DES-CBC3-SHA !ECDH-RSA-DES-CBC3-SHA !ECDH-ECDSA-DES-CBC3-SHA !ECDHE-RSA-DES-CBC3-SHA !ECDHE-ECDSA-DES-CBC3-SHA
The following categories of ciphers are permanently restricted:
!aNULL !eNULL !EXPORT !LOW !MD5 !DES !RC2 !RC4 !PSK !SSLv3
If the server is started with the
ssl_cert system variable set to
a certificate that uses any of the preceding restricted ciphers
or cipher categories, the server starts with support for
encrypted connections disabled.
Connection attempts in MySQL negotiate use of the highest TLS protocol version available on both sides for which a protocol-compatible encryption cipher is available on both sides. The negotiation process depends on factors such as the SSL library used to compile the server and client, the TLS protocol and encryption cipher configuration, and which key size is used:
For a connection attempt to succeed, the server and client TLS protocol configuration must permit some protocol in common.
Similarly, the server and client encryption cipher configuration must permit some cipher in common. A given cipher may work only with particular TLS protocols, so a protocol available to the negotiation process is not chosen unless there is also a compatible cipher.
If TLSv1.3 is available, it is used if possible. (This means
that server and client configuration both must permit
TLSv1.3, and both must also permit some TLSv1.3-compatible
encryption cipher.) Otherwise, MySQL continues through the
list of available protocols, using TLSv1.2 if possible, and
so forth. Negotiation proceeds from more secure protocols to
less secure. Negotiation order is independent of the order
in which protocols are configured. For example, negotiation
order is the same regardless of whether
tls_version has a value of
TLSv1,TLSv1.1,TLSv1.2,TLSv1.3 or
TLSv1.3,TLSv1.2,TLSv1.1,TLSv1.
TLSv1.2 does not work with all ciphers that have a key size
of 512 bits or less. To use this protocol with such a key,
set the ssl_cipher system
variable on the server side or use the
--ssl-cipher client option
to specify the cipher name explicitly:
AES128-SHA AES128-SHA256 AES256-SHA AES256-SHA256 CAMELLIA128-SHA CAMELLIA256-SHA DES-CBC3-SHA DHE-RSA-AES256-SHA RC4-MD5 RC4-SHA SEED-SHA
For better security, use a certificate with an RSA key size of at least 2048 bits.
If the server and client do not have a permitted protocol in common, and a protocol-compatible cipher in common, the server terminates the connection request. Examples:
If the server is configured with
tls_version=TLSv1.1,TLSv1.2:
Connection attempts fail for clients invoked with
--tls-version=TLSv1, and
for older clients that support only TLSv1.
Similarly, connection attempts fail for replicas
configured with MASTER_TLS_VERSION =
'TLSv1', and for older replicas that support
only TLSv1.
If the server is configured with
tls_version=TLSv1 or is an
older server that supports only TLSv1:
Connection attempts fail for clients invoked with
--tls-version=TLSv1.1,TLSv1.2.
Similarly, connection attempts fail for replicas
configured with MASTER_TLS_VERSION =
'TLSv1.1,TLSv1.2'.
MySQL permits specifying a list of protocols to support. This
list is passed directly down to the underlying SSL library and
is ultimately up to that library what protocols it actually
enables from the supplied list. Please refer to the MySQL source
code and the OpenSSL
SSL_CTX_new()
documentation for information about how the SSL library handles
this.
To determine which encryption TLS protocol and cipher the
current client session uses, check the session values of the
Ssl_version and
Ssl_cipher status variables:
mysql>SELECT * FROM performance_schema.session_statusWHERE VARIABLE_NAME IN ('Ssl_version','Ssl_cipher');+---------------+---------------------------+ | VARIABLE_NAME | VARIABLE_VALUE | +---------------+---------------------------+ | Ssl_cipher | DHE-RSA-AES128-GCM-SHA256 | | Ssl_version | TLSv1.2 | +---------------+---------------------------+
If the connection is not encrypted, both variables have an empty value.