Deprecate old SSL config options instead of removing them

CHANGELOG.md

@@ -12,7 +12,7 @@
   Use `ResultSummary.server.agent`, `ResultSummary.server.protocol_version`,
   or call the `dbms.components` procedure instead.
 - SSL configuration options have been changed:
-  - `trust` has been removed.  
+  - `trust` has been deprecated and will be removed in a future release.  
     Use `trusted_certificates` instead which expects `None` or a `list`. See the
     API documentation for more details.
 - `neo4j.time` module:

docs/source/api.rst

@@ -164,6 +164,7 @@ Additional configuration can be provided via the :class:`neo4j.Driver` construct
 + :ref:`max-connection-pool-size-ref`
 + :ref:`max-transaction-retry-time-ref`
 + :ref:`resolver-ref`
++ :ref:`trust-ref`
 + :ref:`ssl-context-ref`
 + :ref:`trusted-certificates-ref`
 + :ref:`user-agent-ref`
@@ -276,6 +277,36 @@ For example:
 :Default: :const:`None`
 
 
+.. _trust-ref:
+
+``trust``
+---------
+Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance on connection.
+
+This setting does not have any effect if ``encrypted`` is set to ``False``.
+
+:Type: ``neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES``, ``neo4j.TRUST_ALL_CERTIFICATES``
+
+.. py:attribute:: neo4j.TRUST_ALL_CERTIFICATES
+
+   Trust any server certificate (default). This ensures that communication
+   is encrypted but does not verify the server certificate against a
+   certificate authority. This option is primarily intended for use with
+   the default auto-generated server certificate.
+
+.. py:attribute:: neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
+
+   Trust server certificates that can be verified against the system
+   certificate authority. This option is primarily intended for use with
+   full certificates.
+
+:Default: ``neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES``.
+
+.. deprecated:: 5.0
+    This configuration option is deprecated and will be removed in a future
+    release. Please use :ref:`trusted-certificates-ref` instead.
+
+
 .. _ssl-context-ref:
 
 ``ssl_context``
@@ -287,6 +318,8 @@ If give, ``encrypted`` and ``trusted_certificates`` have no effect.
 :Type: :class:`ssl.SSLContext` or :const:`None`
 :Default: :const:`None`
 
+.. versionadded:: 5.0
+
 
 .. _trusted-certificates-ref:
 
@@ -317,6 +350,8 @@ custom ``ssl_context`` is configured.
 
 :Default: :const:`None`
 
+.. versionadded:: 5.0
+
 
 .. _user-agent-ref:
 

neo4j/__init__.py

@@ -54,6 +54,8 @@
     "SessionConfig",
     "SummaryCounters",
     "Transaction",
+    "TRUST_ALL_CERTIFICATES",
+    "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES",
     "unit_of_work",
     "Version",
     "WorkspaceConfig",
@@ -105,6 +107,8 @@
     READ_ACCESS,
     ServerInfo,
     SYSTEM_DATABASE,
+    TRUST_ALL_CERTIFICATES,
+    TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
     Version,
     WRITE_ACCESS,
 )

neo4j/_async/driver.py

@@ -20,7 +20,11 @@
 
 from .._async_compat.util import AsyncUtil
 from ..addressing import Address
-from ..api import READ_ACCESS
+from ..api import (
+    READ_ACCESS,
+    TRUST_ALL_CERTIFICATES,
+    TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
+)
 from ..conf import (
     Config,
     PoolConfig,
@@ -71,20 +75,47 @@ def driver(cls, uri, *, auth=None, **config):
 
         driver_type, security_type, parsed = parse_neo4j_uri(uri)
 
-        if security_type in [SECURITY_TYPE_SELF_SIGNED_CERTIFICATE, SECURITY_TYPE_SECURE] and ("encrypted" in config.keys() or "trusted_certificates" in config.keys()):
+        # TODO: 6.0 remove "trust" config option
+        if "trust" in config.keys():
+            if config["trust"] not in (TRUST_ALL_CERTIFICATES,
+                                       TRUST_SYSTEM_CA_SIGNED_CERTIFICATES):
+                from neo4j.exceptions import ConfigurationError
+                raise ConfigurationError(
+                    "The config setting `trust` values are {!r}"
+                    .format(
+                        [
+                            TRUST_ALL_CERTIFICATES,
+                            TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
+                        ]
+                    )
+                )
+
+        if (security_type in [SECURITY_TYPE_SELF_SIGNED_CERTIFICATE, SECURITY_TYPE_SECURE]
+            and ("encrypted" in config.keys()
+                 or "trust" in config.keys()
+                 or "trusted_certificates" in config.keys()
+                 or "ssl_context" in config.keys())):
             from neo4j.exceptions import ConfigurationError
-            raise ConfigurationError("The config settings 'encrypted' and 'trust' can only be used with the URI schemes {!r}. Use the other URI schemes {!r} for setting encryption settings.".format(
-                [
-                    URI_SCHEME_BOLT,
-                    URI_SCHEME_NEO4J,
-                ],
-                [
-                    URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE,
-                    URI_SCHEME_BOLT_SECURE,
-                    URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE,
-                    URI_SCHEME_NEO4J_SECURE,
-                ]
-            ))
+
+            # TODO: 6.0 remove "trust" from error message
+            raise ConfigurationError(
+                'The config settings "encrypted", "trust", '
+                '"trusted_certificates", and "ssl_context" can only be used '
+                "with the URI schemes {!r}. Use the other URI schemes {!r} "
+                "for setting encryption settings."
+                .format(
+                    [
+                        URI_SCHEME_BOLT,
+                        URI_SCHEME_NEO4J,
+                    ],
+                    [
+                        URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE,
+                        URI_SCHEME_BOLT_SECURE,
+                        URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE,
+                        URI_SCHEME_NEO4J_SECURE,
+                    ]
+                )
+            )
 
         if security_type == SECURITY_TYPE_SECURE:
             config["encrypted"] = True

neo4j/_sync/driver.py

@@ -20,7 +20,11 @@
 
 from .._async_compat.util import Util
 from ..addressing import Address
-from ..api import READ_ACCESS
+from ..api import (
+    READ_ACCESS,
+    TRUST_ALL_CERTIFICATES,
+    TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
+)
 from ..conf import (
     Config,
     PoolConfig,
@@ -71,20 +75,47 @@ def driver(cls, uri, *, auth=None, **config):
 
         driver_type, security_type, parsed = parse_neo4j_uri(uri)
 
-        if security_type in [SECURITY_TYPE_SELF_SIGNED_CERTIFICATE, SECURITY_TYPE_SECURE] and ("encrypted" in config.keys() or "trusted_certificates" in config.keys()):
+        # TODO: 6.0 remove "trust" config option
+        if "trust" in config.keys():
+            if config["trust"] not in (TRUST_ALL_CERTIFICATES,
+                                       TRUST_SYSTEM_CA_SIGNED_CERTIFICATES):
+                from neo4j.exceptions import ConfigurationError
+                raise ConfigurationError(
+                    "The config setting `trust` values are {!r}"
+                    .format(
+                        [
+                            TRUST_ALL_CERTIFICATES,
+                            TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
+                        ]
+                    )
+                )
+
+        if (security_type in [SECURITY_TYPE_SELF_SIGNED_CERTIFICATE, SECURITY_TYPE_SECURE]
+            and ("encrypted" in config.keys()
+                 or "trust" in config.keys()
+                 or "trusted_certificates" in config.keys()
+                 or "ssl_context" in config.keys())):
             from neo4j.exceptions import ConfigurationError
-            raise ConfigurationError("The config settings 'encrypted' and 'trust' can only be used with the URI schemes {!r}. Use the other URI schemes {!r} for setting encryption settings.".format(
-                [
-                    URI_SCHEME_BOLT,
-                    URI_SCHEME_NEO4J,
-                ],
-                [
-                    URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE,
-                    URI_SCHEME_BOLT_SECURE,
-                    URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE,
-                    URI_SCHEME_NEO4J_SECURE,
-                ]
-            ))
+
+            # TODO: 6.0 remove "trust" from error message
+            raise ConfigurationError(
+                'The config settings "encrypted", "trust", '
+                '"trusted_certificates", and "ssl_context" can only be used '
+                "with the URI schemes {!r}. Use the other URI schemes {!r} "
+                "for setting encryption settings."
+                .format(
+                    [
+                        URI_SCHEME_BOLT,
+                        URI_SCHEME_NEO4J,
+                    ],
+                    [
+                        URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE,
+                        URI_SCHEME_BOLT_SECURE,
+                        URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE,
+                        URI_SCHEME_NEO4J_SECURE,
+                    ]
+                )
+            )
 
         if security_type == SECURITY_TYPE_SECURE:
             config["encrypted"] = True

neo4j/api.py

@@ -48,6 +48,10 @@
 
 URI_SCHEME_BOLT_ROUTING = "bolt+routing"
 
+# TODO: 6.0 - remove TRUST constants
+TRUST_SYSTEM_CA_SIGNED_CERTIFICATES = "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES"  # Default
+TRUST_ALL_CERTIFICATES = "TRUST_ALL_CERTIFICATES"
+
 SYSTEM_DATABASE = "system"
 DEFAULT_DATABASE = None  # Must be a non string hashable value