4.0 uri scheme (#367)

* implemented uri scheme

bolt
bolt+ssc
bolt+s

neo4j
neo4j+ssc
neo4j+s

neo4j+routing (deprecated)

* removed bolt+neo4j scheme

* added stub tests for routing driver

* fixed ssl_context for python 3.5

* config setting secure removed

the config secure is named encrypted

added tests to check that URI scheme with encryption enabled raises
error if config setting encryption and verify_cert is set on driver
creation.

* updated docs for config setting encrypted

* fixed stub tests

* changed verify_cert to trust

Author: martin-neotech

docs/source/usage_patterns.rst

@@ -41,19 +41,17 @@ Driver Initialization Work Pattern
 
 .. code-block:: python
 
-    from neo4j import GraphDatabase
+    from neo4j import GraphDatabase, TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
     from neo4j.exceptions import ServiceUnavailable
 
     uri = "bolt://localhost:7687"
 
     driver_config = {
         "encrypted": False,
-        "trust": None,
+        "trust": TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
         "user_agent": "example",
         "max_connection_lifetime": 1000,
         "max_connection_pool_size": 100,
-        "connection_acquisition_timeout": 10,
-        "connection_timeout": 1,
         "keep_alive": False,
         "max_retry_time": 10,
         "resolver": None,

neo4j/__init__.py

@@ -55,6 +55,8 @@
 from neo4j.conf import (
     Config,
     PoolConfig,
+    TRUST_ALL_CERTIFICATES,
+    TRUST_SYSTEM_CA_SIGNED_CERTIFICATES,
 )
 from neo4j.meta import (
     experimental,
@@ -88,29 +90,98 @@ def driver(cls, uri, *, auth=None, acquire_timeout=None, **config):
         concurrency.
 
         :param uri:
+
+            bolt://host[:port]
+            Settings: Direct driver with no encryption.
+
+            bolt+ssc://host[:port]
+            Settings: Direct driver with encryption (accepts self signed certificates).
+
+            bolt+s://host[:port]
+            Settings: Direct driver with encryption (accepts only certificates signed by an certificate authority), full certificate checks.
+
+            neo4j://host[:port][?routing_context]
+            Settings: Routing driver with no encryption.
+
+            neo4j+ssc://host[:port][?routing_context]
+            Settings: Routing driver with encryption (accepts self signed certificates).
+
+            neo4j+s://host[:port][?routing_context]
+            Settings: Routing driver with encryption (accepts only certificates signed by an certificate authority), full certificate checks.
+
         :param auth:
-        :param acquire_timeout:
+        :param acquire_timeout: seconds
         :param config: connection configuration settings
         """
-        parsed = urlparse(uri)
-        if parsed.scheme == "bolt":
+
+        from neo4j.api import (
+            parse_neo4j_uri,
+            DRIVER_BOLT,
+            DRIVER_NEO4j,
+            SECURITY_TYPE_NOT_SECURE,
+            SECURITY_TYPE_SELF_SIGNED_CERTIFICATE,
+            SECURITY_TYPE_SECURE,
+            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,
+        )
+        from neo4j.conf import (
+            TRUST_ALL_CERTIFICATES,
+            TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
+        )
+
+        driver_type, security_type, parsed = parse_neo4j_uri(uri)
+
+        if "trust" in config.keys():
+            if config.get("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()):
+            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,
+                ]
+            ))
+
+        if security_type == SECURITY_TYPE_SECURE:
+            config["encrypted"] = True
+        elif security_type == SECURITY_TYPE_SELF_SIGNED_CERTIFICATE:
+            config["encrypted"] = True
+            config["trust"] = TRUST_ALL_CERTIFICATES
+
+        if driver_type == DRIVER_BOLT:
             return cls.bolt_driver(parsed.netloc, auth=auth, acquire_timeout=acquire_timeout, **config)
-        elif parsed.scheme == "neo4j" or parsed.scheme == "bolt+routing":
+        elif driver_type == DRIVER_NEO4j:
             rc = cls._parse_routing_context(parsed.query)
             return cls.neo4j_driver(parsed.netloc, auth=auth, routing_context=rc, acquire_timeout=acquire_timeout, **config)
-        else:
-            raise ValueError("Unknown URI scheme {!r}".format(parsed.scheme))
 
     @classmethod
     def bolt_driver(cls, target, *, auth=None, acquire_timeout=None, **config):
         """ Create a driver for direct Bolt server access that uses
         socket I/O and thread-based concurrency.
         """
-        from neo4j._exceptions import BoltHandshakeError
+        from neo4j._exceptions import BoltHandshakeError, BoltSecurityError
 
         try:
             return BoltDriver.open(target, auth=auth, acquire_timeout=acquire_timeout, **config)
-        except BoltHandshakeError as error:
+        except (BoltHandshakeError, BoltSecurityError) as error:
             from neo4j.exceptions import ServiceUnavailable
             raise ServiceUnavailable(str(error)) from error
 
@@ -120,11 +191,11 @@ def neo4j_driver(cls, *targets, auth=None, routing_context=None, acquire_timeout
         """ Create a driver for routing-capable Neo4j service access
         that uses socket I/O and thread-based concurrency.
         """
-        from neo4j._exceptions import BoltHandshakeError
+        from neo4j._exceptions import BoltHandshakeError, BoltSecurityError
 
         try:
             return Neo4jDriver.open(*targets, auth=auth, routing_context=routing_context, acquire_timeout=acquire_timeout, **config)
-        except BoltHandshakeError as error:
+        except (BoltHandshakeError, BoltSecurityError) as error:
             from neo4j.exceptions import ServiceUnavailable
             raise ServiceUnavailable(str(error)) from error
 
@@ -228,8 +299,8 @@ def __exit__(self, exc_type, exc_value, traceback):
         self.close()
 
     @property
-    def secure(self):
-        return bool(self._pool.config.secure)
+    def encrypted(self):
+        return bool(self._pool.config.encrypted)
 
     def session(self, **config):
         """ Create a simple session.
@@ -278,8 +349,7 @@ def open(cls, target, *, auth=None, **config):
         from neo4j.io import BoltPool
         from neo4j.work import WorkspaceConfig
         address = cls.parse_target(target)
-        pool_config, default_workspace_config = Config.consume_chain(config, PoolConfig,
-                                                                     WorkspaceConfig)
+        pool_config, default_workspace_config = Config.consume_chain(config, PoolConfig, WorkspaceConfig)
         pool = BoltPool.open(address, auth=auth, **pool_config)
         return cls(pool, default_workspace_config)
 
@@ -323,8 +393,7 @@ def open(cls, *targets, auth=None, routing_context=None, **config):
         from neo4j.io import Neo4jPool
         from neo4j.work import WorkspaceConfig
         addresses = cls.parse_targets(*targets)
-        pool_config, default_workspace_config = Config.consume_chain(config, PoolConfig,
-                                                                     WorkspaceConfig)
+        pool_config, default_workspace_config = Config.consume_chain(config, PoolConfig, WorkspaceConfig)
         pool = Neo4jPool.open(*addresses, auth=auth, routing_context=routing_context, **pool_config)
         return cls(pool, default_workspace_config)
 

neo4j/api.py

@@ -18,10 +18,36 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from urllib.parse import (
+    urlparse,
+)
+from.exceptions import (
+    ConfigurationError,
+)
 
 """ Base classes and helpers.
 """
 
+READ_ACCESS = "READ"
+WRITE_ACCESS = "WRITE"
+
+DRIVER_BOLT = "DRIVER_BOLT"
+DRIVER_NEO4j = "DRIVER_NEO4J"
+
+SECURITY_TYPE_NOT_SECURE = "SECURITY_TYPE_NOT_SECURE"
+SECURITY_TYPE_SELF_SIGNED_CERTIFICATE = "SECURITY_TYPE_SELF_SIGNED_CERTIFICATE"
+SECURITY_TYPE_SECURE = "SECURITY_TYPE_SECURE"
+
+URI_SCHEME_BOLT = "bolt"
+URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE = "bolt+ssc"
+URI_SCHEME_BOLT_SECURE = "bolt+s"
+
+URI_SCHEME_NEO4J = "neo4j"
+URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE = "neo4j+ssc"
+URI_SCHEME_NEO4J_SECURE = "neo4j+s"
+
+URI_SCHEME_BOLT_ROUTING = "bolt+routing"
+
 
 class Auth:
     """ Container for auth details.
@@ -161,5 +187,46 @@ def from_bytes(cls, b):
         return Version(b[-1], b[-2])
 
 
-READ_ACCESS = "READ"
-WRITE_ACCESS = "WRITE"
+def parse_neo4j_uri(uri):
+    parsed = urlparse(uri)
+
+    if parsed.username:
+        raise ConfigurationError("Username is not supported in the URI")
+
+    if parsed.password:
+        raise ConfigurationError("Password is not supported in the URI")
+
+    if parsed.scheme == URI_SCHEME_BOLT_ROUTING:
+        raise ConfigurationError("Uri scheme {!r} have been renamed. Use {!r}".format(parsed.scheme, URI_SCHEME_NEO4J))
+    elif parsed.scheme == URI_SCHEME_BOLT:
+        driver_type = DRIVER_BOLT
+        security_type = SECURITY_TYPE_NOT_SECURE
+    elif parsed.scheme == URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE:
+        driver_type = DRIVER_BOLT
+        security_type = SECURITY_TYPE_SELF_SIGNED_CERTIFICATE
+    elif parsed.scheme == URI_SCHEME_BOLT_SECURE:
+        driver_type = DRIVER_BOLT
+        security_type = SECURITY_TYPE_SECURE
+    elif parsed.scheme == URI_SCHEME_NEO4J:
+        driver_type = DRIVER_NEO4j
+        security_type = SECURITY_TYPE_NOT_SECURE
+    elif parsed.scheme == URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE:
+        driver_type = DRIVER_NEO4j
+        security_type = SECURITY_TYPE_SELF_SIGNED_CERTIFICATE
+    elif parsed.scheme == URI_SCHEME_NEO4J_SECURE:
+        driver_type = DRIVER_NEO4j
+        security_type = SECURITY_TYPE_SECURE
+    else:
+        raise ConfigurationError("URI scheme {!r} is not supported. Supported URI schemes are {}. Examples: bolt://host[:port] or neo4j://host[:port][?routing_context]".format(
+            parsed.scheme,
+            [
+                URI_SCHEME_BOLT,
+                URI_SCHEME_BOLT_SELF_SIGNED_CERTIFICATE,
+                URI_SCHEME_BOLT_SECURE,
+                URI_SCHEME_NEO4J,
+                URI_SCHEME_NEO4J_SELF_SIGNED_CERTIFICATE,
+                URI_SCHEME_NEO4J_SECURE
+            ]
+        ))
+
+    return driver_type, security_type, parsed

neo4j/conf.py

@@ -25,6 +25,9 @@
 
 from neo4j.meta import get_user_agent
 
+TRUST_SYSTEM_CA_SIGNED_CERTIFICATES = "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES"  # Default
+TRUST_ALL_CERTIFICATES = "TRUST_ALL_CERTIFICATES"
+
 
 def iter_items(iterable):
     """ Iterate through all items (key-value pairs) within an iterable
@@ -187,26 +190,61 @@ class PoolConfig(Config):
     resolver = None
 
     #:
-    secure = False
-    encrypted = DeprecatedAlias("secure")
+    encrypted = False
 
     #:
     user_agent = get_user_agent()
 
     #:
-    verify_cert = True
+    trust = TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
 
     def get_ssl_context(self):
-        if not self.secure:
+        if not self.encrypted:
             return None
-        # See https://docs.python.org/3.7/library/ssl.html#protocol-versions
-        from ssl import SSLContext, PROTOCOL_TLS_CLIENT, OP_NO_TLSv1, OP_NO_TLSv1_1, CERT_REQUIRED
-        ssl_context = SSLContext(PROTOCOL_TLS_CLIENT)
-        ssl_context.options |= OP_NO_TLSv1
-        ssl_context.options |= OP_NO_TLSv1_1
-        if self.verify_cert:
-            ssl_context.verify_mode = CERT_REQUIRED
-        ssl_context.set_default_verify_paths()
-        return ssl_context
 
+        import ssl
+
+        ssl_context = None
+
+        # SSL stands for Secure Sockets Layer and was originally created by Netscape.
+        # SSLv2 and SSLv3 are the 2 versions of this protocol (SSLv1 was never publicly released).
+        # After SSLv3, SSL was renamed to TLS.
+        # TLS stands for Transport Layer Security and started with TLSv1.0 which is an upgraded version of SSLv3.
+
+        # SSLv2 - (Disabled)
+        # SSLv3 - (Disabled)
+        # TLS 1.0 - Released in 1999, published as RFC 2246. (Disabled)
+        # TLS 1.1 - Released in 2006, published as RFC 4346. (Disabled)
+        # TLS 1.2 - Released in 2008, published as RFC 5246.
+
+        try:
+            # python 3.6+
+            # https://docs.python.org/3.6/library/ssl.html#ssl.PROTOCOL_TLS_CLIENT
+            ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
 
+            # For recommended security options see
+            # https://docs.python.org/3.6/library/ssl.html#protocol-versions
+            ssl_context.options |= ssl.OP_NO_TLSv1      # Python 3.2
+            ssl_context.options |= ssl.OP_NO_TLSv1_1    # Python 3.4
+
+        except AttributeError:
+            # python 3.5
+            # https://docs.python.org/3.5/library/ssl.html#ssl.PROTOCOL_TLS
+            ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS)
+
+            # For recommended security options see
+            # https://docs.python.org/3.5/library/ssl.html#protocol-versions
+            ssl_context.options |= ssl.OP_NO_SSLv2      # Python 3.2
+            ssl_context.options |= ssl.OP_NO_SSLv3      # Python 3.2
+            ssl_context.options |= ssl.OP_NO_TLSv1      # Python 3.2
+            ssl_context.options |= ssl.OP_NO_TLSv1_1    # Python 3.4
+
+            ssl_context.verify_mode = ssl.CERT_REQUIRED     # https://docs.python.org/3.5/library/ssl.html#ssl.SSLContext.verify_mode
+            ssl_context.check_hostname = True               # https://docs.python.org/3.5/library/ssl.html#ssl.SSLContext.check_hostname
+
+        if self.trust == TRUST_ALL_CERTIFICATES:
+            ssl_context.check_hostname = False
+            ssl_context.verify_mode = ssl.CERT_NONE     # https://docs.python.org/3.5/library/ssl.html#ssl.CERT_NONE
+
+        ssl_context.set_default_verify_paths()  # https://docs.python.org/3.5/library/ssl.html#ssl.SSLContext.set_default_verify_paths
+        return ssl_context

neo4j/io/__init__.py

@@ -193,7 +193,7 @@ def open(cls, address, *, auth=None, timeout=None, **config):
         return connection
 
     @property
-    def secure(self):
+    def encrypted(self):
         raise NotImplementedError
 
     @property
@@ -792,17 +792,17 @@ def _secure(s, host, ssl_context):
         try:
             sni_host = host if HAS_SNI and host else None
             s = ssl_context.wrap_socket(s, server_hostname=sni_host)
-        except SSLError as cause:
+        except (SSLError, OSError) as cause:
             s.close()
-            error = BoltSecurityError(message="Failed to establish secure connection to {!r}".format(cause.args[1]), address=(host, port))
+            error = BoltSecurityError(message="Failed to establish encrypted connection.", address=(host, local_port))
             error.__cause__ = cause
             raise error
         else:
             # Check that the server provides a certificate
             der_encoded_server_certificate = s.getpeercert(binary_form=True)
             if der_encoded_server_certificate is None:
                 s.close()
-                raise BoltProtocolError("When using a secure socket, the server should always provide a certificate", address=(host, port))
+                raise BoltProtocolError("When using an encrypted socket, the server should always provide a certificate", address=(host, local_port))
     return s
 
 

neo4j/io/_bolt3.py

@@ -118,7 +118,7 @@ def __init__(self, unresolved_address, sock, *, auth=None, **config):
                 raise AuthError("Password cannot be None")
 
     @property
-    def secure(self):
+    def encrypted(self):
         return isinstance(self.socket, SSLSocket)
 
     @property