4.4 TLS Configuration

Important

This section is a draft and subject to change.

Before 8.0.23, there were two TCP connections and one TLS connection:

client <-> router              // TCP
           router <-> server   // TCP
client <------------> server   // TLS

Router forwards the TLS packets as is, and this behavior can be configured with these Router configuration settings:

client_ssl_mode = PASSTHROUGH
server_ssl_mode = AS_CLIENT

Where PASSTHOUGH means "forward everything to the server" and the client and server decide if they want to switch to TLS or not.

As of 8.0.23, the default behavior is:

client_ssl_mode = PREFERRED
server_ssl_mode = AS_CLIENT

This establishes TLS connections between the client and Router if the client desires switching to TLS and the server supports TLS. This also matches the existing behaviour for client and server without the Router in-between.

TLS Endpoint Configuration

As of Router 8.0.23, Router can accept the TLS session and open a new TLS session to the server. For example:

client <-> router              // TCP
           router <-> server   // TCP
client <-> router              // TLS
           router <-> server   // TLS

To accept a TLS session from a client, Router has to present a TLS client with the certificate using client_ssl_cert and client_ssl_key.

To connect a TLS session to a server, Router verifies the server's certificates using server_ssl_verify server_ssl_verify server_ssl_ca server_ssl_capath server_ssl_crl, and server_ssl_crlpath.

Note

The TLSv1 and TLSv1.1 connection protocols are deprecated as of MySQL Router 8.0.26 and support for them is subject to removal in a future version.

SSL Modes

Because there are two TLS sessions (between client and Router; Router and server) there can also be two independent states of the connection.

Both client_ssl_mode and server_ssl_mode accept DISABLED, PREFERRED, or REQUIRED. In addition, server_ssl_mode accepts AS_CLIENT, and client_ssl_mode accepts PASSTHROUGH.

• DISABLED: Router does not offer encryption to the client, and the client can't switch the client-router connection to TLS. The client may abort the connection if it must switch to TLS.

• PREFERRED (default): Router accepts a TLS connection from the client, but is also okay if the client does not switch to encryption.

• REQUIRED: Router accepts a TLS connection from the client, and will fail if the connection is not switched to TLS before authentication finishes.

• PASSTHROUGH: Means 'forward everything to the server' and lets the client and server decide if they want to switch to TLS or not. This was default behavior before Router 8.0.23, and is only accepted by client_ssl_mode.

• AS_CLIENT (default): if the client-router connection is encrypted then also encrypt the router-server connection, otherwise do not. This option is only accepted by server_ssl_mode.

Additional Related Options

The server_ssl_verify option splits out 'VERIFY_CA' and 'VERIFY_IDENTITY' from the 'ssl_mode' that is known from the MySQL client and MySQL server. In the MySQL client's case, VERIFY_CA means ssl_mode=REQUIRED and to verify the CA|IDENTITY. In Router's case, Router verifies certificates independent of server_ssl_mode; instead it's purely based on whether the connection is encrypted and if server_ssl_verify is not DISABLED, in which case it is verified.

Additional options include server_ssl_dh_params, client_ssl_dh_params, server_ssl_dh_params, client_ssl_dh_params, server_ssl_curves, and client_ssl_curves.

All routing options and additional information is available at Routing Options.