Enabling TLS on MaxScale

This page is part of MariaDB's MariaDB Documentation.

The parent of this page is: Data-in-Transit Encryption for MariaDB MaxScale

Topics on this page:

Overview
Enabling TLS

Overview

MariaDB MaxScale supports data-in-transit encryption, which secures data transmitted over the network. The server and the clients encrypt data using the Transport Layer Security (TLS) protocol, which is a newer version of the Secure Socket Layer (SSL) protocol.

TLS must be manually enabled on the MaxScale instance.

Enabling TLS

Acquire an X509 certificate and a private key for the MaxScale instance.

If it is a test or development instance, then self-signed certificates and keys might be sufficient.

For each server in your maxscale.cnf, determine which TLS parameters you need to configure.

Mandatory parameters for TLS include:

Parameter	Description
`ssl`	Set to true to enable TLS
`ssl_cert`	X509 key in PEM format
`ssl_key`	X509 cert in PEM format
`ssl_ca_cert`	CA file in PEM format

Useful parameters for TLS include:

Parameter	Description
`ssl_version`	The TLS protocol version to use. It can be set to `TLSv10`, `TLSv11`, `TLSv12`, `TLSv13`, or `MAX`. The default value is `MAX`.
:`ssl_cipher`	SSL cipher to use
`ssl_cert_verify_depth`	The maximum length of the certificate authority chain that will be accepted. The default value is 9, same as the OpenSSL default. The configured value must be larger than 0.
`ssl_verify_peer_certificate`	Peer certificate verification. This functionality is disabled by default. In versions prior to 2.3.17 the feature was enabled by default.
`ssl_verify_peer_host`	Peer host verification. This parameter takes a boolean value and is disabled by default.
`ssl_crl	CRL file in PEM format

Set your server parameters in maxscale.cnf.

Each server in your maxscale.cnf has a uniquely-named configuration group. The name of the configuration group is arbitrary, but it cannot contain any white space. Use whatever terms you find most convenient, but it is most common to use names like serverN or the server's host name.

For example:
```
[server1]
type     = server
address  = 192.0.2.2
port     = 3306
protocol = MariaDBBackend
ssl           = true
ssl_cert      = /certs/server-cert.pem
ssl_key       = /certs/server-key.pem
ssl_ca_cert   = /certs/ca-cert.pem
```

For each listener in your maxscale.cnf, determine which TLS parameters you need to configure.

Mandatory parameters for TLS include:

Parameter	Description
`ssl`	Set to true to enable TLS
`ssl_cert`	X509 key in PEM format
`ssl_key`	X509 cert in PEM format
`ssl_ca_cert`	CA file in PEM format

Useful parameters for TLS include:

Parameter	Description
`ssl_version`	The TLS protocol version to use. It can be set to `TLSv10`, `TLSv11`, `TLSv12`, `TLSv13`, or `MAX`. The default value is `MAX`.
:`ssl_cipher`	SSL cipher to use
`ssl_cert_verify_depth`	The maximum length of the certificate authority chain that will be accepted. The default value is 9, same as the OpenSSL default. The configured value must be larger than 0.
`ssl_verify_peer_certificate`	Peer certificate verification. This functionality is disabled by default. In versions prior to 2.3.17 the feature was enabled by default.
`ssl_verify_peer_host`	Peer host verification. This parameter takes a boolean value and is disabled by default.
`ssl_crl	CRL file in PEM format

Set your listener parameters in maxscale.cnf.

Each listener in your maxscale.cnf has a uniquely-named configuration group. The name of the configuration group is arbitrary, but it cannot contain any white space. Use whatever terms you find most convenient, but it is most common to use names like split-router-listener.

For example:

[split-router-listener]
type     = listener
service  = split-router
protocol = MariaDBClient
port     = 3306
ssl           = true
ssl_cert      = /certs/server-cert.pem
ssl_key       = /certs/server-key.pem
ssl_ca_cert   = /certs/ca-cert.pem

...

[connection-router-listener]
type     = listener
service  = connection-router
protocol = MariaDBClient
port     = 3307
ssl           = true
ssl_cert      = /certs/server-cert.pem
ssl_key       = /certs/server-key.pem
ssl_ca_cert   = /certs/ca-cert.pem

Consider also enabling TLS for MaxScale's REST API.
Restart the MaxScale instance.
```
$ sudo systemctl restart maxscale
```