Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 35.5Mb
PDF (A4) - 35.5Mb
PDF (RPM) - 34.6Mb
EPUB - 8.7Mb
HTML Download (TGZ) - 8.5Mb
HTML Download (Zip) - 8.5Mb
HTML Download (RPM) - 7.3Mb
Eclipse Doc Plugin (TGZ) - 9.3Mb
Eclipse Doc Plugin (Zip) - 11.5Mb
Man Pages (TGZ) - 201.5Kb
Man Pages (Zip) - 306.8Kb
Info (Gzip) - 3.3Mb
Info (Zip) - 3.3Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  Configuring MySQL to Use Secure Connections

7.4.4 Configuring MySQL to Use Secure Connections

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 7.4.5, “Command Options for Secure Connections”.

If you need to create the required certificate and key files, see Section 7.4.6, “Creating SSL and RSA Certificates and Keys”.

Server-Side Configuration for Secure Connections

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:

  • --ssl-ca identifies the Certificate Authority (CA) certificate.

  • --ssl-cert identifies the server public key certificate. This can be sent to the client and authenticated against the CA certificate that it has.

  • --ssl-key identifies the server private key.

For example, start the server 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 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 mysql-test/std_data directory.

As of MySQL 5.7.5, the server-side --ssl option value is enabled by default. Also as of MySQL 5.7.5, MySQL servers compiled using OpenSSL can generate missing certificate and key files automatically at startup. See Section 7.4.6.1, “Creating SSL and RSA Certificates and Keys using MySQL”.

The server performs certificate and key file autodiscovery as of MySQL 5.7.5 (for servers compiled using OpenSSL) or 5.7.6 (for servers compiled using yaSSL). If --ssl is enabled (possibly along with --ssl-cipher) and other --ssl-xxx options 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 ca.pem, server-cert.pem, and server-key.pem in 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. As of MySQL 5.7.6, 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 any certificate and key files that the server discovers and uses automatically, it uses the file names to set the corresponding system variables (ssl_ca, ssl_cert, ssl_key).

For further control over whether clients must connect securely, use the require_secure_transport system variable; see Section 6.1.4, “Server System Variables”. For information about permitted encryption protocols and ciphers, see Section 7.4.3, “Secure Connection Protocols and Ciphers”.

Client-Side Configuration for Secure Connections

For client programs, options for secure connections are similar to those used on the server side, but --ssl-cert and --ssl-key identify the client public and private key:

  • --ssl-ca identifies the Certificate Authority (CA) certificate. This option, if used, must specify the same certificate used by the server.

  • --ssl-cert identifies the client public key certificate.

  • --ssl-key identifies the client private key.

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 REQUIRE clause in Section 14.7.1.2, “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 includes the REQUIRE SSL option. As a recommended set of secure-connection options, start the server with at least --ssl-cert and --ssl-key, and invoke the client with --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 --ssl-xxx options, invoke the client program with --ssl-mode=DISABLED, --ssl=0, or a synonym (--skip-ssl, --disable-ssl):

shell> mysql --ssl-mode=DISABLED

As of MySQL 5.7.7, client programs attempt to establish a secure connection by default whenever the server supports secure connections:

From MySQL 5.7.3 to 5.7.6, --ssl on the client side is prescriptive (not advisory as before MySQL 5.7.3): With --ssl, connection attempts fail if a secure connection cannot be established.

Before MySQL 5.7.3, --ssl on the client side is advisory: --ssl permits but does not require the client to connect to the server using encryption. Therefore, this option is not sufficient in itself to cause a secure connection to be used. For example, if you specify this option for a client program but the server has not been configured to support secure connections, the client falls back to an unencrypted connection.

For information about permitted encryption protocols and ciphers, see Section 7.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 use the STATUS or \s command and check the SSL line:

mysql> \s
...
SSL: Cipher in use is DHE-RSA-AES256-SHA
...

Or:

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

C API Configuration for Secure Connections

The C API enables application programs to use secure connections:

Replication uses the C API, so secure connections can be used between master and slave servers. See Section 18.3.8, “Setting Up Replication to Use Secure Connections”.


User Comments
Sign Up Login You must be logged in to post a comment.