Added support for using the TLS SNI extension to reduce the number of

TLS renegotiations that are needed to connect to the database.

Author: anthony-tuininga

doc/src/api_manual/connect_params.rst

@@ -62,11 +62,15 @@ ConnectParams Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=None)
+        driver_name=oracledb.defaults.driver_name, use_sni=None, handle=None)
 
     Sets the values for one or more of the parameters of a ConnectParams
     object.
 
+    .. versionchanged:: 3.0.0
+
+        The ``use_sni`` parameter was added.
+
     .. versionchanged:: 2.5.0
 
         The ``program``, ``machine``, ``terminal``, ``osuser``, and
@@ -509,6 +513,16 @@ ConnectParams Attributes
         The default value of this attribute was changed from *60.0* seconds to
         *20.0* seconds.
 
+.. attribute:: ConnectParams.use_sni
+
+    This read-only attribute is a boolean which indicates whether to use the
+    TLS Server Name Indicator (SNI) extension to bypass the second TLS
+    negotiation that would otherwise be required.
+
+    This attribute is supported in both python-oracledb Thin and Thick modes.
+
+    .. versionadded:: 3.0.0
+
 .. attribute:: ConnectParams.terminal
 
     This read-only attribute is a string that specifies the terminal

doc/src/api_manual/module.rst

@@ -52,7 +52,7 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -362,6 +362,12 @@ Oracledb Methods
     are using python-oracledb Thick mode, Oracle Client 23ai is additionally
     required.
 
+    The ``use_sni`` parameter is expected to be a boolean which indicates
+    whether to use the TLS Server Name Indicator (SNI) extension to bypass the
+    second TLS neogiation that would otherwise be required. This parameter is
+    used in both python-oracledb Thin and Thick modes. The default value is
+    False.
+
     The ``program`` parameter is expected to be a string which specifies the
     name of the executable program or application connected to Oracle
     Database.  This value is only used in the python-oracledb Thin mode. The
@@ -397,8 +403,8 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias`` parameter was added.  The ``pool`` parameter was
-        deprecated. Use :meth:`ConnectionPool.acquire()` instead.
+        The ``pool_alias`` and ``use_sni`` parameters were added.  The ``pool``
+        parameter was deprecated. Use :meth:`ConnectionPool.acquire()` instead.
 
     .. versionchanged:: 2.5.0
 
@@ -443,7 +449,7 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
 
     Constructor for creating a connection to the database. Returns an
     :ref:`AsyncConnection Object <asyncconnobj>`. All parameters are optional
@@ -689,6 +695,12 @@ Oracledb Methods
     are using python-oracledb Thick mode, Oracle Client 23ai is additionally
     required.
 
+    The ``use_sni`` parameter is expected to be a boolean which indicates
+    whether to use the TLS Server Name Indicator (SNI) extension to bypass the
+    second TLS neogiation that would otherwise be required. This parameter is
+    used in both python-oracledb Thin and Thick modes. The default value is
+    False.
+
     The ``program`` parameter is expected to be a string which specifies the
     name of the executable program or application connected to Oracle
     Database.  This value is only used in the python-oracledb Thin mode. The
@@ -718,8 +730,9 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias`` parameter was added. The ``pool`` parameter was
-        deprecated. Use :meth:`AsyncConnectionPool.acquire()` instead.
+        The ``pool_alias`` and ``use_sni`` parameters were added. The ``pool``
+        parameter was deprecated. Use :meth:`AsyncConnectionPool.acquire()`
+        instead.
 
     .. versionchanged:: 2.5.0
 
@@ -762,7 +775,7 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
 
     Contains all the parameters that can be used to establish a connection to
     the database.
@@ -1026,6 +1039,12 @@ Oracledb Methods
     are using python-oracledb Thick mode, Oracle Client 23ai is additionally
     required.
 
+    The ``use_sni`` parameter is expected to be a boolean which indicates
+    whether to use the TLS Server Name Indicator (SNI) extension to bypass the
+    second TLS neogiation that would otherwise be required. This parameter is
+    used in both python-oracledb Thin and Thick modes. The default value is
+    False.
+
     The ``program`` parameter is expected to be a string which specifies the
     name of the executable program or application connected to Oracle
     Database.  This value is only used in the python-oracledb Thin mode. The
@@ -1056,6 +1075,10 @@ Oracledb Methods
     python-oracledb Thick mode.  It should be used with extreme caution. The
     default value is *0*.
 
+    .. versionchanged:: 3.0.0
+
+        The ``use_sni`` parameter was added.
+
     .. versionchanged:: 2.5.0
 
         The ``program``, ``machine``, ``terminal``, ``osuser``, and
@@ -1115,7 +1138,7 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -1497,6 +1520,12 @@ Oracledb Methods
     are using python-oracledb Thick mode, Oracle Client 23ai is additionally
     required.
 
+    The ``use_sni`` parameter is expected to be a boolean which indicates
+    whether to use the TLS Server Name Indicator (SNI) extension to bypass the
+    second TLS neogiation that would otherwise be required. This parameter is
+    used in both python-oracledb Thin and Thick modes. The default value is
+    False.
+
     The ``program`` parameter is expected to be a string which specifies the
     name of the executable program or application connected to Oracle
     Database.  This value is only used in the python-oracledb Thin mode. The
@@ -1540,6 +1569,10 @@ Oracledb Methods
         ``driver_name`` parameters were added. Support for ``edition`` and
         ``appcontext`` was added to python-oracledb Thin mode.
 
+    .. versionchanged:: 2.5.0
+
+        The ``use_sni`` parameter was added.
+
     .. versionchanged:: 2.3.0
 
         The default value of the ``retry_delay`` parameter was changed from *0*
@@ -1582,7 +1615,7 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`AsyncConnectionPool object <asyncconnpoolobj>` for the pool.
@@ -1884,6 +1917,12 @@ Oracledb Methods
     are using python-oracledb Thick mode, Oracle Client 23ai is additionally
     required.
 
+    The ``use_sni`` parameter is expected to be a boolean which indicates
+    whether to use the TLS Server Name Indicator (SNI) extension to bypass the
+    second TLS neogiation that would otherwise be required. This parameter is
+    used in both python-oracledb Thin and Thick modes. The default value is
+    False.
+
     The ``program`` parameter is expected to be a string which specifies the
     name of the executable program or application connected to Oracle
     Database.  This value is only used in the python-oracledb Thin mode. The
@@ -1913,7 +1952,7 @@ Oracledb Methods
 
     .. versionchanged:: 3.0.0
 
-        The ``pool_alias`` parameter was added.
+        The ``pool_alias`` and ``use_sni`` parameters were added.
 
     .. versionchanged:: 2.5.0
 
@@ -2129,7 +2168,7 @@ Oracledb Methods
         pool_boundary=None, use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=0)
+        driver_name=oracledb.defaults.driver_name, use_sni=False, handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -2454,6 +2493,12 @@ Oracledb Methods
     are using python-oracledb Thick mode, Oracle Client 23ai is additionally
     required.
 
+    The ``use_sni`` parameter is expected to be a boolean which indicates
+    whether to use the TLS Server Name Indicator (SNI) extension to bypass the
+    second TLS neogiation that would otherwise be required. This parameter is
+    used in both python-oracledb Thin and Thick modes. The default value is
+    False.
+
     The ``program`` parameter is expected to be a string which specifies the
     name of the executable program or application connected to Oracle
     Database.  This value is only used in the python-oracledb Thin mode. The
@@ -2484,6 +2529,10 @@ Oracledb Methods
     python-oracledb Thick mode. It should be used with extreme caution. The
     default value is *0*.
 
+    .. versionchanged:: 3.0.0
+
+        The ``use_sni`` parameter was added.
+
     .. versionchanged:: 2.5.0
 
         The ``program``, ``machine``, ``terminal``, ``osuser``, and

doc/src/api_manual/pool_params.rst

@@ -51,10 +51,14 @@ PoolParams Methods
         use_tcp_fast_open=False, ssl_version=None, \
         program=oracledb.defaults.program, machine=oracledb.defaults.machine, \
         terminal=oracledb.defaults.terminal, osuser=oracledb.defaults.osuser, \
-        driver_name=oracledb.defaults.driver_name, handle=None)
+        driver_name=oracledb.defaults.driver_name, use_sni=None, handle=None)
 
         Sets one or more of the parameters.
 
+        .. versionchanged:: 3.0.0
+
+            The ``use_sni`` parameter was added.
+
         .. versionchanged:: 2.5.0
 
             The ``program``, ``machine``, ``terminal``, ``osuser``, and

doc/src/release_notes.rst

@@ -22,6 +22,9 @@ Thin Mode Changes
 #)  Perform TLS server matching in python-oracledb instead of the Python SSL
     library to allow alternate names to be checked
     (`issue 415 <https://github.com/oracle/python-oracledb/issues/415>`__).
+#)  Added parameter :data:`ConnectParams.use_sni` to specify that the TLS SNI
+    extension should be used to reduce the number of TLS neegotiations that are
+    needed to connect to the database.
 #)  Host names are now resolved to IP addresses in python-oracledb instead of
     the Python libraries. Address list load balancing and failover settings
     will be used when establishing connections.

src/oracledb/base_impl.pxd

@@ -496,6 +496,7 @@ cdef class Description(ConnectParamsNode):
         public uint32_t purity
         public bint ssl_server_dn_match
         public bint use_tcp_fast_open
+        public bint use_sni
         public str ssl_server_cert_dn
         public object ssl_version
         public str wallet_location

src/oracledb/connect_params.py

@@ -103,6 +103,7 @@ def __init__(
         terminal: str = oracledb.defaults.terminal,
         osuser: str = oracledb.defaults.osuser,
         driver_name: str = oracledb.defaults.driver_name,
+        use_sni: bool = False,
         handle: int = 0,
     ):
         """
@@ -294,6 +295,10 @@ def __init__(
         - driver_name: the driver name used by the client to connect to the
           Oracle Database (default: oracledb.defaults.driver_name)
 
+        - use_sni: boolean indicating whether to use the TLS SNI extension to
+          bypass the second TLS neogiation that would otherwise be required
+          (default: False)
+
         - 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)
@@ -346,7 +351,8 @@ def __repr__(self):
             + f"machine={self.machine!r}, "
             + f"terminal={self.terminal!r}, "
             + f"osuser={self.osuser!r}, "
-            + f"driver_name={self.driver_name!r}"
+            + f"driver_name={self.driver_name!r}, "
+            + f"use_sni={self.use_sni!r}"
             + ")"
         )
 
@@ -729,6 +735,15 @@ def user(self) -> str:
         """
         return self._impl.user
 
+    @property
+    @_flatten_value
+    def use_sni(self) -> Union[list, bool]:
+        """
+        Boolean indicating whether to use the TLS SNI extension to bypass the
+        second TLS neogiation that would otherwise be required.
+        """
+        return [d.use_sni for d in self._impl.description_list.children]
+
     @property
     @_flatten_value
     def use_tcp_fast_open(self) -> Union[list, bool]:
@@ -848,6 +863,7 @@ def set(
         terminal: str = None,
         osuser: str = None,
         driver_name: str = None,
+        use_sni: bool = None,
         handle: int = None,
     ):
         """
@@ -1027,6 +1043,9 @@ def set(
         - driver_name: the driver name used by the client to connect to the
           Oracle Database
 
+        - use_sni: boolean indicating whether to use the TLS SNI extension to
+          bypass the second TLS neogiation that would otherwise be required
+
         - 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

src/oracledb/connection.py

@@ -1271,6 +1271,7 @@ def connect(
     terminal: str = oracledb.defaults.terminal,
     osuser: str = oracledb.defaults.osuser,
     driver_name: str = oracledb.defaults.driver_name,
+    use_sni: bool = False,
     handle: int = 0,
 ) -> Connection:
     """
@@ -1481,6 +1482,10 @@ def connect(
     - driver_name: the driver name used by the client to connect to the Oracle
       Database (default: oracledb.defaults.driver_name)
 
+    - use_sni: boolean indicating whether to use the TLS SNI extension to
+      bypass the second TLS neogiation that would otherwise be required
+      (default: False)
+
     - 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)
@@ -2036,6 +2041,7 @@ def connect_async(
     terminal: str = oracledb.defaults.terminal,
     osuser: str = oracledb.defaults.osuser,
     driver_name: str = oracledb.defaults.driver_name,
+    use_sni: bool = False,
     handle: int = 0,
 ) -> AsyncConnection:
     """
@@ -2246,6 +2252,10 @@ def connect_async(
     - driver_name: the driver name used by the client to connect to the Oracle
       Database (default: oracledb.defaults.driver_name)
 
+    - use_sni: boolean indicating whether to use the TLS SNI extension to
+      bypass the second TLS neogiation that would otherwise be required
+      (default: False)
+
     - 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)

src/oracledb/impl/base/connect_params.pyx

@@ -792,6 +792,8 @@ cdef class Description(ConnectParamsNode):
         if self.tcp_connect_timeout != DEFAULT_TCP_CONNECT_TIMEOUT:
             temp = self._build_duration_str(self.tcp_connect_timeout)
             parts.append(f"(TRANSPORT_CONNECT_TIMEOUT={temp})")
+        if self.use_sni:
+            parts.append("(USE_SNI=ON)")
         if self.sdu != DEFAULT_SDU:
             parts.append(f"(SDU={self.sdu})")
 
@@ -875,6 +877,7 @@ cdef class Description(ConnectParamsNode):
         description.use_tcp_fast_open = self.use_tcp_fast_open
         description.ssl_server_cert_dn = self.ssl_server_cert_dn
         description.ssl_version = self.ssl_version
+        description.use_sni = self.use_sni
         description.wallet_location = self.wallet_location
         return description
 
@@ -914,6 +917,7 @@ cdef class Description(ConnectParamsNode):
         _set_bool_param(args, "source_route", &self.source_route)
         _set_uint_param(args, "retry_count", &self.retry_count)
         _set_uint_param(args, "retry_delay", &self.retry_delay)
+        _set_bool_param(args, "use_sni", &self.use_sni)
         _set_uint_param(args, "sdu", &self.sdu)
         self.sdu = min(max(self.sdu, 512), 2097152)         # sanitize SDU
         _set_duration_param(args, "tcp_connect_timeout",