Some adjustments re. switchover to default certificate verification

Author: amotl

docs/connect.rst

@@ -100,30 +100,26 @@ URL:
 
     >>> connection = client.connect('https://localhost:4200/', ...)
 
-.. CAUTION::
-
-    By default, server certificates are *not* verified.
-
 .. SEEALSO::
 
     The CrateDB reference has a section on `setting up SSL`_. This will be
-    useful background reading for the following two subsections.
+    a useful background reading for the following two subsections.
 
 Server verification
 ...................
 
-You can enable server SSL certificate verification by passing in the
-``verify_ssl_cert`` keyword argument and setting it to ``True``.
+Server certificates are verified by default. In order to connect to a
+SSL-enabled host using self-signed certificates, you will need to provide the
+CA certificate file used to sign the server SSL certificate::
 
-However, in order to do so, you also need to specify the certificate file of
-the *Certificate Authority* (CA) used to sign the server SSL certificate. You
-can do this using the ``ca_cert`` keyword argument.
+    >>> connection = client.connect(..., ca_cert="<CA_CERT_FILE>")
 
-Here's how you might do that::
+Here, replace ``<CA_CERT_FILE>`` with the path to the CA certificate file.
 
-    >>> connection = client.connect(..., ca_cert="<CA_CERT_FILE>", verify_ssl_cert=True)
+You can disable server SSL certificate verification by using the
+``verify_ssl_cert`` keyword argument and setting it to ``False``::
 
-Here, replace ``<CA_CERT_FILE>`` with the path to the CA certificate file.
+    >>> connection = client.connect(..., verify_ssl_cert=False)
 
 
 Client verification
@@ -148,7 +144,7 @@ Timeout
 -------
 
 Connection timeouts (in seconds) can be configured with the optional
-``timeout`` argument:
+``timeout`` argument::
 
     >>> connection = client.connect(..., timeout=5)
 

docs/sqlalchemy.rst

@@ -105,21 +105,29 @@ the ``connect_args`` argument, like so::
 When you do this, the Database API layer will use its :ref:`round-robin
 <multiple-nodes>` implementation.
 
-The client validates `SSL server certificates`_ by default. To configure
-this behaviour, SSL verification options can be passed in via ``connect_args``
-too::
+The client validates `SSL server certificates`_ by default. For further
+adjusting this behaviour, SSL verification options can be passed in by using
+the ``connect_args`` dictionary. For example, use ``ca_cert`` for providing
+a path to the CA certificate used for signing the server certificate::
 
     >>> engine = sa.create_engine(
     ...     'crate://',
     ...     connect_args={
     ...         'servers': ['198.51.100.1:4200', '198.51.100.2:4200'],
-    ...         'verify_ssl_cert': True,
     ...         'ca_cert': '<PATH_TO_CA_CERT>',
     ...     }
     ... )
 
-Here, ``<PATH_TO_CA_CERT>`` should be replaced with the path to the correct CA
-certificate.
+In order to disable SSL verification, use ``verify_ssl_cert = False``, like::
+
+    >>> engine = sa.create_engine(
+    ...     'crate://',
+    ...     connect_args={
+    ...         'servers': ['198.51.100.1:4200', '198.51.100.2:4200'],
+    ...         'verify_ssl_cert': False,
+    ...     }
+    ... )
+
 
 Get a session
 .............

src/crate/client/connection.py

@@ -61,7 +61,7 @@ def __init__(self,
             (optional - for testing)
             client used to communicate with crate.
         :param verify_ssl_cert:
-            if set to ``True`` verify the servers SSL server certificate.
+            if set to ``False``, disable SSL server certificate verification.
             defaults to ``True``
         :param ca_cert:
             a path to a CA certificate to use when verifying the SSL server

src/crate/client/doctests/sqlalchemy.txt

@@ -32,18 +32,27 @@ The ``connect_args`` parameter has to be used to do so::
     ... })
     Engine(crate://)
 
-As defined in :ref:`https_connection` the client validates SSL server
-certificates by default. To configure this behaviour, SSL verification options
-can be given via ``connect_args`` too::
+As defined in :ref:`https_connection`, the client validates SSL server
+certificates by default. To configure this further, use e.g. the ``ca_cert``
+attribute within the ``connect_args``, like::
 
     >>> ssl_engine = sa.create_engine(
     ...     'crate://',
     ...     connect_args={
     ...         'servers': ['https://host1:4200'],
-    ...         'verify_ssl_cert': True,
     ...         'ca_cert': '/path/to/cacert.pem',
     ...     })
 
+In order to disable SSL verification, use ``verify_ssl_cert = False``, like::
+
+    >>> ssl_engine = sa.create_engine(
+    ...     'crate://',
+    ...     connect_args={
+    ...         'servers': ['https://host1:4200'],
+    ...         'verify_ssl_cert': False,
+    ...     })
+
+
 Complex Types
 =============