| Home | Libraries | People | FAQ | More

## SSL/TLS

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 `caching_sha2_password` authentication plugin, which is the default in MySQL 8.0.

#### SSL-enabled streams

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.

#### When is the SSL handshake performed?

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.

#### SSL negotiation

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 set to `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.
- If set to `enable`, the connection will use TLS if available, falling back to an unencrypted connection if the server does not support it.
- If set to `disable`, the connection will never use TLS.

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`.