Several options are available to indicate whether to use encrypted connections, and to specify the appropriate certificate and key files. This section provides general guidance about configuring the server and clients for encrypted connections:
For a complete list of options related to establishment of encrypted connections, see Section 6.3.2, “Command Options for Encrypted Connections”. To create any required certificate and key files, see Section 6.3.3, “Creating SSL and RSA Certificates and Keys”.
Encrypted connections can be used between master and slave replication servers. See Section 17.3.9, “Setting Up Replication to Use Encrypted Connections”.
Encrypted connections are available through the MySQL C API. See Section 28.7.22, “C API Encrypted Connection Support”.
On the server side, the
option specifies that the server permits but does not require
encrypted connections. This option is enabled by default.
These options on the server side identify the certificate and key files the server uses when permitting clients to establish encrypted connections:
--ssl-ca: The path name of the Certificate Authority (CA) certificate file. (
--ssl-capathis similar but specifies the path name of a directory of CA certificate files.)
--ssl-cert: The path name of the server public key certificate file. This can be sent to the client and authenticated against the CA certificate that it has.
--ssl-key: The path name of the server private key file.
For example, to enable the server for encrypted connections,
start it with these lines in the
file, changing the file names as necessary:
[mysqld] ssl-ca=ca.pem ssl-cert=server-cert.pem ssl-key=server-key.pem
Each option names a file in PEM format. If you need to create
the required certificate and key files, see
Section 6.3.3, “Creating SSL and RSA Certificates and Keys”. Alternatively, if you
have a MySQL source distribution, you can test your setup using
the demonstration certificate and key files in its
MySQL servers compiled using OpenSSL can generate missing certificate and key files automatically at startup. See Section 220.127.116.11, “Creating SSL and RSA Certificates and Keys using MySQL”.
The server performs certificate and key file autodiscovery. If
--ssl is enabled (possibly along
--ssl-cipher) and other
are not given to configure encrypted
connections explicitly, the server attempts to enable support
for encrypted connections automatically at startup:
If the server discovers valid certificate and key files named
server-key.pemin the data directory, it enables support for encrypted connections by clients. (The files need not have been generated automatically; what matters is that they have the indicated names and are valid.)
If the server does not find valid certificate and key files in the data directory, it continues executing but without support for encrypted connections.
If the server automatically enables support for encrypted connections, 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:
These system variables provide additional configuration control for encrypted connections:
To explicitly specify which encryption protocols the server permits, use the
tls_versionsystem variable; see Section 6.3.6, “Encrypted Connection Protocols and Ciphers”.
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.
Table 6.11 Corresponding System and Status Variables Related to Server SSL Context
To reconfigure the SSL context at runtime, use this procedure:
Set any SSL context-related system variables that should be changed to their new values.
ALTER INSTANCE RELOAD TLS. This statement reconfigures the active SSL context from the current values of the SSL context-related system variables. It also sets the context-related status variables to reflect the new active context values. The statement requires the
New connections established after execution of
ALTER INSTANCE RELOAD TLSuse the new SSL context. Existing connections remain unaffected. If existing connections should be terminated, use the
The members of each pair of system and status variables may have different values temporarily due to the way the reconfiguration procedure works:
Changes to the system variables prior to
ALTER INSTANCE RELOAD TLSdo not change the SSL context. At this point, those changes have no effect on new connections, and corresponding context-related system and status variables may have different values. This enables you to make any changes required to the system variables, then update the active SSL context atomically with
ALTER INSTANCE RELOAD TLSafter all system variable changes have been made.
ALTER INSTANCE RELOAD TLS, corresponding system and status variables have the same values. This remains true until the next change to the system variables.
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
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
--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
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
Prior to MySQL 8.0.16, the SSL context-related system variables are not dynamic. They can be set at server startup, but cannot be changed thereafter. These system variables therefore reflect the SSL context values the server uses for new connections.
By default, MySQL client programs attempt to establish an
encrypted connection if the server supports encrypted
connections, with further control available through the
In the absence of an
--ssl-modeoption, clients attempt to connect using encryption, falling back to an unencrypted connection if an encrypted connection cannot be established. This is also the behavior with an explicit
--ssl-mode=REQUIRED, clients require an encrypted connection and fail if one cannot be established.
--ssl-mode=DISABLED, clients use an unencrypted connection.
--ssl-mode=VERIFY_IDENTITY, clients require an encrypted connection, and also perform verification against the server CA certificate and (with
VERIFY_IDENTITY) against the server host name in its certificate.
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-key identify the client
public and private key:
--ssl-ca: The path name of the Certificate Authority (CA) certificate file. This option, if used, must specify the same certificate used by the server. (
--ssl-capathis similar but specifies the path name of a directory of CA certificate files.)
--ssl-cert: The path name of the client public key certificate file.
--ssl-key: The path name of the client private key file.
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:
Host name identity verification with
VERIFY_IDENTITY does not work with
self-signed certificates created automatically by the server,
or manually using mysql_ssl_rsa_setup (see
Section 18.104.22.168, “Creating SSL and RSA Certificates and Keys using MySQL”). Such
self-signed certificates do not contain the server name as the
Common Name value.
Host name identity verification also does not work with certificates that specify the Common Name using wildcards because that name is compared verbatim to the server name.
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 a MySQL server that supports encrypted connections.
Suppose that you want to connect using an account that has no
special encryption requirements or was created using a
CREATE USER statement that
REQUIRE SSL option. Assuming
that the server supports encrypted connections, a client can
connect using encryption with no
--ssl-mode option or with an
For an account with
REQUIRE SSL, 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:
If the account has more stringent security requirements, other options must be specified to establish an encrypted connection:
For accounts with
REQUIRE X509, clients must specify at least
--ssl-key. In addition,
--ssl-capath) is recommended so that the public certificate provided by the server can be verified. For example:
mysql --ssl-ca=ca.pem \ --ssl-cert=client-cert.pem \ --ssl-key=client-key.pem
For accounts that have
REQUIRE SUBJECT, the option requirements are the same as for
REQUIRE X509, but the certificate must match the issue or subject, respectively, specified in the account definition.
For additional information about the
clause, see the discussion in Section 22.214.171.124, “CREATE USER Syntax”.
To prevent use of encryption and override other
invoke the client program with
MySQL also provides these options for client-side SSL control:
To specify permitted encryption protocols explicitly, use the
--tls-version option; see
Section 6.3.6, “Encrypted Connection Protocols and Ciphers”.
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
command and check the
mysql> \s ... SSL: Not in use ...
mysql> \s ... SSL: Cipher in use is DHE-RSA-AES128-GCM-SHA256 ...