Boost C++ Libraries

To use SSL/TLS, you must use a connection with a Stream that supports SSL. A SSL-enabled stream must inherit from boost::asio::ssl::stream_base. This includes both boost::asio::ssl::stream and boost::beast::ssl_stream.

To make life easier, this library provides the type alias tcp_ssl_connection.

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 caching_sha2_password even if TLS is not used.

The SSL handshake is performed while establishing the connection to the MySQL server, as part of the connection::handshake and connection::async_handshake. The functions connection::connect and connection::async_connect 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 boost::asio::ssl::context required to create a connection using a SSL-enabled stream type. This context will be passed to the stream's constructor. You can configure any setting allowed by boost::asio::ssl::context, including SSL certificate validation. Check this example for an example on this topic.

If SSL certificate validation is enabled and fails, the connection::handshake or connection::async_handshake operation will fail with the relevant error code.

SSL shutdown is performed by the library, too, by connection::quit and connection::async_quit. MySQL doesn't always close SSL connections gracefully, so these functions ignore any errors generated by the TLS shutdown. The functions connection::close and connection::async_close are implemented in terms of connection::quit and connection::async_quit, 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 ssl_mode parameter in handshake_params, which configure the MySQL handshake process.

There are three possible values for this ssl_mode:

If you're aiming for security, then use require (the default).

If you are using enable, you can employ connection::uses_ssl 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.

See this section for more information on handshake_params.