3.5.1 Support for Encrypted Connections

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

Options for Encrypted Connections

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

  • MYSQL_OPT_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.

  • MYSQL_OPT_SSL_CAPATH: The path name of the directory that contains trusted SSL CA certificate files.

  • MYSQL_OPT_SSL_CERT: The path name of the client public key certificate file.

  • MYSQL_OPT_SSL_CIPHER: The list of permissible ciphers for SSL encryption.

  • MYSQL_OPT_SSL_CRL: The path name of the file containing certificate revocation lists.

  • MYSQL_OPT_SSL_CRLPATH: The path name of the directory that contains certificate revocation list files.

  • MYSQL_OPT_SSL_KEY: The path name of the client private key file.

  • MYSQL_OPT_SSL_MODE: The connection security state.

  • MYSQL_OPT_SSL_VERIFY_SERVER_CERT: Whether to perform host name identity verification of the server certificate Common Name value.

mysql_ssl_set()can be used as a convenience routine that is equivalent to a set ofmysql_options()calls that specify certificate and key files, encryption ciphers, and so forth. SeeSection 5.4.70, “mysql_ssl_set()”.

Enforcing an Encrypted Connection

mysql_options()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. Callmysql_options()as necessary supply the appropriate SSL parameters (certificate and key files, encryption ciphers, and so forth).

  2. For MySQL 5.6.36 and higher,MYSQL_OPT_SSL_MODEis available, so callmysql_options()to pass theMYSQL_OPT_SSL_MODEoption with a value ofSSL_MODE_REQUIRED.

    Important

    In MySQL 5.6, the minor C API version number was not incremented for the addition ofMYSQL_OPT_SSL_MODEin MySQL 5.6.36. Application programs compiled for MySQL 5.6 that requireMYSQL_OPT_SSL_MODEmay fail to operate properly if the dynamic loader provides an older client library that does not includeMYSQL_OPT_SSL_MODE. Such applications must be written to handle this possibility by checking whether themysql_options()call succeeds or fails.

  3. Callmysql_real_connect()to connect to the server. As of MySQL 5.6.36, the call fails if an encrypted connection cannot be obtained; exit with an error. Prior to 5.6.36 (beforeMYSQL_OPT_SSL_MODEis available), clients are required to check for themselves, after callingmysql_real_connect(), whether the connection is encrypted. To do this ifmysql_real_connect()succeeds, callmysql_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 namedmysql_connect_ssl_check()to establish and check the connection, rather than callingmysql_real_connect()directly. To see how this works, look in theclientdirectory of a MySQL source distribution at the source for any of the standard MySQL clients, as well as theclient_priv.hfile that contains themysql_connect_ssl_check()wrapper function implementation. A call tomysql_connect_ssl_check()takes arguments like the arguments tomysql_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 encrypted if required to be */ } else { /* success: connection obtained, encrypted if required to be */ }

Version notes:

  • In MySQL 5.6.30, the--ssl-mode=REQUIRED命令行选项从MySQL 5.7补丁to MySQL 5.6. 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 callingmysql_real_connect(), whether the connection is encrypted, and fail if not. To do this, callmysql_get_ssl_cipher()and check the return value.

  • In MySQL 5.6.36, theMYSQL_OPT_SSL_MODEoption formysql_options()was backported from MySQL 5.7 to MySQL 5.6. A call tomysql_options()to set theMYSQL_OPT_SSL_MODEoption to value ofSSL_MODE_REQUIREDsuffices to causemysql_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.

Improving Security of Encrypted Connections

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:

  • 来specify the CA certificate, callmysql_options()to pass theMYSQL_OPT_SSL_CA(orMYSQL_OPT_SSL_CAPATH) option.

  • 来enable host name identity verification, callmysql_options()to enable theMYSQL_OPT_SSL_VERIFY_SERVER_CERToption.

  • 来require an encrypted connection, callmysql_options()to pass theMYSQL_OPT_SSL_MODEoption with a value ofSSL_MODE_REQUIRED. (For details aboutSSL_MODE_REQUIRED, seeEnforcing an Encrypted Connection.)