Update security documentation and examples to use PROTOCOL_TLS

Author: aboudreault

CHANGELOG.rst

@@ -15,6 +15,7 @@ Bug Fixes
 Others
 ------
 * Drop Python 3.4 support (PYTHON-1220)
+* Update security documentation and examples to use PROTOCOL_TLS (PYTHON-1264)
 
 3.24.0
 ======

cassandra/cluster.py

@@ -785,7 +785,7 @@ def default_retry_policy(self, policy):
 
     By default, a ``ca_certs`` value should be supplied (the value should be
     a string pointing to the location of the CA certs file), and you probably
-    want to specify ``ssl_version`` as ``ssl.PROTOCOL_TLSv1`` to match
+    want to specify ``ssl_version`` as ``ssl.PROTOCOL_TLS`` to match
     Cassandra's default protocol.
 
     .. versionchanged:: 3.3.0

docs/security.rst

@@ -119,9 +119,9 @@ The driver configuration:
 .. code-block:: python
 
     from cassandra.cluster import Cluster, Session
-    from ssl import SSLContext, PROTOCOL_TLSv1
+    from ssl import SSLContext, PROTOCOL_TLS
 
-    ssl_context = SSLContext(PROTOCOL_TLSv1)
+    ssl_context = SSLContext(PROTOCOL_TLS)
 
     cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context)
     session = cluster.connect()
@@ -147,9 +147,9 @@ to `CERT_REQUIRED`. Otherwise, the loaded verify certificate will have no effect
 .. code-block:: python
 
     from cassandra.cluster import Cluster, Session
-    from ssl import SSLContext, PROTOCOL_TLSv1, CERT_REQUIRED
+    from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED
 
-    ssl_context = SSLContext(PROTOCOL_TLSv1)
+    ssl_context = SSLContext(PROTOCOL_TLS)
     ssl_context.load_verify_locations('/path/to/rootca.crt')
     ssl_context.verify_mode = CERT_REQUIRED
 
@@ -161,9 +161,9 @@ Additionally, you can also force the driver to verify the `hostname` of the serv
 .. code-block:: python
 
     from cassandra.cluster import Cluster, Session
-    from ssl import SSLContext, PROTOCOL_TLSv1, CERT_REQUIRED
+    from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED
 
-    ssl_context = SSLContext(PROTOCOL_TLSv1)
+    ssl_context = SSLContext(PROTOCOL_TLS)
     ssl_context.load_verify_locations('/path/to/rootca.crt')
     ssl_context.verify_mode = CERT_REQUIRED
     ssl_context.check_hostname = True
@@ -228,9 +228,9 @@ Finally, you can use that configuration with the following driver code:
 .. code-block:: python
 
     from cassandra.cluster import Cluster, Session
-    from ssl import SSLContext, PROTOCOL_TLSv1
+    from ssl import SSLContext, PROTOCOL_TLS
 
-    ssl_context = SSLContext(PROTOCOL_TLSv1)
+    ssl_context = SSLContext(PROTOCOL_TLS)
     ssl_context.load_cert_chain(
         certfile='/path/to/client.crt_signed',
         keyfile='/path/to/client.key')
@@ -251,9 +251,9 @@ The following driver code specifies that the connection should use two-way verif
 .. code-block:: python
 
     from cassandra.cluster import Cluster, Session
-    from ssl import SSLContext, PROTOCOL_TLSv1, CERT_REQUIRED
+    from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED
 
-    ssl_context = SSLContext(PROTOCOL_TLSv1)
+    ssl_context = SSLContext(PROTOCOL_TLS)
     ssl_context.load_verify_locations('/path/to/rootca.crt')
     ssl_context.verify_mode = CERT_REQUIRED
     ssl_context.load_cert_chain(
@@ -275,7 +275,7 @@ for more details about ``SSLContext`` configuration.
     from cassandra.cluster import Cluster
     from cassandra.io.twistedreactor import TwistedConnection
 
-    ssl_context = SSL.Context(SSL.TLSv1_METHOD)
+    ssl_context = SSL.Context(SSL.TLSv1_2_METHOD)
     ssl_context.set_verify(SSL.VERIFY_PEER, callback=lambda _1, _2, _3, _4, ok: ok)
     ssl_context.use_certificate_file('/path/to/client.crt_signed')
     ssl_context.use_privatekey_file('/path/to/client.key')
@@ -303,19 +303,19 @@ deprecated in the next major release.
 
 By default, a ``ca_certs`` value should be supplied (the value should be
 a string pointing to the location of the CA certs file), and you probably
-want to specify ``ssl_version`` as ``ssl.PROTOCOL_TLSv1`` to match
+want to specify ``ssl_version`` as ``ssl.PROTOCOL_TLS`` to match
 Cassandra's default protocol.
 
 For example:
 
 .. code-block:: python
 
     from cassandra.cluster import Cluster
-    from ssl import PROTOCOL_TLSv1, CERT_REQUIRED
+    from ssl import PROTOCOL_TLS, CERT_REQUIRED
 
     ssl_opts = {
         'ca_certs': '/path/to/my/ca.certs',
-        'ssl_version': PROTOCOL_TLSv1,
+        'ssl_version': PROTOCOL_TLS,
         'cert_reqs': CERT_REQUIRED  # Certificates are required and validated
     }
     cluster = Cluster(ssl_options=ssl_opts)

tests/integration/cloud/test_cloud.py

@@ -24,7 +24,7 @@
     import unittest  # noqa
 
 import six
-from ssl import SSLContext, PROTOCOL_TLSv1
+from ssl import SSLContext, PROTOCOL_TLS
 
 from cassandra import DriverException, ConsistencyLevel, InvalidRequest
 from cassandra.cluster import NoHostAvailable, ExecutionProfile, Cluster, _execution_profile_to_string
@@ -92,7 +92,7 @@ def test_support_overriding_auth_provider(self):
 
     def test_error_overriding_ssl_context(self):
         with self.assertRaises(ValueError) as cm:
-            self.connect(self.creds, ssl_context=SSLContext(PROTOCOL_TLSv1))
+            self.connect(self.creds, ssl_context=SSLContext(PROTOCOL_TLS))
 
         self.assertIn('cannot be specified with a cloud configuration', str(cm.exception))
 

tests/integration/long/test_ssl.py

@@ -54,11 +54,11 @@
 USES_PYOPENSSL = "twisted" in EVENT_LOOP_MANAGER or "eventlet" in EVENT_LOOP_MANAGER
 if "twisted" in EVENT_LOOP_MANAGER:
     import OpenSSL
-    ssl_version = OpenSSL.SSL.TLSv1_METHOD
+    ssl_version = OpenSSL.SSL.TLSv1_2_METHOD
     verify_certs = {'cert_reqs': SSL.VERIFY_PEER,
                     'check_hostname': True}
 else:
-    ssl_version = ssl.PROTOCOL_TLSv1
+    ssl_version = ssl.PROTOCOL_TLS
     verify_certs = {'cert_reqs': ssl.CERT_REQUIRED,
                     'check_hostname': True}
 
@@ -404,7 +404,7 @@ def test_can_connect_with_sslcontext_certificate(self):
         @test_category connection:ssl
         """
         if USES_PYOPENSSL:
-            ssl_context = SSL.Context(SSL.TLSv1_METHOD)
+            ssl_context = SSL.Context(SSL.TLSv1_2_METHOD)
             ssl_context.load_verify_locations(CLIENT_CA_CERTS)
         else:
             ssl_context = ssl.SSLContext(ssl_version)
@@ -428,7 +428,7 @@ def test_can_connect_with_ssl_client_auth_password_private_key(self):
         ssl_options = {}
 
         if USES_PYOPENSSL:
-            ssl_context = SSL.Context(SSL.TLSv1_METHOD)
+            ssl_context = SSL.Context(SSL.TLSv1_2_METHOD)
             ssl_context.use_certificate_file(abs_driver_certfile)
             with open(abs_driver_keyfile) as keyfile:
                 key = crypto.load_privatekey(crypto.FILETYPE_PEM, keyfile.read(), b'cassandra')
@@ -449,7 +449,7 @@ def test_can_connect_with_ssl_context_ca_host_match(self):
         """
         ssl_options = {}
         if USES_PYOPENSSL:
-            ssl_context = SSL.Context(SSL.TLSv1_METHOD)
+            ssl_context = SSL.Context(SSL.TLSv1_2_METHOD)
             ssl_context.use_certificate_file(DRIVER_CERTFILE)
             with open(DRIVER_KEYFILE_ENCRYPTED) as keyfile:
                 key = crypto.load_privatekey(crypto.FILETYPE_PEM, keyfile.read(), b'cassandra')
@@ -472,7 +472,7 @@ def test_can_connect_with_ssl_context_ca_host_match(self):
     def test_cannot_connect_ssl_context_with_invalid_hostname(self):
         ssl_options = {}
         if USES_PYOPENSSL:
-            ssl_context = SSL.Context(SSL.TLSv1_METHOD)
+            ssl_context = SSL.Context(SSL.TLSv1_2_METHOD)
             ssl_context.use_certificate_file(DRIVER_CERTFILE)
             with open(DRIVER_KEYFILE_ENCRYPTED) as keyfile:
                 key = crypto.load_privatekey(crypto.FILETYPE_PEM, keyfile.read(), b"cassandra")