28.7.7.77 mysql_ssl_set()

mysql_ssl_set() is used for establishing encrypted connections using SSL. The mysql argument must be a valid connection handler. Any unused SSL arguments may be given as NULL.

If used, mysql_ssl_set() must be called before mysql_real_connect(). mysql_ssl_set() does nothing unless SSL support is enabled in the client library.

It is optional to call mysql_ssl_set() to obtain an encrypted connection because by default, MySQL programs attempt to connect using encryption if the server supports encrypted connections, falling back to an unencrypted connection if an encrypted connection cannot be established (see Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”). mysql_ssl_set() may be useful to applications that must specify particular certificate and key files, encryption ciphers, and so forth.

mysql_ssl_set() specifies SSL information such as certificate and key files for establishing an encrypted connection if such connections are available, but does not enforce any requirement that the connection obtained be encrypted. To require an encrypted connection, use the technique described in Section 28.7.22, “C API Encrypted Connection Support”.

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. For details, see Section 28.7.22, “C API Encrypted Connection Support”.

mysql_ssl_set() is a convenience function that is essentially equivalent to this set of mysql_options() calls:

mysql_options(mysql, MYSQL_OPT_SSL_KEY,    key);
mysql_options(mysql, MYSQL_OPT_SSL_CERT,   cert);
mysql_options(mysql, MYSQL_OPT_SSL_CA,     ca);
mysql_options(mysql, MYSQL_OPT_SSL_CAPATH, capath);
mysql_options(mysql, MYSQL_OPT_SSL_CIPHER, cipher);

Because of that equivalence, applications can, instead of calling mysql_ssl_set(), call mysql_options() directly, omitting calls for those options for which the option value is NULL. Moreover, mysql_options() offers encrypted-connection options not available using mysql_ssl_set(), such as MYSQL_OPT_SSL_MODE to specify the security state of the connection, and MYSQL_OPT_TLS_VERSION to specify the protocols the client permits for encrypted connections.

Arguments:

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