Pre-General Availability Draft: 2017-07-21
To enable secure connections, the proper options must be used to specify the appropriate certificate and key files. For a complete list of options related to establishment of secure connections, see Section 6.4.5, “Command Options for Secure Connections”.
If you need to create the required certificate and key files, see Section 6.4.6, “Creating SSL and RSA Certificates and Keys”.
To start the MySQL server so that it permits clients to connect securely, use options that identify the certificate and key files the server uses when establishing a secure connection:
For example, start the server with these lines in the
my.cnf file, changing the file names as
[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 have a MySQL
source distribution, you can test your setup using the
demonstration certificate and key files in its
value is enabled by default.
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 secure connections explicitly, the
server attempts to enable support for secure connections
automatically at startup:
If the server discovers valid certificate and key files named
server-key.pemin the data directory, it enables support for secure connections by clients. (The files need not have been autogenerated; 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 does not enable secure connections.
If the server automatically enables support for secure connections, it writes a message 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 will be self-signed if created automatically by the server or manually using mysql_ssl_rsa_setup.)
For further control over whether clients must connect securely,
variable; see Section 5.1.5, “Server System Variables”. For
information about permitted encryption protocols and ciphers,
see Section 6.4.3, “Secure Connection Protocols and Ciphers”.
To connect securely to a MySQL server that supports secure
connections, the options that a client must specify depend on
the encryption requirements of the MySQL account used by the
client. (See the discussion of the
clause in Section 18.104.22.168, “CREATE USER Syntax”.)
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. As a
recommended set of secure-connection options, start the server
with at least
--ssl-key, and invoke the client
--ssl-ca. A client can
connect securely like this:
shell> mysql --ssl-ca=ca.pem
To require that a client certificate also be specified, create
the account using the
REQUIRE X509 option.
Then the client must also specify the proper client key and
certificate files or the server will reject the connection:
shell> mysql --ssl-ca=ca.pem \ --ssl-cert=client-cert.pem \ --ssl-key=client-key.pem
To prevent use of encryption and override other
invoke the client program with
shell> mysql --ssl-mode=DISABLED
Client programs attempt to establish a secure connection by default whenever the server supports secure connections:
To require a secure connection and fail if one cannot be established, invoke the client with
To use an unencrypted connection, invoke the client with
For information about permitted encryption protocols and ciphers, see Section 6.4.3, “Secure Connection Protocols and Ciphers”.
A client can determine whether the current connection with the
server uses encryption by checking the 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 STATUS LIKE 'Ssl_cipher'; +---------------+--------------------+ | Variable_name | Value | +---------------+--------------------+ | Ssl_cipher | DHE-RSA-AES256-SHA | +---------------+--------------------+
For the mysql client, an alternative is to
command and check the
mysql> \s ... SSL: Cipher in use is DHE-RSA-AES256-SHA ...
mysql> \s ... SSL: Not in use ...
The C API enables application programs to use secure connections:
To establish a secure connection, use the
mysql_ssl_set()C API function to set the appropriate certificate options before calling
mysql_real_connect(). See Section 22.214.171.124, “mysql_ssl_set()”. To require the use of a secure connection, call
MYSQL_OPT_SSL_MODEoption. To establish permitted encryption protocols, call
To determine whether encryption is in use after the connection is established, use
mysql_get_ssl_cipher(). A non-
NULLreturn value indicates an encrypted connection and names the cipher used for encryption. A
NULLreturn value indicates that encryption is not being used. See Section 126.96.36.199, “mysql_get_ssl_cipher()”.
Replication uses the C API, so secure connections can be used between master and slave servers. See Section 18.3.9, “Setting Up Replication to Use Secure Connections”.