Enabling TLS on MaxScale

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

Enabling TLS

Step 1: Acquire Certificates and Keys

Acquire X.509 certificates and private keys for the MaxScale instance.

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

The configuration examples below assume that the certificates and keys will be located at the following paths:

  • For server sections:

    • Certificate: /etc/ssl/maxscale/server-cert.pem

    • Private Key: /etc/ssl/maxscale/server-key.pem

  • For listener sections:

    • Certificate: /etc/ssl/maxscale/listener-cert.pem

    • Private Key: /etc/ssl/maxscale/listener-key.pem

Ensure that the file system privileges are properly set, so that MaxScale can read the certificate and private key files, while still protecting the private key files from unauthorized users.

Note

Starting with MaxScale 2.5.20 if the ssl_cert used has the X509v3 extended key usage information, MaxScale will check, and honor it. This means that a certificate with only clientAuth can only be used with servers and a certificate with only serverAuth can only be used with listeners. In order to use the same certificate for both listeners and servers, it must have both the clientAuth, and serverAuth usages. See the TLS/SSL Encryption section of the MariaDB MaxScale configuration guide for more details.

Step 2: Configure server Sections

For each server section in your maxscale.cnf, configure the TLS parameters:

[server1]
type       = server
address    = 192.0.2.2
port       = 3306
ssl        = true
ssl_cert   = /etc/ssl/maxscale/server-cert.pem
ssl_key    = /etc/ssl/maxscale/server-key.pem
ssl_ca     = /etc/ssl/maxscale/ca.pem

When enabling TLS in a server section, the following parameters are mandatory:

Parameter

Description

ssl

Set to true to enable TLS

ssl_cert

Path to the X.509 certificate file in PEM format

ssl_key

Path to the non-encrypted PKCS #8 private key file in PEM format

ssl_ca

Path to the X.509 certificate authority chain file in PEM format. In MaxScale 22.08 and before, the deprecated ssl_ca_cert parameter can be used instead, but MariaDB recommends switching to the new parameter.

The following parameters are optional, but useful:

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

Path to the X.509 certificate revocation list in PEM format

Step 3: Configure listener Sections

For each listener section in your maxscale.cnf, configure the TLS parameters:

[split-router-listener]
type       = listener
service    = split-router
protocol   = MariaDBClient
port       = 3306
ssl        = true
ssl_cert   = /etc/ssl/maxscale/listener-cert.pem
ssl_key    = /etc/ssl/maxscale/listener-key.pem
ssl_ca     = /etc/ssl/maxscale/ca.pem

...

[connection-router-listener]
type       = listener
service    = connection-router
protocol   = MariaDBClient
port       = 3307
ssl        = true
ssl_cert   = /etc/ssl/maxscale/listener-cert.pem
ssl_key    = /etc/ssl/maxscale/listener-key.pem
ssl_ca     = /etc/ssl/maxscale/ca.pem

When enabling TLS in a listener section, the following parameters are mandatory:

Parameter

Description

ssl

Set to true to enable TLS

ssl_cert

Path to the X.509 certificate file in PEM format

ssl_key

Path to the non-encrypted PKCS #8 private key file in PEM format

ssl_ca

Path to the X.509 certificate authority chain file in PEM format. In MaxScale 22.08 and before, the deprecated ssl_ca_cert parameter can be used instead, but MariaDB recommends switching to the new parameter.

The following parameters are optional, but useful:

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

Path to the X.509 certificate revocation list in PEM format

Step 4: Restart MaxScale

Restart the MaxScale node:

$ sudo systemctl restart maxscale