MySQL 9.3 C API Developer Guide
This section describes how C applications use the C API capabilities for encrypted connections. 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 Configuring MySQL to Use Encrypted Connections). For applications that require control beyond the default behavior over how encrypted connections are established, the C API provides these capabilities:
The mysql_options() function
enables applications to set the appropriate SSL/TLS options
before calling
mysql_real_connect(). For
example, to require the use of an encrypted connection, see
Enforcing an Encrypted Connection.
The mysql_get_ssl_cipher()
function enables applications to determine, after a
connection has been established, whether the connection uses
encryption. A NULL return value indicates
that encryption is not being used. A
non-NULL return value indicates an
encrypted connection and names the encryption cipher. See
Section 5.4.36, “mysql_get_ssl_cipher()”.
mysql_options() provides the
following options for control over use of encrypted
connections. For option details, see
Section 5.4.54, “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
encryption ciphers the client permits for connections that
use TLS protocols up through TLSv1.2.
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_SESSION_DATA : Serialized
session data from an encrypted connection that was
returned by a call to the
mysql_get_ssl_session_data()
function while the connection was active.
MYSQL_OPT_TLS_CIPHERSUITES: The list of
encryption ciphersuites the client permits for connections
that use TLSv1.3.
MYSQL_OPT_TLS_VERSION: The encryption
protocols the client permits.
The deprecated mysql_ssl_set()
function can be used as a convenience routine that is
equivalent to a set of
mysql_options() calls that
specify certificate and key files, encryption ciphers, and so
forth. See Section 5.4.82, “mysql_ssl_set()”.
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:
Call mysql_options() as
necessary supply the appropriate SSL parameters
(certificate and key files, encryption ciphers, and so
forth).
Call mysql_options() to
pass the MYSQL_OPT_SSL_MODE option with
a value of SSL_MODE_REQUIRED or one of
the more-restrictive option values.
Call mysql_real_connect()
to connect to the server. The call fails if an encrypted
connection cannot be obtained; exit with an error.
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:
To specify the CA certificate, call
mysql_options() to pass
the MYSQL_OPT_SSL_CA (or
MYSQL_OPT_SSL_CAPATH) option, and call
mysql_options() to pass
the MYSQL_OPT_SSL_MODE option with a
value of SSL_MODE_VERIFY_CA.
To enable host name identity verification as well, call
mysql_options() to pass
the MYSQL_OPT_SSL_MODE option with a
value of SSL_MODE_VERIFY_IDENTITY
rather than SSL_MODE_VERIFY_CA.
Host name identity verification with
SSL_MODE_VERIFY_IDENTITY does not work
with self-signed certificates created automatically by the
server, or manually using
mysql_ssl_rsa_setup (see
Creating SSL and RSA Certificates and Keys using MySQL). Such
self-signed certificates do not contain the server name as
the Common Name value.
Host name identity verification also does not work with certificates that specify the Common Name using wildcards because that name is compared verbatim to the server name.