Documentation Home
Security in MySQL
Related Documentation Download this Excerpt
PDF (US Ltr) - 1.2Mb
PDF (A4) - 1.2Mb
EPUB - 369.4Kb
HTML Download (TGZ) - 287.0Kb
HTML Download (Zip) - 296.8Kb

Security in MySQL  /  ...  /  Configuring MySQL to Use SSL Connections

5.12.3 Configuring MySQL to Use SSL Connections

To enable SSL connections, the proper SSL-related options must be used to specify the appropriate certificate and key files. For a complete list of SSL options, see Section 5.12.4, “SSL Command Options”.

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

Server-Side SSL Configuration

To start the MySQL server so that it permits clients to connect using SSL, 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:


Each option names a file in PEM format. If you have a MySQL source distribution, you can also 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 SSL files automatically at startup. See Section 5.13.1, “Creating SSL and RSA Certificates and Keys using MySQL”.

SSL file autodiscovery is enabled 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 options are not given to configure SSL explicitly, the server attempts to enable SSL automatically at startup:

  • If the server discovers valid SSL files named ca.pem, server-cert.pem, and server-key.pem in the data directory, it enables SSL to permit SSL connections by clients. (These 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 SSL files in the data directory, it continues executing but does not enable SSL.

If the server automatically enables SSL, 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 SSL 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).

Client-Side SSL Configuration

For client programs, SSL options 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 as used by the server.

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

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

To establish a secure connection to a MySQL server with SSL support, the options that a client must specify depend on the SSL requirements of the MySQL account used by the client. (See the discussion of the REQUIRE clause in CREATE USER Syntax.)

Suppose that you want to connect using an account that has no special SSL requirements or was created using a CREATE USER statement that includes the REQUIRE SSL option. As a recommended set of SSL 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 \

To prevent use of SSL and override other SSL options, invoke the client program with --ssl=0 or a synonym (--skip-ssl, --disable-ssl):

shell> mysql --ssl=0

As of MySQL 5.7.3, --ssl on the client side is prescriptive (not advisory as before MySQL 5.7.3). With --ssl, connection attempts fail if SSL is not available.

As of MySQL 5.7.7, MySQL client programs attempt to establish an SSL connection by default whenever the server is enabled to support SSL:

  • In the absence of an --ssl option, the client falls back to an unencrypted connection if SSL is not available.

  • To require an SSL connection and fail if SSL is unavailable, invoke the client with an explicit --ssl option.

  • To suppress the attempt at using SSL for the connection, specify the --ssl=0 option.

A client can determine whether the current connection with the server uses SSL by checking the value of the Ssl_cipher status variable. The value is nonempty if SSL is used, and empty otherwise. 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


mysql> \s
SSL: Not in use

SSL Configuration and the C API

The C API enables application programs to use SSL:

  • 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 mysql_ssl_set(). To require the use of SSL, call mysql_options() with the MYSQL_OPT_SSL_ENFORCE option.

  • To determine whether SSL is in use after the connection is established, use mysql_get_ssl_cipher(). A non-NULL return value indicates a secure connection and names the SSL cipher used for encryption. A NULL return value indicates that SSL is not being used. See mysql_get_ssl_cipher().

Replication uses the C API, so secure connections can be used between master and slave servers. See Setting Up Replication Using SSL.

Download this Excerpt
PDF (US Ltr) - 1.2Mb
PDF (A4) - 1.2Mb
EPUB - 369.4Kb
HTML Download (TGZ) - 287.0Kb
HTML Download (Zip) - 296.8Kb
User Comments
Sign Up Login You must be logged in to post a comment.