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

Author: robsdedude

docs/source/api.rst

@@ -82,19 +82,25 @@ Each supported scheme maps to a particular :class:`neo4j.Driver` subclass that i
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | URI Scheme             | Driver Object and Setting                                                                                                             |
 +========================+=======================================================================================================================================+
-| bolt                   | :ref:`bolt-driver-ref` with no encryption.                                                                                            |
+| bolt                   | :ref:`bolt-driver-ref` with no encryption or with custom encryption configuration, see :ref:`driver-configuration-ref`.               |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+ssc               | :ref:`bolt-driver-ref` with encryption (accepts self signed certificates).                                                            |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+s                 | :ref:`bolt-driver-ref` with encryption (accepts only certificates signed by a certificate authority), full certificate checks.        |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| neo4j                  | :ref:`neo4j-driver-ref` with no encryption.                                                                                           |
+| neo4j                  | :ref:`neo4j-driver-ref` with no encryption or with custom encryption configuration, see :ref:`driver-configuration-ref`.               |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | neo4j+ssc              | :ref:`neo4j-driver-ref` with encryption (accepts self signed certificates).                                                           |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
 | 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.
@@ -408,9 +414,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:
 
@@ -607,6 +616,9 @@ custom ``ssl_context`` is configured.
 ---------------
 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.
@@ -807,6 +819,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

@@ -100,19 +100,25 @@ Each supported scheme maps to a particular :class:`neo4j.AsyncDriver` subclass t
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | URI Scheme             | Driver Object and Setting                                                                                                                   |
 +========================+=============================================================================================================================================+
-| bolt                   | :ref:`async-bolt-driver-ref` with no encryption.                                                                                            |
+| bolt                   | :ref:`async-bolt-driver-ref` with no encryption or with custom encryption configuration, see :ref:`async-driver-configuration-ref`.         |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | bolt+ssc               | :ref:`async-bolt-driver-ref` with encryption (accepts self signed certificates).                                                            |
 +------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
 | 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.                                                                                           |
+| 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

@@ -61,6 +61,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