API docs: explain security config options interplay (#1239)

Author: robsdedude

docs/source/api.rst

@@ -95,6 +95,12 @@ Each supported scheme maps to a particular :class:`neo4j.Driver` subclass that i
 | neo4j+s                | :ref:`neo4j-driver-ref` with encryption (accepts only certificates signed by a certificate authority), full certificate checks.       |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 
+
+.. note::
+
+    See also :ref:`encryption-config-note-ref` to understand how the URI scheme relates to other encryption configuration options.
+
+
 .. note::
 
     See https://neo4j.com/docs/operations-manual/current/configuration/ports/ for Neo4j ports.
@@ -413,9 +419,12 @@ Additional configuration can be provided via the :class:`neo4j.Driver` construct
 + :ref:`user-agent-ref`
 + :ref:`driver-notifications-min-severity-ref`
 + :ref:`driver-notifications-disabled-categories-ref`
++ :ref:`driver-notifications-disabled-classifications-ref`
 + :ref:`driver-warn-notification-severity-ref`
 + :ref:`telemetry-disabled-ref`
 
+:ref:`encryption-config-note-ref`
+
 
 .. _connection-acquisition-timeout-ref:
 
@@ -594,6 +603,9 @@ For example:
 ---------------
 Specify a custom SSL context to use for wrapping connections.
 
+The driver offers other, easier APIs for common encryption configurations (see :ref:`encryption-config-note-ref`).
+It's likely that your use-case doesn't actually require this options.
+
 This setting is only available for URI schemes ``bolt://`` and ``neo4j://`` (:ref:`uri-ref`).
 
 If given, ``encrypted``, ``trusted_certificates``, and ``client_certificate`` have no effect.
@@ -794,6 +806,23 @@ The driver transmits the following information:
 .. versionadded:: 5.13
 
 
+.. _encryption-config-note-ref:
+
+Note on Encryption Configuration
+--------------------------------
+There are different *mutually exclusive* ways of configuring TLS/SSL encryption behavior of the driver:
+
+* Use a URI scheme ending in ``+s``. This auto-configures the driver to use TLS and only trust system CAs.
+* Use a URI scheme ending in ``+ssc``. This auto-configures the driver to use TLS and trust any certificate.
+* Use a URI scheme without suffix (i.e. ``neo4j://`` or ``bolt://``) and one of the following mutually exclusive options:
+
+  * set :ref:`encrypted-ref` to ``True`` and optionally configure :ref:`trusted-certificates-ref` and/or
+    :ref:`client-certificate-ref` to enable TLS with custom security settings.
+  * or set :ref:`ssl-context-ref` to gain full control (and responsibility) over the TLS configuration.
+  * or set ``encrypted=False`` (default) to disable TLS.
+
+
+
 Driver Object Lifetime
 ======================
 

docs/source/async_api.rst

@@ -101,13 +101,19 @@ Each supported scheme maps to a particular :class:`neo4j.AsyncDriver` subclass t
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+s                 | :ref:`async-bolt-driver-ref` with encryption (accepts only certificates signed by a certificate authority), full certificate checks.        |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
-| neo4j                  | :ref:`async-neo4j-driver-ref` with no encryption or with custom encryption configuration, see :ref:`async-driver-configuration-ref`.         |
+| neo4j                  | :ref:`async-neo4j-driver-ref` with no encryption or with custom encryption configuration, see :ref:`async-driver-configuration-ref`.        |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | neo4j+ssc              | :ref:`async-neo4j-driver-ref` with encryption (accepts self signed certificates).                                                           |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | neo4j+s                | :ref:`async-neo4j-driver-ref` with encryption (accepts only certificates signed by a certificate authority), full certificate checks.       |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 
+
+.. note::
+
+    See also :ref:`encryption-config-note-ref` to understand how the URI scheme relates to other encryption configuration options.
+
+
 .. note::
 
     See https://neo4j.com/docs/operations-manual/current/configuration/ports/ for Neo4j ports.

src/neo4j/_conf.py

@@ -59,6 +59,9 @@ class TrustSystemCAs(TrustStore):
     certificate authority. This option is primarily intended for use with
     full certificates.
 
+    The driver loads the trusted system CAs using Python's
+    :meth:`ssl.SSLContext.load_default_certs`.
+
     For example::
 
         import neo4j