Added new parameter "ssl_context" as suggested (#259).

Author: anthony-tuininga

Diff for: doc/src/api_manual/connect_param.rst

@@ -277,6 +277,16 @@ ConnectParams Attributes
 
     This attribute is supported in the python-oracledb Thin and Thick modes.
 
+.. attribute:: ConnectParams.ssl_context
+
+    This read-only attribute is an SSLContext object which is used for
+    connecting to the database using TLS. This SSL context will be modified to
+    include the private key or any certificates found in a separately supplied
+    wallet. This parameter should only be specified if the default SSLContext
+    object cannot be used.
+
+    This attribute is only supported in the python-oracledb Thin mode.
+
 .. attribute:: ConnectParams.ssl_server_cert_dn
 
     This read-only attribute is a string that returns the distinguished name

Diff for: doc/src/release_notes.rst

@@ -15,6 +15,8 @@ Thin Mode Changes
 
 #)  Fixed bug in detecting the current time zone
     (`issue 257 <https://github.com/oracle/python-oracledb/issues/257>`__).
+#)  Added parameter :data:`ConnectParams.ssl_context`
+    (`issue 259 <https://github.com/oracle/python-oracledb/issues/259>`__).
 #)  Fixed bug in handling database response in certain unusual circumstances.
 #)  Fixed bug in handling exceptions raised during connection establishment.
 #)  Fixed bug in identifying bind variables in SQL statements containing

Diff for: src/oracledb/base_impl.pxd

@@ -178,6 +178,7 @@ cdef class ConnectParamsImpl:
         public list supershardingkey
         public uint32_t stmtcachesize
         public bint disable_oob
+        public object ssl_context
         public DescriptionList description_list
         uint64_t _external_handle
         public str debug_jdwp

Diff for: src/oracledb/connect_params.py

@@ -34,7 +34,7 @@
 # -----------------------------------------------------------------------------
 
 import functools
-from typing import Union, Callable
+from typing import Union, Callable, Any
 
 import oracledb
 
@@ -92,6 +92,7 @@ def __init__(
         supershardingkey: list = None,
         debug_jdwp: str = None,
         connection_id_prefix: str = None,
+        ssl_context: Any = None,
         handle: int = 0,
         threaded: bool = True,
         encoding: str = None,
@@ -243,6 +244,12 @@ def __init__(
         - connection_id_prefix: an application specific prefix that is added to
           the connection identifier used for tracing (default: None)
 
+        - ssl_context: an SSLContext object used for connecting to the database
+          using TLS.  This SSL context will be modified to include the private
+          key or any certificates found in a separately supplied wallet. This
+          parameter should only be specified if the default SSLContext object
+          cannot be used. (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)
@@ -285,7 +292,8 @@ def __repr__(self):
             + f"shardingkey={self.shardingkey!r}, "
             + f"supershardingkey={self.supershardingkey!r}, "
             + f"debug_jdwp={self.debug_jdwp!r}, "
-            + f"connection_id_prefix={self.connection_id_prefix!r}"
+            + f"connection_id_prefix={self.connection_id_prefix!r}, "
+            + f"ssl_context={self.ssl_context!r}"
             + ")"
         )
 
@@ -532,6 +540,17 @@ def sid(self) -> Union[list, str]:
         """
         return self._impl.sid
 
+    @property
+    def ssl_context(self) -> Any:
+        """
+        An SSLContext object used for connecting to the database using TLS.
+        This SSL context will be modified to include the private key or any
+        certificates found in a separately supplied wallet. This parameter
+        should only be specified if the default SSLContext object cannot be
+        used..
+        """
+        return self._impl.ssl_context
+
     @property
     @_description_attr
     def ssl_server_cert_dn(self) -> Union[list, str]:
@@ -679,6 +698,7 @@ def set(
         supershardingkey: list = None,
         debug_jdwp: str = None,
         connection_id_prefix: str = None,
+        ssl_context: Any = None,
         handle: int = None,
         threaded: bool = None,
         encoding: str = None,
@@ -821,6 +841,12 @@ def set(
         - connection_id_prefix: an application specific prefix that is added to
           the connection identifier used for tracing
 
+        - ssl_context: an SSLContext object used for connecting to the database
+          using TLS.  This SSL context will be modified to include the private
+          key or any certificates found in a separately supplied wallet. This
+          parameter should only be specified if the default SSLContext object
+          cannot be used.
+
         - 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

Diff for: src/oracledb/connection.py

@@ -1177,6 +1177,7 @@ def connect(
     supershardingkey: list = None,
     debug_jdwp: str = None,
     connection_id_prefix: str = None,
+    ssl_context: Any = None,
     handle: int = 0,
     threaded: bool = True,
     encoding: str = None,
@@ -1349,6 +1350,12 @@ def connect(
     - connection_id_prefix: an application specific prefix that is added to the
       connection identifier used for tracing (default: None)
 
+    - ssl_context: an SSLContext object used for connecting to the database
+      using TLS.  This SSL context will be modified to include the private key
+      or any certificates found in a separately supplied wallet. This parameter
+      should only be specified if the default SSLContext object cannot be used.
+      (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)

Diff for: src/oracledb/impl/base/connect_params.pyx

@@ -158,6 +158,7 @@ cdef class ConnectParamsImpl:
         _set_bool_param(args, "matchanytag", &self.matchanytag)
         _set_uint_param(args, "stmtcachesize", &self.stmtcachesize)
         _set_bool_param(args, "disable_oob", &self.disable_oob)
+        self.ssl_context = args.get("ssl_context")
         _set_str_param(args, "debug_jdwp", self)
         _set_str_param(args, "config_dir", self)
         self.appcontext = args.get("appcontext")
@@ -198,6 +199,7 @@ cdef class ConnectParamsImpl:
         self.stmtcachesize = other_params.stmtcachesize
         self.disable_oob = other_params.disable_oob
         self.debug_jdwp = other_params.debug_jdwp
+        self.ssl_context = other_params.ssl_context
         self.description_list = other_params.description_list
         self.access_token_callback = other_params.access_token_callback
         self.access_token_expires = other_params.access_token_expires

Diff for: src/oracledb/impl/thin/crypto.pyx

@@ -111,7 +111,9 @@ def get_ssl_socket(sock, ConnectParamsImpl params, Description description,
     Returns a wrapped SSL socket given a socket and the parameters supplied by
     the user.
     """
-    ssl_context = ssl.create_default_context()
+    ssl_context = params.ssl_context
+    if ssl_context is None:
+        ssl_context = ssl.create_default_context()
 
     # if the platform is macOS, and one-way TLS or mTLS is being used, check
     # if the certifi package is installed. If certifi is not installed, load

Diff for: src/oracledb/pool.py

@@ -34,7 +34,7 @@
 # -----------------------------------------------------------------------------
 
 import functools
-from typing import Callable, Type, Union
+from typing import Callable, Type, Union, Any
 
 import oracledb
 
@@ -610,6 +610,7 @@ def create_pool(
     supershardingkey: list = None,
     debug_jdwp: str = None,
     connection_id_prefix: str = None,
+    ssl_context: Any = None,
     handle: int = 0,
     threaded: bool = True,
     encoding: str = None,
@@ -832,6 +833,12 @@ def create_pool(
     - connection_id_prefix: an application specific prefix that is added to the
       connection identifier used for tracing (default: None)
 
+    - ssl_context: an SSLContext object used for connecting to the database
+      using TLS.  This SSL context will be modified to include the private key
+      or any certificates found in a separately supplied wallet. This parameter
+      should only be specified if the default SSLContext object cannot be used.
+      (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)

Diff for: src/oracledb/pool_params.py

@@ -33,7 +33,7 @@
 # more information.
 # -----------------------------------------------------------------------------
 
-from typing import Callable, Type, Union
+from typing import Callable, Type, Union, Any
 
 import oracledb
 
@@ -104,6 +104,7 @@ def __init__(
         supershardingkey: list = None,
         debug_jdwp: str = None,
         connection_id_prefix: str = None,
+        ssl_context: Any = None,
         handle: int = 0,
         threaded: bool = True,
         encoding: str = None,
@@ -310,6 +311,12 @@ def __init__(
         - connection_id_prefix: an application specific prefix that is added to
           the connection identifier used for tracing (default: None)
 
+        - ssl_context: an SSLContext object used for connecting to the database
+          using TLS.  This SSL context will be modified to include the private
+          key or any certificates found in a separately supplied wallet. This
+          parameter should only be specified if the default SSLContext object
+          cannot be used. (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)
@@ -365,7 +372,8 @@ def __repr__(self):
             + f"shardingkey={self.shardingkey!r}, "
             + f"supershardingkey={self.supershardingkey!r}, "
             + f"debug_jdwp={self.debug_jdwp!r}, "
-            + f"connection_id_prefix={self.connection_id_prefix!r}"
+            + f"connection_id_prefix={self.connection_id_prefix!r}, "
+            + f"ssl_context={self.ssl_context!r}"
             + ")"
         )
 
@@ -541,6 +549,7 @@ def set(
         supershardingkey: list = None,
         debug_jdwp: str = None,
         connection_id_prefix: str = None,
+        ssl_context: Any = None,
         handle: int = None,
         threaded: bool = None,
         encoding: str = None,
@@ -734,6 +743,12 @@ def set(
         - connection_id_prefix: an application specific prefix that is added to
           the connection identifier used for tracing
 
+        - ssl_context: an SSLContext object used for connecting to the database
+          using TLS.  This SSL context will be modified to include the private
+          key or any certificates found in a separately supplied wallet. This
+          parameter should only be specified if the default SSLContext object
+          cannot be used.
+
         - 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

Diff for: tests/test_4500_connect_params.py

@@ -738,6 +738,7 @@ def test_4564_repr(self):
             ("supershardingkey", [4]),
             ("debug_jdwp", "host=host;port=4538"),
             ("connection_id_prefix", "prefix4564"),
+            ("ssl_context", None),
         ]
         params = oracledb.ConnectParams(**dict(values))
         parts = [f"{name}={value!r}" for name, value in values]

Diff for: tests/test_4700_pool_params.py

@@ -112,6 +112,7 @@ def test_4701_repr(self):
             ("supershardingkey", [4]),
             ("debug_jdwp", "host=host;port=1523"),
             ("connection_id_prefix", "prefix4701"),
+            ("ssl_context", None),
         ]
         params = oracledb.PoolParams(**dict(values))
         parts = [f"{name}={value!r}" for name, value in values]

Diff for: utils/fields.cfg

@@ -403,6 +403,14 @@ description =
     an application specific prefix that is added to the connection identifier
     used for tracing
 
+[ssl_context]
+type = Any
+description =
+    an SSLContext object used for connecting to the database using TLS.  This
+    SSL context will be modified to include the private key or any certificates
+    found in a separately supplied wallet. This parameter should only be
+    specified if the default SSLContext object cannot be used.
+
 [handle]
 type = int
 default = 0

Diff for: utils/templates/connect_params.py

@@ -32,7 +32,7 @@
 # -----------------------------------------------------------------------------
 
 import functools
-from typing import Union, Callable
+from typing import Union, Callable, Any
 
 import oracledb
 

Diff for: utils/templates/pool.py

@@ -32,7 +32,7 @@
 # -----------------------------------------------------------------------------
 
 import functools
-from typing import Callable, Type, Union
+from typing import Callable, Type, Union, Any
 
 import oracledb
 

Diff for: utils/templates/pool_params.py

@@ -31,7 +31,7 @@
 # # {{ generated_notice }}
 # -----------------------------------------------------------------------------
 
-from typing import Callable, Type, Union
+from typing import Callable, Type, Union, Any
 
 import oracledb