MySQL 8.4 supports the TLSv1.2 and TLSv1.3 protocols for connections. To use TLSv1.3, both the MySQL server and the client application must be compiled using OpenSSL 1.1.1 or higher. The Group Replication component supports TLSv1.3 from MySQL 8.0.18 (for details, see Section 20.6.2, “Securing Group Communication Connections with Secure Socket Layer (SSL)”).

MySQL 8.4 does not support the old TLSv1 and TLSv1.1 protocols.

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.

The host system may permit only certain TLS protocols, which means that MySQL connections cannot use protocols not allowed by the host even if MySQL itself permits them. Possible workarounds for this issue include the following:

Support for the TLSv1 and TLSv1.1 connection protocols was deprecated and removed in MySQL 8.0. For background, refer to the IETF memo Deprecating TLSv1.0 and TLSv1.1. In MySQL 8.4, connections can be made using only the more secure TLSv1.2 and TLSv1.3 protocols. TLSv1.3 requires that both the MySQL server and the client application are compiled with OpenSSL 1.1.1.

For more information, see Does MySQL 8.4 support TLS 1.0 and 1.1?

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 administrative connection interface is configured similarly, but uses the admin_tls_version system variable (see Section 7.1.12.2, “Administrative Connection Management”). This discussion applies to admin_tls_version as well.

The tls_version value is a list of one or more comma-separated TLS protocol versions, which is not case-sensitive. By default, this variable lists all protocols that are supported by the SSL library used to compile MySQL and by the MySQL Server release. The default settings are therefore as shown in MySQL Server TLS Protocol Default Settings.

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.2,TLSv1.3       |
+---------------+-----------------------+

To change the value of tls_version, set it at server startup. For example, to permit connections that use the TLSv1.2 or TLSv1.3 protocol, but prohibit connections that use any other protocol, use these lines in the server my.cnf file:

[mysqld]
tls_version=TLSv1.2,TLSv1.3

To be even more restrictive and permit only TLSv1.3 connections, set tls_version like this:

[mysqld]
tls_version=TLSv1.3

tls_version can 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 option for the CHANGE REPLICATION SOURCE TO statement 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 19.3.1, “Setting Up Replication to Use Encrypted Connections”.

The protocols that can be specified for SOURCE_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 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. Again, 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 20.6.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.2,TLSv1.3
tls_version=TLSv1.3

The prohibition on holes also applies in other configuration contexts, such as for clients or replicas.

Unless you intend to disable encrypted connections, 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:

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 TLSv1.2:

For encrypted connections that use TLSv1.3, OpenSSL 1.1.1 and higher supports the following ciphersuites, all of which are enabled by default for use with server system variables --tls-ciphersuites or --admin-tls-ciphersuites:

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_CCM_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.

Ciphersuite support requires that both the MySQL server and the client application be compiled using OpenSSL 1.1.1 or higher.

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 TLSv1.2, MySQL passes the following default cipher list to the SSL library when used with the server system variables --ssl-cipher and --admin-ssl-cipher.

ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-CHACHA20-POLY1305
ECDHE-RSA-CHACHA20-POLY1305
ECDHE-ECDSA-AES256-CCM
ECDHE-ECDSA-AES128-CCM
DHE-RSA-AES128-GCM-SHA256
DHE-RSA-AES256-GCM-SHA384
DHE-RSA-AES256-CCM
DHE-RSA-AES128-CCM
DHE-RSA-CHACHA20-POLY1305

These cipher restrictions are in place:

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:

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.

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_status
       WHERE 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.