Enabling TLS on MaxScale

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

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

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

  3. 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
    
  4. 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

  5. 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
    
  6. Consider also enabling TLS for MaxScale's REST API.

  7. Restart the MaxScale instance.

    $ sudo systemctl restart maxscale