hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-1735: Clarify SSL documentation

Browse Source 
Explicitly state that servers only require `ssl_ca_cert` and that
`ssl_cert` and `ssl_key` are optional in certain cases. Updated the
wording of all parameters and removed obsolete or false documentation.
This commit is contained in:
Markus Mäkelä
2018-08-28 08:48:36 +03:00
parent 39016c410c
commit e4fdaf0c50
1 changed files with 32 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
Documentation/Getting-Started/Configuration-Guide.md
View File

@ -1384,20 +1384,24 @@ This section describes configuration parameters for both servers and listeners
that control the TLS/SSL encryption method and the various certificate files that control the TLS/SSL encryption method and the various certificate files
involved in it. involved in it.
To enable TLS/SSL for a listener or a server, you must set the `ssl` parameter To enable TLS/SSL for a listener, you must set the `ssl` parameter to `required`
to `required` and provide the three files for `ssl_cert`, `ssl_key` and and provide the three files for `ssl_cert`, `ssl_key` and `ssl_ca_cert`.
`ssl_ca_cert`.
To enable TLS/SSL for a server, you must set the `ssl` parameter to `required`
and provide at least the `ssl_ca_cert` parameter. If the backend database server
has certificate verification enabled, the `ssl_cert` and `ssl_key` parameters
must also be defined.
After this, MaxScale connections between the server and/or the client will be After this, MaxScale connections between the server and/or the client will be
encrypted. Note that the database must be configured to use TLS/SSL connections encrypted. Note that the database must also be configured to use TLS/SSL
if backend connection encryption is used. connections if backend connection encryption is used.
**Note:** MaxScale does not allow mixed use of TLS/SSL and normal connections on **Note:** MaxScale does not allow mixed use of TLS/SSL and normal connections on
the same port. the same port.
If TLS encryption is enabled for a listener, any unencrypted connections to it If TLS encryption is enabled for a listener, any unencrypted connections to it
will be rejected. MaxScale does this to improve security by preventing will be rejected. MaxScale does this to improve security by preventing
accidental creation on unencrypted connections. accidental creation of unencrypted connections.
The separation of secure and insecure connections differs from the MariaDB The separation of secure and insecure connections differs from the MariaDB
server which allows both secure and insecure connections on the same port. As server which allows both secure and insecure connections on the same port. As
@ -1407,33 +1411,34 @@ server does.
#### `ssl` #### `ssl`
This enables SSL connections when set to `required`. If enabled, the three This enables SSL connections when set to `required`. If enabled, the certificate
certificate files mentioned below must also be supplied. MaxScale connections files mentioned above must also be supplied. MaxScale connections to will then
to will then be encrypted with TLS/SSL. be encrypted with TLS/SSL.
#### `ssl_key` #### `ssl_key`
A string giving a file path that identifies an existing readable file. The file A string giving a file path that identifies an existing readable file. The file
must be the SSL client private key MaxScale should use. This is a required must be the SSL private key MaxScale should use.
parameter for SSL enabled configurations.
#### `ssl_cert` #### `ssl_cert`
A string giving a file path that identifies an existing readable file. The file A string giving a file path that identifies an existing readable file. The file
must be the SSL client certificate MaxScale should use with the server. This is must be the SSL public certificate MaxScale should use. The certificate must
a required parameter for SSL enabled configurations. The certificate must match match the key defined in `ssl_key`.
the key defined in `ssl_key`.
#### `ssl_ca_cert` #### `ssl_ca_cert`
A string giving a file path that identifies an existing readable file. The file A string giving a file path that identifies an existing readable file. The file
must be the Certificate Authority (CA) certificate for the CA that signed the must be the Certificate Authority (CA) certificate that will be used to validate
certificate referred to in the previous parameter. It will be used to verify any public certificates. This is a required parameter for SSL enabled
that the certificate is valid. This is a required parameter for SSL enabled configurations. The CA certificate can consist of a certificate chain.
configurations.
#### `ssl_version` #### `ssl_version`
**Note:** It is highly recommended to leave this parameter to the default value
of _MAX_. This will guarantee that the strongest available encryption is used.
**Do not change this unless you know what you are doing**.
This parameter controls the level of encryption used. Accepted values are: This parameter controls the level of encryption used. Accepted values are:
* TLSv10 * TLSv10
@ -1442,18 +1447,13 @@ This parameter controls the level of encryption used. Accepted values are:
* MAX * MAX
The default is to use the highest level of encryption available. For OpenSSL 1.0 The default is to use the highest level of encryption available. For OpenSSL 1.0
and newer this is TLSv1.2. Older versions use TLSv1.0 as the default transport and newer this is TLSv1.2.
layer encryption.
**Note:** It is highly recommended to leave this parameter to the default value
of _MAX_. This will guarantee that the strongest available encryption is used.
#### `ssl_cert_verify_depth` #### `ssl_cert_verify_depth`
The maximum length of the certificate authority chain that will be accepted. The maximum length of the certificate authority chain that will be accepted. The
Legal values are positive integers. Note that if the client is to submit an SSL default value is 9, same as the OpenSSL default. The configured value must be
certificate, the `ssl_cert_verify_depth` parameter must not be 0. If no larger than 0.
value is specified, the default is 9.
#### `ssl_verify_peer_certificate` #### `ssl_verify_peer_certificate`
@ -1461,9 +1461,9 @@ Peer certificate verification. This functionality is enabled by default.
When this feature is enabled, the certificate sent by the peer is verified When this feature is enabled, the certificate sent by the peer is verified
against the configured Certificate Authority. If you are using self-signed against the configured Certificate Authority. If you are using self-signed
certificates, disable this feature. certificates, set `ssl_verify_peer_certificate=false`.
**Example SSL enabled server configuration:** #### Example SSL enabled server configuration
``` ```
[server1] [server1]
@ -1475,19 +1475,18 @@ ssl=required
ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.max-client.pem ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.max-client.pem
ssl_key=/usr/local/mariadb/maxscale/ssl/key.max-client.pem ssl_key=/usr/local/mariadb/maxscale/ssl/key.max-client.pem
ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem
``` ```
This example configuration requires all connections to this server to be This example configuration requires all connections to this server to be
encrypted with SSL. The paths to the certificate files and the Certificate encrypted with SSL. The paths to the certificate files and the Certificate
Authority file are also provided. Authority file are also provided.
**Example SSL enabled listener configuration:** #### Example SSL enabled listener configuration
``` ```
[RW Split Listener] [RW-Split-Listener]
type=listener type=listener
service=RW Split Router service=RW-Split-Router
protocol=MariaDBClient protocol=MariaDBClient
port=3306 port=3306
ssl=required ssl=required