Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 33.8Mb
PDF (A4) - 33.8Mb
PDF (RPM) - 31.8Mb
HTML Download (TGZ) - 8.1Mb
HTML Download (Zip) - 8.2Mb
HTML Download (RPM) - 7.0Mb
Man Pages (TGZ) - 145.9Kb
Man Pages (Zip) - 206.8Kb
Info (Gzip) - 3.1Mb
Info (Zip) - 3.1Mb


MySQL 8.0 Reference Manual  /  ...  /  Configuring MySQL to Use Encrypted Connections

Pre-General Availability Draft: 2017-11-22

6.4.1 Configuring MySQL to Use Encrypted Connections

Several options 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:

For a complete list of options related to establishment of encrypted connections, see Section 6.4.2, “Command Options for Encrypted Connections”. If you need to create the required certificate and key files, see Section 6.4.3, “Creating SSL and RSA Certificates and Keys”.

Encrypted connections can be used between master and slave replication servers. See Section 18.3.9, “Setting Up Replication to Use Encrypted Connections”.

Encrypted connections are available through the MySQL C API. See Section 28.7.18, “C API Encrypted Connection Support”.

Server-Side Configuration for Encrypted Connections

On the server side, the --ssl option specifies that the server permits but does not require encrypted connections. This option is enabled by default.

These options on the server side identify 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 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 option names a file in PEM format. If you need to create the required certificate and key files, see Section 6.4.3, “Creating SSL and RSA Certificates and Keys”. Alternatively, 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 servers compiled using OpenSSL can generate missing certificate and key files automatically at startup. See Section 6.4.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”.

The server performs certificate and key file autodiscovery. If --ssl is enabled (possibly along with --ssl-cipher) and other --ssl-xxx options are not given to configure encrypted connections explicitly, the server attempts to enable support for encrypted 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 encrypted connections by clients. (The files need not have been generated automatically; 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 without support for encrypted connections.

If the server automatically enables support for encrypted connections, 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.)

The server uses the names of any automatically discovered and used certificate and key files to set the corresponding system variables (ssl_ca, ssl_cert, ssl_key).

For further control over whether clients must connect using encryption, use the require_secure_transport system variable; see Section 5.1.5, “Server System Variables”. To specify permitted encryption protocols explicitly, use the tls_version system variable; see Section 6.4.6, “Encrypted Connection Protocols and Ciphers”.

Client-Side Configuration 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 --ssl-mode option:

  • In the absence of an --ssl-mode option, 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=PREFFERED option.

  • With --ssl-mode=REQUIRED, clients require an encrypted connection and fail if one cannot be established.

  • With --ssl-mode=DISABLED, clients use an unencrypted connection.

  • With --ssl-mode=VERIFY_CA or --ssl-mode=VERIFY_IDENTITY, clients require an unencrypted connection, and also perform verification against the server CA certificate and (with VERIFY_IDENTITY) against the server host name in its certificate.

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 options 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:

Note

Host name identity verification does not work with self-signed certificates created automatically by the server, or manually using mysql_ssl_rsa_setup (see Section 6.4.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.

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 a MySQL server that supports encrypted connections.

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. Assuming that the server supports encrypted connections, a client can connect using encryption with no --ssl-mode option or with an explicit --ssl-mode=PREFFERED option:

mysql

Or:

mysql --ssl-mode=PREFERRED

For an account with REQUIRE SSL, 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:

mysql --ssl-mode=REQUIRED

If the account has more stringent security requirements, other options must be specified to establish an encrypted connection:

  • For accounts with REQUIRE X509, clients must specify at least --ssl-cert and --ssl-key. In addition, --ssl-ca (or --ssl-capath) is recommended so that the public certificate provided by the server can be verified. For example:

    mysql --ssl-ca=ca.pem \
          --ssl-cert=client-cert.pem \
          --ssl-key=client-key.pem
  • For accounts that have REQUIRE ISSUER or REQUIRE SUBJECT, the option 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 REQUIRE clause, see the discussion in Section 13.7.1.3, “CREATE USER Syntax”.

To prevent use of encryption and override other --ssl-xxx options, invoke the client program with --ssl-mode=DISABLED:

mysql --ssl-mode=DISABLED

To specify permitted encryption protocols explicitly, use the --tls-version option; see Section 6.4.6, “Encrypted Connection Protocols and Ciphers”.

To determine whether the current connection with the server uses encryption, check 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 SESSION STATUS LIKE 'Ssl_cipher';
+---------------+---------------------------+
| Variable_name | Value                     |
+---------------+---------------------------+
| Ssl_cipher    | DHE-RSA-AES128-GCM-SHA256 |
+---------------+---------------------------+

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-AES128-GCM-SHA256
...

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