Documentation Home
MySQL 5.5 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 27.2Mb
PDF (A4) - 27.2Mb
PDF (RPM) - 26.1Mb
HTML Download (TGZ) - 6.5Mb
HTML Download (Zip) - 6.5Mb
HTML Download (RPM) - 5.6Mb
Man Pages (TGZ) - 170.5Kb
Man Pages (Zip) - 279.0Kb
Info (Gzip) - 2.6Mb
Info (Zip) - 2.6Mb
Excerpts from this Manual

MySQL 5.5 Reference Manual  /  ...  /  C API Encrypted Connection Support

23.8.15 C API Encrypted Connection Support

For applications that require control over how encrypted connections are established, the C API provides these capabilities:

C API Options for Encrypted Connections

mysql_ssl_set() takes the following arguments for control over use of encrypted connections. For more information, see Section, “mysql_ssl_set()”.

  • 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

mysql_options() provides the following options for control over use of encrypted connections. For option details, see Section, “mysql_options()”.

  • MYSQL_OPT_SSL_MODE: The connection security state

  • MYSQL_OPT_SSL_VERIFY_SERVER_CERT: Whether to verify server Common Name value

Enforcing an Encrypted Connection

mysql_ssl_set() options for information such as SSL certificate and key files are used to establish an encrypted connection if such connections are available, but do not enforce any requirement that the connection obtained be encrypted. To require an encrypted connection, use the following technique:

  1. Call mysql_ssl_set() to supply the appropriate SSL values (certificate and key files, encryption ciphers, and so forth).

  2. For MySQL 5.5.55 and higher, MYSQL_OPT_SSL_MODE is available, so call mysql_options() to pass the MYSQL_OPT_SSL_MODE option with a value of SSL_MODE_REQUIRED.


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

  3. Call mysql_real_connect() to connect to the server. As of MySQL 5.5.55, the call fails if an encrypted connection cannot be obtained; exit with an error. Prior to 5.5.55 (before MYSQL_OPT_SSL_MODE is available), clients are required to check for themselves, after calling mysql_real_connect(), whether the connection is encrypted. To do this if mysql_real_connect() succeeds, 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,
  /* failure: connection not obtained, or not encrypted if required to be */
  /* success: connection obtained, encrypted if required to be */

Version notes:

  • In MySQL 5.5.49, the --ssl-mode=REQUIRED command-line option was backported from MySQL 5.7 to MySQL 5.5. Clients can check for this option and use it to determine whether to require an encrypted connection. If so, clients must 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() and check the return value.

  • In MySQL 5.5.55, the MYSQL_OPT_SSL_MODE option for mysql_options() was backported from MySQL 5.7 to MySQL 5.5. A call to mysql_options() to set the 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.

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