Documentation Home
MySQL 5.6 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 31.5Mb
PDF (A4) - 31.6Mb
PDF (RPM) - 30.6Mb
HTML Download (TGZ) - 7.6Mb
HTML Download (Zip) - 7.7Mb
HTML Download (RPM) - 6.6Mb
Man Pages (TGZ) - 187.6Kb
Man Pages (Zip) - 302.2Kb
Info (Gzip) - 2.9Mb
Info (Zip) - 2.9Mb
Excerpts from this Manual

23.8.7.68 mysql_ssl_set()

my_bool mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)

Description

mysql_ssl_set() is used for establishing secure connections using SSL. It must be called before mysql_real_connect().

mysql_ssl_set() does nothing unless SSL support is enabled in the client library.

Arguments:

  • mysql: The connection handler returned from mysql_init().

  • key: The path name to the key file

  • cert: The path name to the certificate file

  • ca: The path name to the certificate authority file

  • capath: The path name to a directory that contains trusted SSL CA certificates in PEM format

  • cipher: A list of permissible ciphers to use for SSL encryption

The mysql argument must be a valid connection handler. Any unused SSL arguments may be given as NULL.

Return Values

This function always returns 0. If SSL setup is incorrect, a subsequent mysql_real_connect() call returns an error when you attempt to connect.

Enforcing an Encrypted Connection

mysql_ssl_set() specifies SSL information such as certificate and key files for establishing a secure connection if such connections are available, but does not enforce any requirement that the connection obtained be secure. To require an encrypted connection, the standard MySQL client programs use the following technique, which can also be used by third-party applications:

  1. If the --ssl-mode=REQUIRED command-line option was specified, turn on SSL by calling mysql_ssl_set() to supply the appropriate SSL values. In addition, call mysql_options(), passing the MYSQL_OPT_SSL_MODE option with a value of SSL_MODE_REQUIRED. If the mysql_options() call fails, exit with an error.

  2. Call mysql_real_connect() to connect to the server, then call mysql_get_ssl_cipher() to check whether the resulting connection is encrypted. If not, exit with an error.

MySQL clients implement this technique using a wrapper function named mysql_connect_ssl_check() to establish and check the connection, rather than calling mysql_real_connect() directly. To see how this works, look in the client directory of a MySQL source distribution at the source for any of the standard MySQL clients, as well as the client_priv.h file that contains the mysql_connect_ssl_check() wrapper function implementation. A call to mysql_connect_ssl_check() takes arguments like the arguments to mysql_real_connect(), plus an extra argument indicating whether to require an encrypted connection:

if (!mysql_connect_ssl_check(&mysql, host, user, pass, db,
                             port, sock, flags,
                             opt_ssl_required))
{
  /* failure: connection not obtained, or not secure if required to be */
}
else
{
  /* success: connection obtained, secure if required to be */
}

Version notes:

  • In MySQL 5.6.30, the --ssl-mode=REQUIRED command-line option was backported from MySQL 5.7 to MySQL 5.6. Clients are required to check for themselves, after calling mysql_real_connect(), whether the connection is encrypted, and fail if not. To do this, call mysql_get_ssl_cipher().

  • In MySQL 5.6.36, the MYSQL_OPT_SSL_MODE option for mysql_options() was backported from MySQL 5.7 to MySQL 5.6. A call to mysql_options() to set MYSQL_OPT_SSL_MODE option to value of SSL_MODE_REQUIRED suffices to cause mysql_real_connect() to fail if the connection is not encrypted. mysql_get_ssl_cipher(). can still be called after connecting, although it is not necessary to do so.

    Important

    In MySQL 5.6, the minor C API version number was not incremented for this change. Application programs compiled for MySQL 5.6 that require MYSQL_OPT_SSL_MODE may fail to operate properly if the dynamic loader provides an older client library without MYSQL_OPT_SSL_MODE. Such applications must be written to handle this possibility by checking whether the mysql_options() call succeeds or fails.


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