Several configuration parameters 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:
Encrypted connections also can be used in other contexts, as discussed in these additional sections:
Between source and replica servers. See Setting Up Replication to Use Encrypted Connections.
Among Group Replication servers. See Group Replication Secure Socket Layer (SSL) Support.
By client programs that are based on the MySQL C API. See Support for Encrypted Connections.
Instructions for creating any required certificate and key files are available in Section 5.3, “Creating SSL and RSA Certificates and Keys”.
On the server side, the
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.
These system variables on the server side specify the certificate and key files the server uses when permitting clients to establish encrypted connections:
ssl_cert: The path name of the server public key certificate file. This certificate 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
To specify in addition that clients are required to use
encrypted connections, enable the
[mysqld] ssl_ca=ca.pem ssl_cert=server-cert.pem ssl_key=server-key.pem require_secure_transport=ON
Each certificate and key system variable names a file in PEM
format. Should you need to create the required certificate and
key files, see Section 5.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 5.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
The server performs certificate and key file autodiscovery. If
no explicit encrypted-connection options are given other than
--ssl (possibly along with
ssl_cipher) to configure
encrypted connections, the server attempts to enable
encrypted-connection support 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 those 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 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 system variables for server-side encrypted-connection control:
ssl_cipher: The list of permissible ciphers for connection encryption.
tls_version: Which encryption protocols the server permits for encrypted connections; see Section 5.2, “Encrypted Connection TLS Protocols and Ciphers”. For example, you can configure
tls_versionto prevent clients from using less-secure protocols.
For a complete list of client options related to establishment of encrypted connections, see Command Options for Encrypted 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 default setting,
an encrypted connection if the other default settings are
unchanged. However, to help prevent sophisticated
man-in-the-middle attacks, it is important for the client to
verify the server’s identity. The settings
are a better choice than the default setting to help prevent
this type of attack.
VERIFY_CA makes the
client check that the server’s certificate is valid.
VERIFY_IDENTITY makes the client check that
the server’s certificate is valid, and also makes the client
check that the host name the client is using matches the
identity in the server’s certificate. To implement one of
these settings, you must first ensure that the CA certificate
for the server is reliably available to all the clients that
use it in your environment, otherwise availability issues will
result. For this reason, they are not the default setting.
Attempts to establish an unencrypted connection fail if the
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
ssl_key system variables 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 that are created automatically by the
server or manually using
Section 5.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”). Such
self-signed certificates do not contain the server name as the
Common Name value.
Prior to MySQL 5.7.23, 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.
MySQL also provides these options for client-side encrypted-connection control:
--ssl-cipher: The list of permissible ciphers for connection encryption.
--ssl-crl: The path name of the file containing certificate revocation lists. (
--ssl-crlpathis similar but specifies the path name of a directory of certificate revocation-list files.)
--tls-version: The permitted encryption protocols; see Section 5.2, “Encrypted Connection TLS Protocols and Ciphers”.
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
REQUIRE SSL clause. Assuming
that the server supports encrypted connections, a client can
connect using encryption with no
--ssl-mode option or with an
For an account created with a
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:
If the account has more stringent security requirements, other options must be specified to establish an encrypted connection:
For accounts created with a
REQUIRE X509clause, 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 (enter the command on a single line):
mysql --ssl-ca=ca.pem --ssl-cert=client-cert.pem --ssl-key=client-key.pem
For accounts created with a
REQUIRE SUBJECTclause, the encryption 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 CREATE USER Statement.
MySQL servers can generate client certificate and key files that clients can use to connect to MySQL server instances. See Section 5.3, “Creating SSL and RSA Certificates and Keys”.
If a client connecting to a MySQL server instance uses an SSL
certificate with the
extension (an X.509 v3 extension), the extended key usage must
include client authentication (
If the SSL certificate is only specified for server
serverAuth) and other
non-client certificate purposes, certificate verification
fails and the client connection to the MySQL server instance
fails. There is no
extension in SSL certificates generated by MySQL Server (as
Section 5.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”),
and SSL certificates created using the
openssl command following the instructions
in Section 5.3.2, “Creating SSL Certificates and Keys Using openssl”. If you
use your own client certificate created in another way, ensure
extendedKeyUsage extension includes
To prevent use of encryption and override other
invoke the client program with
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 ...
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:
You can configure the server to require that clients connect using encrypted connections.
You can invoke individual client programs to require an encrypted connection, even if the server permits but does not require encryption.
You can configure individual MySQL accounts to be usable only over encrypted connections.
To require that clients connect using encrypted connections,
variable. For example, put these lines in the server
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
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
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,
CREATE USER 'jeffrey'@'localhost' REQUIRE X509;
For additional information about the
clause, see CREATE USER Statement.
To modify existing accounts that have no encryption
requirements, use the