diff --git a/docs/source/api.rst b/docs/source/api.rst index 67d8ecf8..3cb84518 100644 --- a/docs/source/api.rst +++ b/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 ====================== diff --git a/docs/source/async_api.rst b/docs/source/async_api.rst index fc009728..13377961 100644 --- a/docs/source/async_api.rst +++ b/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. diff --git a/src/neo4j/_conf.py b/src/neo4j/_conf.py index 58d3c524..bd9eb801 100644 --- a/src/neo4j/_conf.py +++ b/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