To enable encrypted connections, your MySQL distribution must be built with SSL support, as described in Section 2.9.6, “Configuring SSL Library Support”. In addition, 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 Section 17.3.8, “Setting Up Replication to Use Encrypted Connections”.
By client programs that are based on the MySQL C API. See Support for Encrypted Connections.
If the server is compiled against OpenSSL, clients from MySQL 5.6 versions older than 5.6.17 are not able to connect to the server using encrypted connections if the client library is compiled using yaSSL. Either use a client and server compiled using the same SSL package, or upgrade to clients compiled against a client library version from MySQL 5.6.17 or higher.
Instructions for creating any required certificate and key files are available in Section 6.3.3, “Creating SSL and RSA Certificates and Keys”.
These system variables on the server side specify 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_capath
is 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 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 my.cnf
file, changing the file names as necessary:
[mysqld]
ssl_ca=ca.pem
ssl_cert=server-cert.pem
ssl_key=server-key.pem
Each certificate and key system variable names a file in PEM
format. 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.
MySQL also provides these system variables for server-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_crlpath
is similar but specifies the path name of a directory of certificate revocation-list files.)
For a complete list of client options related to establishment of encrypted connections, see Command Options for Encrypted Connections.
These 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_ca
,
ssl_cert
, and
ssl_key
system variables used
on the server side, but
--ssl-cert
and
--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-capath
is 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:
To specify the CA certificate, use
--ssl-ca
(or--ssl-capath
).To enable host name identity verification as well, specify
--ssl-verify-server-cert
.To require an encrypted connection, specify
--ssl-mode=REQUIRED
.--ssl-cipher
: The list of permissible ciphers for connection encryption.--ssl-crl
: The path name of the file containing certificate revocation lists. (--ssl-crlpath
is similar but specifies the path name of a directory of certificate revocation-list files.)
--ssl-mode=REQUIRED
produces
an encrypted connection. However, to help prevent
sophisticated man-in-the-middle attacks, it is also important
for the client to verify the server’s identity. Adding the
--ssl-verify-server-cert
option achieves this. To implement that additional option, 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.
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
GRANT
statement that included the
REQUIRE SSL
clause. As a recommended set of
encrypted-connection options, start the server with at least the
ssl_cert
and
ssl_key
system variables set,
and invoke the client with the
--ssl-ca
(or
--ssl-capath
) option. A client
can connect using encryption like this:
mysql --ssl-ca=ca.pem
To require that a client certificate also be specified, create
the account using a REQUIRE X509
clause. Then
the client must also specify the proper client key and
certificate files or the server rejects the connection (enter
the command on a single line):
mysql --ssl-ca=ca.pem
--ssl-cert=client-cert.pem
--ssl-key=client-key.pem
For additional information about the REQUIRE
clause, see Section 13.7.1.4, “GRANT Statement”.
To prevent use of encryption and override other
--ssl-
options,
invoke the client program with
xxx
--ssl=0
or a synonym
(--skip-ssl
,
--disable-ssl
):
mysql --ssl=0
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-AES256-SHA |
+---------------+--------------------+
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-AES256-SHA
...