This library fully supports connecting to MySQL over SSL/TLS. In fact, all
examples make use of TLS connections, as TLS is required for the
plugin, which is the default in MySQL 8.0.
To use SSL/TLS, you must use a
that supports SSL. A SSL-enabled stream must inherit from
This includes both
To make life easier, this library provides the type alias
Note that there is no need to use TLS when using UNIX sockets. As the traffic
doesn't leave the machine, MySQL considers them secure, and will allow using
authentication plugins like
even if TLS is not used.
The SSL handshake is performed while establishing the connection to the MySQL
server, as part of the
are implemented in terms of the former, and thus also perform the TLS handshake.
This approach contrasts with libraries like Boost.Beast, where it's the user resposibility to invoke the SSL handshake on the underlying stream before performing any operation.
We take this approach because the SSL handshake is part of the MySQL protocol's handshake: the client and server exchange several unencrypted messages, then perform the SSL handshake, and continue exchanging encrypted messages, until the connection either succeeds or fails. This scheme allows the SSL negotiation feature (see below for more info).
You can set any SSL/TLS parameters on the
required to create a
using a SSL-enabled stream type. This context will be passed to the stream's
constructor. You can configure any setting allowed by
including SSL certificate validation. Check this
example for an example on this topic.
SSL shutdown is performed by the library, too, by
MySQL doesn't always close SSL connections gracefully, so these functions
ignore any errors generated by the TLS shutdown. The functions
are implemented in terms of
and thus also perform the TLS shutdown.
During the handshake, client and server will negotiate whether to use TLS
or not. For SSL capable streams, we support using TLS conditionally. This
is controlled using the
which configure the MySQL handshake process.
There are three possible values for this
require, the connection will use TLS. If the server does not support it, the connection will be refused. This is the default for SSL-enabled streams.
enable, the connection will use TLS if available, falling back to an unencrypted connection if the server does not support it.
disable, the connection will never use TLS.
If you're aiming for security, then use
If you are using
you can employ
to query whether the connection uses SSL or not.
This parameter is ignored for non-SSL connections. In this case, TLS will never be used.