From e4fdaf0c504b49247cb53a143afb7ac554aa40f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Tue, 28 Aug 2018 08:48:36 +0300 Subject: [PATCH] MXS-1735: Clarify SSL documentation 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. --- .../Getting-Started/Configuration-Guide.md | 65 +++++++++---------- 1 file changed, 32 insertions(+), 33 deletions(-) diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index 22f0100d9..7d452e067 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -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 involved in it. -To enable TLS/SSL for a listener or a server, you must set the `ssl` parameter -to `required` and provide the three files for `ssl_cert`, `ssl_key` and -`ssl_ca_cert`. +To enable TLS/SSL for a listener, you must set the `ssl` parameter to `required` +and provide the three files for `ssl_cert`, `ssl_key` and `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 -encrypted. Note that the database must be configured to use TLS/SSL connections -if backend connection encryption is used. +encrypted. Note that the database must also be configured to use TLS/SSL +connections if backend connection encryption is used. **Note:** MaxScale does not allow mixed use of TLS/SSL and normal connections on the same port. If TLS encryption is enabled for a listener, any unencrypted connections to it 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 server which allows both secure and insecure connections on the same port. As @@ -1407,33 +1411,34 @@ server does. #### `ssl` -This enables SSL connections when set to `required`. If enabled, the three -certificate files mentioned below must also be supplied. MaxScale connections -to will then be encrypted with TLS/SSL. +This enables SSL connections when set to `required`. If enabled, the certificate +files mentioned above must also be supplied. MaxScale connections to will then +be encrypted with TLS/SSL. #### `ssl_key` 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 -parameter for SSL enabled configurations. +must be the SSL private key MaxScale should use. #### `ssl_cert` 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 -a required parameter for SSL enabled configurations. The certificate must match -the key defined in `ssl_key`. +must be the SSL public certificate MaxScale should use. The certificate must +match the key defined in `ssl_key`. #### `ssl_ca_cert` 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 -certificate referred to in the previous parameter. It will be used to verify -that the certificate is valid. This is a required parameter for SSL enabled -configurations. +must be the Certificate Authority (CA) certificate that will be used to validate +any public certificates. This is a required parameter for SSL enabled +configurations. The CA certificate can consist of a certificate chain. #### `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: * TLSv10 @@ -1442,18 +1447,13 @@ This parameter controls the level of encryption used. Accepted values are: * MAX 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 -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. +and newer this is TLSv1.2. #### `ssl_cert_verify_depth` -The maximum length of the certificate authority chain that will be accepted. -Legal values are positive integers. Note that if the client is to submit an SSL -certificate, the `ssl_cert_verify_depth` parameter must not be 0. If no -value is specified, the default is 9. +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` @@ -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 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] @@ -1475,19 +1475,18 @@ ssl=required ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.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 - ``` This example configuration requires all connections to this server to be encrypted with SSL. The paths to the certificate files and the Certificate Authority file are also provided. -**Example SSL enabled listener configuration:** +#### Example SSL enabled listener configuration ``` -[RW Split Listener] +[RW-Split-Listener] type=listener -service=RW Split Router +service=RW-Split-Router protocol=MariaDBClient port=3306 ssl=required