[/
    Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
   
    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:ssl SSL/TLS]
[nochunk]

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 
[mysqllink caching-sha2-pluggable-authentication.html `caching_sha2_password`]
authentication plugin, which is the default in MySQL 8.0.

[heading SSL-enabled streams]

To use SSL/TLS, you must use a [reflink connection] with a 
[reflink Stream] that supports SSL. A SSL-enabled stream must inherit from
[asioreflink ssl__stream_base ssl::stream_base]. This includes both
[asioreflink ssl__stream ssl::stream] and `boost::beast::ssl_stream`.

To make life easier, this library provides the type alias [reflink 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.



[heading When is the SSL handshake performed?]

The SSL handshake is performed while establishing the connection to the MySQL server,
as part of the [refmem connection handshake] and [refmem connection async_handshake]. The functions
[refmem connection connect] and [refmem connection async_connect] are implemented in terms of the former,
and thus also perform the TLS handshake. 

This approach contrasts with libraries like __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 [asioreflink ssl__context ssl::context] required
to create a [reflink connection] using a SSL-enabled stream type. This context will be passed
to the stream's constructor. You can configure any setting allowed by [asioreflink ssl__context ssl::context],
including SSL certificate validation. Check [link mysql.examples.ssl this example] for an example
on this topic.

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

SSL shutdown is performed by the library, too, by [refmem connection quit] and 
[refmem connection async_quit]. MySQL doesn't always close SSL connections
gracefully, so these functions ignore any errors generated by the TLS shutdown.
The functions [refmem connection close] and [refmem connection async_close]
are implemented in terms of [refmem connection quit] and 
[refmem connection async_quit], and thus also perform the TLS shutdown. 


[heading:negotiation 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 [reflink ssl_mode]
parameter in [reflink handshake_params], which configure the MySQL handshake process.

There are three possible values for this [reflink 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
[refmem 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 [link mysql.connparams this section] for more information on [reflink handshake_params].


[endsect]