Improve error message when NNE is required by the server.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -47,6 +47,11 @@ Thin Mode Changes
 #)  Error ``DPY-3001: bequeath is only supported in python-oracledb thick
     mode`` is now raised when attempting to connect to the database without a
     connect string.
+#)  Error ``DPY-3001: Native Network Encryption and Data Integrity is only
+    supported in python-oracledb thick mode`` is now the secondary error
+    message returned when Oracle Net NNE or checksumming is required by the
+    database. Previously, the error ``DPY-4011: the database or network closed
+    the connection`` was raised.
 #)  Optimization: the connect descriptor sent to the database does not include
     the RETRY_DELAY parameter unless the RETRY_COUNT parameter is also
     specified.

doc/src/user_guide/troubleshooting.rst

@@ -253,6 +253,54 @@ DPY Error Messages
 The python-oracledb Thin mode code and python-oracledb Thick mode code
 generates error messages with the prefix ``DPY``.
 
+.. _dpy3001:
+
+DPY-3001
+++++++++
+
+**Message:** ``DPY-3001: Native Network Encryption and Data Integrity is only
+supported in python-oracledb thick mode``
+
+**Action:** To verify if NNE or checksumming are enabled, you can use the
+following query::
+
+    SELECT network_service_banner FROM v$session_connect_info;
+
+If NNE is enabled, then this query prints output that includes the
+available encryption service, the crypto-checksumming service, and the
+algorithms in use, such as::
+
+    NETWORK_SERVICE_BANNER
+    -------------------------------------------------------------------------------------
+    TCP/IP NT Protocol Adapter for Linux: Version 19.0.0.0.0 - Production
+    Encryption service for Linux: Version 19.0.1.0.0 - Production
+    AES256 Encryption service adapter for Linux: Version 19.0.1.0.0 - Production
+    Crypto-checksumming service for Linux: Version 19.0.1.0.0 - Production
+    SHA256 Crypto-checksumming service adapter for Linux: Version 19.0.1.0.0 - Production
+
+If NNE is not enabled, then the query will only print the available encryption
+and crypto-checksumming services in the output. For example::
+
+    NETWORK_SERVICE_BANNER
+    -------------------------------------------------------------------------------------
+    TCP/IP NT Protocol Adapter for Linux: Version 19.0.0.0.0 - Production
+    Encryption service for Linux: Version 19.0.1.0.0 - Production
+
+If NNE or checksumming are enabled, you can resolve this error by either:
+
+- Changing the architecture to use Transport Layer Security (TLS), which is
+  supported in python-oracledb Thin and Thick modes. See `Configuring
+  Transport Layer Security Encryption
+  <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-8B82DD7E-7189-4FE9-8F3B-4E521706E1E4>`__.
+- Or :ref:`enabling python-oracledb Thick mode <enablingthick>`.
+
+.. seealso::
+
+    `Oracle Database Security Guide <https://www.oracle.com/pls/topic/lookup?
+    ctx=dblatest&id=DBSEG>`__ for more information about Oracle Data Network
+    Encryption and Integrity, and for information about configuring TLS
+    network encryption.
+
 DPY-3010
 ++++++++
 
@@ -330,48 +378,15 @@ DPY-4011
 **Cause:** If this occurs when using an already opened connection, additional
 messages may indicate a reason.
 
-If the error occurs when creating a connection or connection pool, the common
-cause is that Oracle Database has Native Network Encryption (NNE) enabled. NNE
-is only supported in python-oracledb Thick mode.
-
-**Action:** To verify if NNE is enabled, you can use the following query::
-
-    SELECT network_service_banner FROM v$session_connect_info;
-
-If NNE is enabled, then this query prints output that includes the
-available encryption service, the crypto-checksumming service, and the
-algorithms in use, such as::
-
-    NETWORK_SERVICE_BANNER
-    -------------------------------------------------------------------------------------
-    TCP/IP NT Protocol Adapter for Linux: Version 19.0.0.0.0 - Production
-    Encryption service for Linux: Version 19.0.1.0.0 - Production
-    AES256 Encryption service adapter for Linux: Version 19.0.1.0.0 - Production
-    Crypto-checksumming service for Linux: Version 19.0.1.0.0 - Production
-    SHA256 Crypto-checksumming service adapter for Linux: Version 19.0.1.0.0 - Production
-
-If NNE is not enabled, then the query will only print the available encryption
-and crypto-checksumming services in the output. For example::
-
-    NETWORK_SERVICE_BANNER
-    -------------------------------------------------------------------------------------
-    TCP/IP NT Protocol Adapter for Linux: Version 19.0.0.0.0 - Production
-    Encryption service for Linux: Version 19.0.1.0.0 - Production
+If the error occurs when creating a connection or connection pool with
+python-oracledb 2 or earlier, the common cause is that Oracle Database has
+Native Network Encryption (NNE) enabled.  NNE and Oracle Net checksumming are
+only supported in python-oracledb Thick mode.
 
-If NNE is enabled, you can resolve this error by either:
+**Action:** Review if NNE or checksumming are enabled. See
+:ref:`DPY-3001 <dpy3001>` for solutions.
 
-- Changing the architecture to use Transport Layer Security (TLS), which is
-  supported in python-oracledb Thin and Thick modes. See `Configuring
-  Transport Layer Security Encryption
-  <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-8B82DD7E-7189-4FE9-8F3B-4E521706E1E4>`__.
-- Or :ref:`enabling python-oracledb Thick mode <enablingthick>`.
-
-.. seealso::
-
-    `Oracle Database Security Guide <https://www.oracle.com/pls/topic/lookup?
-    ctx=dblatest&id=DBSEG>`__ for more information about Oracle Data Network
-    Encryption and Integrity, and for information about configuring TLS
-    network encryption.
+If additional messages indicate a reason, follow their guidance.
 
 .. _oraerr:
 

src/oracledb/impl/thin/constants.pxi

@@ -268,6 +268,7 @@ cdef enum:
 cdef enum:
     TNS_GSO_DONT_CARE = 0x0001
     TNS_GSO_CAN_RECV_ATTENTION = 0x0400
+    TNS_NSI_NA_REQUIRED = 0x10
     TNS_NSI_DISABLE_NA = 0x04
     TNS_NSI_SUPPORT_SECURITY_RENEG = 0x80
 

src/oracledb/impl/thin/messages.pyx

@@ -1856,7 +1856,8 @@ cdef class ConnectMessage(Message):
         cdef:
             uint16_t protocol_version, protocol_options
             const char_type *redirect_data
-            uint32_t flags = 0
+            uint32_t flags2 = 0
+            uint8_t flags1
             bytes db_uuid
         if buf._current_packet.packet_type == TNS_PACKET_TYPE_REDIRECT:
             if not self.read_redirect_data_len:
@@ -1875,13 +1876,18 @@ cdef class ConnectMessage(Message):
             if protocol_version < TNS_VERSION_MIN_ACCEPTED:
                 errors._raise_err(errors.ERR_SERVER_VERSION_NOT_SUPPORTED)
             buf.read_uint16be(&protocol_options)
-            buf.skip_raw_bytes(20)
+            buf.skip_raw_bytes(10)
+            buf.read_ub1(&flags1)
+            if flags1 & TNS_NSI_NA_REQUIRED:
+                feature = "Native Network Encryption and Data Integrity"
+                errors._raise_not_supported(feature)
+            buf.skip_raw_bytes(9)
             buf.read_uint32be(&buf._caps.sdu)
             if protocol_version >= TNS_VERSION_MIN_OOB_CHECK:
                 buf.skip_raw_bytes(5)
-                buf.read_uint32be(&flags)
+                buf.read_uint32be(&flags2)
             buf._caps._adjust_for_protocol(protocol_version, protocol_options,
-                                           flags)
+                                           flags2)
             buf._transport._full_packet_size = True
         elif buf._current_packet.packet_type == TNS_PACKET_TYPE_REFUSE:
             response = self.error_info.message