On the server side, the --ssl option specifies that the server permits but does not require encrypted connections. This option is enabled by default, so it need not be specified explicitly.

To require that clients connect using encrypted connections, enable the require_secure_transport system variable. See Configuring Encrypted Connections as Mandatory.

These options on the server side specify the certificate and key files the server uses when permitting clients to establish encrypted connections:

For example, to enable the server for encrypted connections, start it with these lines in the my.cnf file, changing the file names as necessary:

[mysqld]
ssl-ca=ca.pem
ssl-cert=server-cert.pem
ssl-key=server-key.pem

To specify in addition that clients are required to use encrypted connections, enable the require_secure_transport system variable:

[mysqld]
ssl-ca=ca.pem
ssl-cert=server-cert.pem
ssl-key=server-key.pem
require_secure_transport=ON

Each certificate and key option names a file in PEM format. Should you need to create the required certificate and key files, see Section 6.3.3, “Creating SSL and RSA Certificates and Keys”. MySQL servers compiled using OpenSSL can generate missing certificate and key files automatically at startup. See Section 6.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”. Alternatively, if you have a MySQL source distribution, you can test your setup using the demonstration certificate and key files in its mysql-test/std_data directory.

The server performs certificate and key file autodiscovery. If --ssl is enabled (possibly along with --ssl-cipher) and other --ssl-xxx options are not given to configure encrypted connections explicitly, the server attempts to enable encrypted connection support automatically at startup:

If the server automatically enables encrypted connection support, it writes a note to the error log. If the server discovers that the CA certificate is self-signed, it writes a warning to the error log. (The certificate is self-signed if created automatically by the server or manually using mysql_ssl_rsa_setup.)

MySQL also provides these options for server-side SSL control:

The values of the --ssl-xxx options set the values of the corresponding system variables (ssl_ca, ssl_cert, ssl_key, and so forth).

To explicitly specify which encryption protocols and ciphersuites the server permits for encrypted connections, use the tls_version and tls_ciphersuites system variables; see Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”. For example, you can set tls_version to prevent clients from using less-secure protocols.

Certain encryption-related system variables can be set at runtime: require_secure_transport, and (as of MySQL 8.0.16) tls_version and tls_ciphersuites. If changed with SET GLOBAL, the new values apply to connections established subsequent to the change, and apply only until server restart. If changed with SET PERSIST, the new values also apply to subsequent server restarts. See Section 13.7.6.1, “SET Syntax for Variable Assignment”.

In addition, as of MySQL 8.0.16, the SSL context the server uses for new connections is reconfigurable at runtime. This capability may be useful, for example, to avoid restarting a MySQL server that has been running so long that its SSL certificate has expired.

The server creates the initial SSL context from the values that the context-related system variables have at startup. It also initializes a set of context-related status variables to indicate the values used in the context. The following table shows the system variables that define the SSL context and the corresponding status variables that indicate the currently active context values.

To reconfigure the SSL context at runtime, use this procedure:

The members of each pair of system and status variables may have different values temporarily due to the way the reconfiguration procedure works:

In some cases, ALTER INSTANCE RELOAD TLS by itself may suffice to reconfigure the SSL context, without changing any system variables. Suppose that the certificate in the file named by ssl_cert has expired. It is sufficient to replace the existing file contents with a nonexpired certificate and execute ALTER INSTANCE RELOAD TLS to cause the new file contents to be read and used for new connections.

By default, the RELOAD TLS action rolls back with an error and has no effect if the configuration values do not permit creation of a new SSL context. The previous context values continue to be used for new connections.

If the optional NO ROLLBACK ON ERROR clause is given and a new context cannot be created, rollback does not occur. Instead, a warning is generated and SSL is disabled for new connections.

The server-side --ssl option has an effect only at server startup on whether the server accepts SSL connections. It is ignored by, and has no effect on the operation of, ALTER INSTANCE RELOAD TLS. For example, you can use --ssl=0 to start the server with SSL connections disabled, then reconfigure SSL and execute ALTER INSTANCE RELOAD TLS to enable SSL connections at runtime.

ALTER INSTANCE RELOAD TLS changes only the SSL context the server itself uses for new connections. It does not affect the SSL context used by other enabled server plugins or components such as X Plugin or Group Replication. If you want to apply the reconfiguration to Group Replication‘s group communication connections, which take their settings from the server‘s SSL context-related system variables, you must issue STOP GROUP_REPLICATION followed by START GROUP_REPLICATION to stop and restart Group Replication.

By default, MySQL client programs attempt to establish an encrypted connection if the server supports encrypted connections, with further control available through the --ssl-mode option:

Attempts to establish an unencrypted connection fail if the require_secure_transport system variable is enabled on the server side to cause the server to require encrypted connections. See Configuring Encrypted Connections as Mandatory.

The following options on the client side identify the certificate and key files clients use when establishing encrypted connections to the server. They are similar to the options used on the server side, but --ssl-cert and --ssl-key identify the client public and private key:

For additional security relative to that provided by the default encryption, clients can supply a CA certificate matching the one used by the server and enable host name identity verification. In this way, the server and client place their trust in the same CA certificate and the client verifies that the host to which it connected is the one intended:

MySQL also provides these options for client-side SSL control:

Depending on the encryption requirements of the MySQL account used by a client, the client may be required to specify certain options to connect using encryption to the MySQL server.

Suppose that you want to connect using an account that has no special encryption requirements or that was created using a CREATE USER statement that included the REQUIRE SSL clause. Assuming that the server supports encrypted connections, a client can connect using encryption with no --ssl-mode option or with an explicit --ssl-mode=PREFFERED option:

mysql

Or:

mysql --ssl-mode=PREFERRED

For an account created with a REQUIRE SSL clause, the connection attempt fails if an encrypted connection cannot be established. For an account with no special encryption requirements, the attempt falls back to an unencrypted connection if an encrypted connection cannot be established. To prevent fallback and fail if an encrypted connection cannot be obtained, connect like this:

mysql --ssl-mode=REQUIRED

If the account has more stringent security requirements, other options must be specified to establish an encrypted connection:

For additional information about the REQUIRE clause, see Section 13.7.1.3, “CREATE USER Statement”.

To prevent use of encryption and override other --ssl-xxx options, invoke the client program with --ssl-mode=DISABLED:

mysql --ssl-mode=DISABLED

To determine whether the current connection with the server uses encryption, check the session value of the Ssl_cipher status variable. If the value is empty, the connection is not encrypted. Otherwise, the connection is encrypted and the value indicates the encryption cipher. For example:

mysql> SHOW SESSION STATUS LIKE ‘Ssl_cipher‘;
+---------------+---------------------------+
| Variable_name | Value                     |
+---------------+---------------------------+
| Ssl_cipher    | DHE-RSA-AES128-GCM-SHA256 |
+---------------+---------------------------+

For the mysql client, an alternative is to use the STATUS or \s command and check the SSL line:

mysql> \s
...
SSL: Not in use
...

Or:

mysql> \s
...
SSL: Cipher in use is DHE-RSA-AES128-GCM-SHA256
...

For some MySQL deployments it may be not only desirable but mandatory to use encrypted connections (for example, to satisfy regulatory requirements). This section discusses configuration settings that enable you to do this. These levels of control are available:

To require that clients connect using encrypted connections, enable the require_secure_transport system variable. For example, put these lines in the server my.cnf file:

[mysqld]
require_secure_transport=ON

Alternatively, to set and persist the value at runtime, use this statement:

SET PERSIST require_secure_transport=ON;

SET PERSIST sets the value for the running MySQL instance. It also saves the value, causing it to be used for subsequent server restarts. See Section 13.7.6.1, “SET Syntax for Variable Assignment”.

With require_secure_transport enabled, client connections to the server are required to use some form of secure transport, and the server permits only TCP/IP connections that use SSL, or connections that use a socket file (on Unix) or shared memory (on Windows). The server rejects nonsecure connection attempts, which fail with an ER_SECURE_TRANSPORT_REQUIRED error.

To invoke a client program such that it requires an encrypted connection whether or not the server requires encryption, use an --ssl-mode option value of REQUIRED, VERIFY_CA, or VERIFY_IDENTITY. For example:

mysql --ssl-mode=REQUIRED
mysqldump --ssl-mode=VERIFY_CA
mysqladmin --ssl-mode=VERIFY_IDENTITY

To configure a MySQL account to be usable only over encrypted connections, include a REQUIRE clause in the CREATE USER statement that creates the account, specifying in that clause the encryption characteristics you require. For example, to require an encrypted connection and the use of a valid X.509 certificate, use REQUIRE X509:

CREATE USER ‘jeffrey‘@‘localhost‘ REQUIRE X509;

For additional information about the REQUIRE clause, see Section 13.7.1.3, “CREATE USER Statement”.

To modify existing accounts that have no encryption requirements, use the ALTER USER statement.

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:

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 master/slave replication connections where this server instance is the master, 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 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 master/slave replication connections where this server instance is the slave, the MASTER_TLS_VERSION option for the CHANGE MASTER TO statement specifies which TLS protocols the replication slave permits for connections to the master. 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 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 replication slave can be configured with tls_version set to TLSv1.3 to permit only incoming connections that use TLSv1.3, but also configured with MASTER_TLS_VERSION set to TLSv1.2 to permit only TLSv1.2 for outgoing slave connections to the master.

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, “Group Replication Secure Socket Layer (SSL) Support”.

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 replication slaves.

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 TLS protocols up through TLSv1.2:

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.

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:

If the server is started with an --ssl-cert option specifying 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. Examples:

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