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.

mysql is the connection handler returned from mysql_init(). Specify the other parameters as follows:

Any unused SSL parameters may be given as NULL.

Return Values

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

Enforcing an Encrypted Connection

In MySQL 5.5.49, the --ssl-mode=REQUIRED option was backported from MySQL 5.7 to MySQL 5.5 for standard MySQL client programs, to enable requiring encrypted connections. In MySQL 5.7, the C client library additionally provides native support for requiring encrypted connections (call mysql_options(), passing the MYSQL_OPT_SSL_MODE option with a value of SSL_MODE_REQUIRED). In MySQL 5.5, the client library provides no such support because doing so would break binary compatibility with previous library versions within the series. Clients that require encrypted connections must implement the logic themselves.

To require encrypted connections, the standard MySQL client programs use the following technique, which can also be used by third-party applications:

MySQL clients implement this technique using a wrapper function to establish and check the connection, rather than calling mysql_real_connect() directly. To see how this works, check the source for any of the standard MySQL clients in a MySQL source distribution. A typical call to mysql_connect_ssl_check(), the wrapper function, 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 */
}
else
{
  /* success */
}

mysql_connect_ssl_check() can be found in the client_priv.h file in the same directory as the client programs. It looks like this (slightly reformatted):

/**
  Wrapper for mysql_real_connect() that checks if SSL connection is
  established.

  The function calls mysql_real_connect() first. Then, if the ssl_required
  argument is TRUE (i.e., the --ssl-mode=REQUIRED option was specified), it
  checks the current SSL cipher to ensure that SSL is used for the current
  connection.  Otherwise, it returns NULL and sets errno to
  CR_SSL_CONNECTION_ERROR.

  All clients (except mysqlbinlog, which disregards SSL options) use this
  function instead of mysql_real_connect() to handle the --ssl-mode=REQUIRED
  option.
*/
MYSQL *mysql_connect_ssl_check(MYSQL *mysql_arg, const char *host,
                               const char *user, const char *passwd,
                               const char *db, uint port,
                               const char *unix_socket, ulong client_flag,
                               my_bool ssl_required __attribute__((unused)))
{
  MYSQL *mysql= mysql_real_connect(mysql_arg, host, user, passwd, db, port,
                                   unix_socket, client_flag);
#if defined(HAVE_OPENSSL) && !defined(EMBEDDED_LIBRARY)
  if (mysql &&                                   /* connection established. */
      ssl_required &&                            /* --ssl-mode=REQUIRED. */
      !mysql_get_ssl_cipher(mysql))              /* non-SSL connection. */
  {
    NET *net= &mysql->net;
    net->last_errno= CR_SSL_CONNECTION_ERROR;
    strmov(net->last_error, "--ssl-mode=REQUIRED option forbids non SSL connections");
    strmov(net->sqlstate, "HY000");
    return NULL;
  }
#endif
  return mysql;
}