Add parameter "ssl_version" to allow specification of which TLS version

to use when connecting securely.

Author: anthony-tuininga

doc/src/api_manual/connect_params.rst

@@ -59,11 +59,16 @@ ConnectParams Methods
         edition=None, tag=None, matchanytag=None, config_dir=None, \
         appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
         connection_id_prefix=None, ssl_context=None, sdu=None, \
-        pool_boundary=None, use_tcp_fast_open=False, handle=None)
+        pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
+        handle=None)
 
     Sets the values for one or more of the parameters of a ConnectParams
     object.
 
+    .. versionchanged:: 2.3.0
+
+        The ``ssl_version`` parameter was added.
+
     .. versionchanged:: 2.1.0
 
         The ``pool_boundary`` and ``use_tcp_fast_open`` parameters were added.
@@ -371,6 +376,17 @@ ConnectParams Attributes
 
     This attribute is supported in both python-oracledb Thin and Thick modes.
 
+.. attribute:: ConnectParams.ssl_version
+
+    This read-only attribute is one of the constants "ssl.TLSVersion.TLSv1_2"
+    or "ssl.TLSVersion.TLSv1_3" which identifies the TLS protocol version
+    used.  These constants are defined in the Python `ssl <https://docs.python.
+    org/3/library/ssl.html>`__ module.
+
+    This attribute is supported in both python-oracledb Thin and Thick modes.
+
+    .. versionadded:: 2.3.0
+
 .. attribute:: ConnectParams.stmtcachesize
 
     This read-only attribute is an integer that identifies the initial size of

doc/src/api_manual/module.rst

@@ -49,7 +49,8 @@ Oracledb Methods
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
         connection_id_prefix=None, ssl_context=None, sdu=8192, \
-        pool_boundary=None, use_tcp_fast_open=False, handle=0)
+        pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
+        handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -339,6 +340,15 @@ Oracledb Methods
     available with certain versions of ADB-S.  This value is used in both
     python-oracledb Thin and Thick modes.  The default value is False.
 
+    The ``ssl_version`` parameter is expected to be one of the constants
+    "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
+    protocol version to use.  These constants are defined in the Python
+    `ssl <https://docs.python.org/3/library/ssl.html>`__ module.  This
+    parameter can be specified when establishing connections with the protocol
+    "tcps".  This parameter is used in both python-oracledb Thin and Thick
+    modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
+    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
@@ -351,7 +361,8 @@ Oracledb Methods
 
         The default value of the ``retry_delay`` parameter was changed from 0
         seconds to 1 second. The default value of the ``tcp_connect_timeout``
-        parameter was changed from 60.0 seconds to 20.0 seconds.
+        parameter was changed from 60.0 seconds to 20.0 seconds. The
+        ``ssl_version`` parameter was added.
 
     .. versionchanged:: 2.1.0
 
@@ -379,7 +390,8 @@ Oracledb Methods
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
         connection_id_prefix=None, ssl_context=None, sdu=8192, \
-        pool_boundary=None, use_tcp_fast_open=False, handle=0)
+        pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
+        handle=0)
 
     Constructor for creating a connection to the database. Returns an
     :ref:`AsyncConnection Object <asyncconnobj>`. All parameters are optional
@@ -601,13 +613,23 @@ Oracledb Methods
     available with certain versions of ADB-S.  This value is used in both
     python-oracledb Thin and Thick modes.  The default value is False.
 
+    The ``ssl_version`` parameter is expected to be one of the constants
+    "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
+    protocol version to use.  These constants are defined in the Python
+    `ssl <https://docs.python.org/3/library/ssl.html>`__ module.  This
+    parameter can be specified when establishing connections with the protocol
+    "tcps".  This parameter is used in both python-oracledb Thin and Thick
+    modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
+    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+
     The ``handle`` parameter is ignored in the python-oracledb Thin mode.
 
     .. versionchanged:: 2.3.0
 
         The default value of the ``retry_delay`` parameter was changed from 0
         seconds to 1 second. The default value of the ``tcp_connect_timeout``
-        parameter was changed from 60.0 seconds to 20.0 seconds.
+        parameter was changed from 60.0 seconds to 20.0 seconds. The
+        ``ssl_version`` parameter was added.
 
     .. versionchanged:: 2.1.0
 
@@ -634,7 +656,8 @@ Oracledb Methods
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
         connection_id_prefix=None, ssl_context=None, sdu=8192, \
-        pool_boundary=None, use_tcp_fast_open=False, handle=0)
+        pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
+        handle=0)
 
     Contains all the parameters that can be used to establish a connection to
     the database.
@@ -888,6 +911,15 @@ Oracledb Methods
     available with certain versions of ADB-S.  This value is used in both
     python-oracledb Thin and Thick modes.  The default value is False.
 
+    The ``ssl_version`` parameter is expected to be one of the constants
+    "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
+    protocol version to use.  These constants are defined in the Python
+    `ssl <https://docs.python.org/3/library/ssl.html>`__ module.  This
+    parameter can be specified when establishing connections with the protocol
+    "tcps".  This parameter is used in both python-oracledb Thin and Thick
+    modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
+    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode.  It should be used with extreme caution. The
@@ -897,7 +929,8 @@ Oracledb Methods
 
         The default value of the ``retry_delay`` parameter was changed from 0
         seconds to 1 second. The default value of the ``tcp_connect_timeout``
-        parameter was changed from 60.0 seconds to 20.0 seconds.
+        parameter was changed from 60.0 seconds to 20.0 seconds. The
+        ``ssl_version`` parameter was added.
 
     .. versionchanged:: 2.1.0
 
@@ -930,7 +963,8 @@ Oracledb Methods
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
         connection_id_prefix=None, ssl_context=None, sdu=8192, \
-        pool_boundary=None, use_tcp_fast_open=False, handle=0)
+        pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
+        handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -1277,6 +1311,15 @@ Oracledb Methods
     with certain versions of ADB-S.  This value is used in both python-oracledb
     Thin and Thick modes.  The default value is False.
 
+    The ``ssl_version`` parameter is expected to be one of the constants
+    "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
+    protocol version to use.  These constants are defined in the Python
+    `ssl <https://docs.python.org/3/library/ssl.html>`__ module.  This
+    parameter can be specified when establishing connections with the protocol
+    "tcps".  This parameter is used in both python-oracledb Thin and Thick
+    modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
+    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
@@ -1297,7 +1340,7 @@ Oracledb Methods
         The default value of the ``retry_delay`` parameter was changed from 0
         seconds to 1 second. The default value of the ``tcp_connect_timeout``
         parameter was changed from 60.0 seconds to 20.0 seconds. The
-        ``ping_timeout`` parameter was added.
+        ``ping_timeout`` and ``ssl_version`` parameters were added.
 
     .. versionchanged:: 2.1.0
 
@@ -1330,7 +1373,8 @@ Oracledb Methods
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
         connection_id_prefix=None, ssl_context=None, sdu=8192, \
-        pool_boundary=None, use_tcp_fast_open=False, handle=0)
+        pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
+        handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`AsyncConnectionPool object <asyncconnpoolobj>` for the pool.
@@ -1607,14 +1651,23 @@ Oracledb Methods
     with certain versions of ADB-S.  This value is used in both python-oracledb
     Thin and Thick modes.  The default value is False.
 
+    The ``ssl_version`` parameter is expected to be one of the constants
+    "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
+    protocol version to use.  These constants are defined in the Python
+    `ssl <https://docs.python.org/3/library/ssl.html>`__ module.  This
+    parameter can be specified when establishing connections with the protocol
+    "tcps".  This parameter is used in both python-oracledb Thin and Thick
+    modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
+    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+
     The ``handle`` parameter is ignored in the python-oracledb Thin mode.
 
     .. versionchanged:: 2.3.0
 
         The default value of the ``retry_delay`` parameter was changed from 0
         seconds to 1 second. The default value of the ``tcp_connect_timeout``
         parameter was changed from 60.0 seconds to 20.0 seconds. The
-        ``ping_timeout`` parameter was added.
+        ``ping_timeout`` and ``ssl_version`` parameters were added.
 
     .. versionchanged:: 2.1.0
 
@@ -1750,7 +1803,8 @@ Oracledb Methods
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
         connection_id_prefix=None, ssl_context=None, sdu=8192, \
-        pool_boundary=None, use_tcp_fast_open=False, handle=0)
+        pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
+        handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -2064,6 +2118,15 @@ Oracledb Methods
     with certain versions of ADB-S.  This value is used in both python-oracledb
     Thin and Thick modes.  The default value is False.
 
+    The ``ssl_version`` parameter is expected to be one of the constants
+    "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
+    protocol version to use.  These constants are defined in the Python
+    `ssl <https://docs.python.org/3/library/ssl.html>`__ module.  This
+    parameter can be specified when establishing connections with the protocol
+    "tcps".  This parameter is used in both python-oracledb Thin and Thick
+    modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
+    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode. It should be used with extreme caution. The
@@ -2074,7 +2137,7 @@ Oracledb Methods
         The default value of the ``retry_delay`` parameter was changed from 0
         seconds to 1 second. The default value of the ``tcp_connect_timeout``
         parameter was changed from 60.0 seconds to 20.0 seconds. The
-        ``ping_timeout`` parameter was added.
+        ``ping_timeout`` and ``ssl_version`` parameters were added.
 
     .. versionchanged:: 2.1.0
 

doc/src/api_manual/pool_params.rst

@@ -48,13 +48,13 @@ PoolParams Methods
         matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], \
         supershardingkey=[], debug_jdwp=None, connection_id_prefix=None, \
         ssl_context=None, sdu=None, pool_boundary=None, \
-        use_tcp_fast_open=False, handle=None)
+        use_tcp_fast_open=False, ssl_version=None, handle=None)
 
   Sets one or more of the parameters.
 
   .. versionchanged:: 2.3.0
 
-    The ``ping_timeout`` parameter was added.
+    The ``ping_timeout`` and ``ssl_version`` parameters were added.
 
   .. versionchanged:: 2.1.0
 

doc/src/release_notes.rst

@@ -48,6 +48,10 @@ Common Changes
 #)  The default value of the ``tcp_connect_timeout`` parameter was changed
     from 60 seconds to 20 seconds. The default value of the
     ``retry_delay`` parameter was changed from 0 seconds to 1 second.
+#)  Added parameter ``ssl_version`` to :meth:`oracledb.connect()`
+    :meth:`oracledb.connect_async()`, :meth:`oracledb.create_pool()`, and
+    :meth:`oracledb.create_pool_async()` methods in order to specify which TLS
+    version to use when establishing connections with the protocol "tcps".
 #)  Added parameter ``ping_timeout`` to methods :meth:`oracledb.create_pool()`
     and :meth:`oracledb.create_pool_async()` with a default value of 5000
     milliseconds. This limits the amount of time that a call to

src/oracledb/base_impl.pxd

@@ -422,6 +422,7 @@ cdef class Description(ConnectParamsNode):
         public bint ssl_server_dn_match
         public bint use_tcp_fast_open
         public str ssl_server_cert_dn
+        public object ssl_version
         public str wallet_location
         str connection_id
 

src/oracledb/base_impl.pyx

@@ -52,6 +52,7 @@ import os
 import random
 import re
 import secrets
+import ssl
 import sys
 
 cydatetime.import_datetime()

src/oracledb/connect_params.py

@@ -34,6 +34,7 @@
 # -----------------------------------------------------------------------------
 
 import functools
+import ssl
 from typing import Union, Callable, Any
 
 import oracledb
@@ -96,6 +97,7 @@ def __init__(
         sdu: int = 8192,
         pool_boundary: str = None,
         use_tcp_fast_open: bool = False,
+        ssl_version: ssl.TLSVersion = None,
         handle: int = 0,
     ):
         """
@@ -268,6 +270,10 @@ def __init__(
           refer to the ADB-S documentation for more information (default:
           False)
 
+        - ssl_version: one of the values ssl.TLSVersion.TLSv1_2 or
+          ssl.TLSVersion.TLSv1_3 indicating which TLS version to use (default:
+          None)
+
         - handle: an integer representing a pointer to a valid service context
           handle. This value is only used in thick mode. It should be used with
           extreme caution (default: 0)
@@ -314,7 +320,8 @@ def __repr__(self):
             + f"ssl_context={self.ssl_context!r}, "
             + f"sdu={self.sdu!r}, "
             + f"pool_boundary={self.pool_boundary!r}, "
-            + f"use_tcp_fast_open={self.use_tcp_fast_open!r}"
+            + f"use_tcp_fast_open={self.use_tcp_fast_open!r}, "
+            + f"ssl_version={self.ssl_version!r}"
             + ")"
         )
 
@@ -611,6 +618,15 @@ def ssl_server_dn_match(self) -> Union[list, bool]:
             d.ssl_server_dn_match for d in self._impl.description_list.children
         ]
 
+    @property
+    @_flatten_value
+    def ssl_version(self) -> Union[list, ssl.TLSVersion]:
+        """
+        One of the values ssl.TLSVersion.TLSv1_2 or ssl.TLSVersion.TLSv1_3
+        indicating which TLS version to use.
+        """
+        return [d.ssl_version for d in self._impl.description_list.children]
+
     @property
     def stmtcachesize(self) -> int:
         """
@@ -765,6 +781,7 @@ def set(
         sdu: int = None,
         pool_boundary: str = None,
         use_tcp_fast_open: bool = None,
+        ssl_version: ssl.TLSVersion = None,
         handle: int = None,
     ):
         """
@@ -926,6 +943,9 @@ def set(
           property for clients connecting from within OCI Cloud network. Please
           refer to the ADB-S documentation for more information
 
+        - ssl_version: one of the values ssl.TLSVersion.TLSv1_2 or
+          ssl.TLSVersion.TLSv1_3 indicating which TLS version to use
+
         - handle: an integer representing a pointer to a valid service context
           handle. This value is only used in thick mode. It should be used with
           extreme caution