Network improvements

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -966,9 +966,10 @@ Each of the configuration properties is described below.
     authentication. See :ref:`External Authentication <extauth>` for more
     information.
 
-    In node-oracledb Thin mode, when token-based authentication is required,
-    this property must be set to *true*. In all the other cases where this
-    property is set to *true*, an error is thrown.
+    In node-oracledb Thin mode, when token-based authentication or
+    :ref:`external authentication using TLS <tlsextauth>` is required, this
+    property must be set to *true*. In all the other cases where this property
+    is set to *true*, an error is thrown.
 
     The default value is *false*.
 
@@ -2120,7 +2121,7 @@ Oracledb Methods
 
             The default is *false*.
 
-            In Thin mode, when token-based authentication is required, this property must be set to *true*. In all the other cases where this property is set to *true*, an error is thrown.
+            In Thin mode, when token-based authentication or :ref:`external authentication using TLS <tlsextauth>` is required, this property must be set to *true*. In all the other cases where this property is set to *true*, an error is thrown.
 
             This optional property overrides the :attr:`oracledb.externalAuth` property.
 
@@ -2897,7 +2898,7 @@ Oracledb Methods
 
             If this optional property is set to *true* in Thick mode, then the connection will be established using :ref:`External Authentication <extauth>`.
 
-            In Thin mode, when token-based authentication is required, this property must be set to *true*. In all the other cases where this property is set to *true*, an error is thrown.
+            In Thin mode, when token-based authentication or :ref:`external authentication using TLS <tlsextauth>` is required, this property must be set to *true*. In all the other cases where this property is set to *true*, an error is thrown.
 
             This optional property overrides the :attr:`oracledb.externalAuth` property.
 

doc/src/user_guide/connection_handling.rst

@@ -1981,17 +1981,28 @@ Connecting Using External Authentication
 External Authentication allows applications to use an external password
 store (such as an `Oracle Wallet <https://www.oracle.com/pls/topic/lookup?
 ctx=dblatest&id=GUID-E3E16C82-E174-4814-98D5-EADF1BCB3C37>`__),
-the `Secure Socket Layer <https://www.oracle.com/pls/topic/lookup?ctx=
-dblatest&id=GUID-6AD89576-526F-4D6B-A539-ADF4B840819F>`__
-(SSL), or the `operating system <https://www.oracle.com/pls/topic/lookup
-?ctx=dblatest&id=GUID-37BECE32-58D5-43BF-A098-97936D66968F>`__
-to validate user access. One of the benefits is that database
-credentials do not need to be hard coded in the application.
+the `Transport Layer Security (TLS) or Secure Socket Layer (SSL)
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-6AD89576-526F-
+4D6B-A539-ADF4B840819F>`__, or the `operating system <https://www.oracle.com/
+pls/topic/lookup?ctx=dblatest&id=GUID-37BECE32-58D5-43BF-A098-97936D66968F>`__
+to validate user access. With an external password store, your application can
+use an Oracle Wallet to authenticate users. External Authentication using TLS
+authenticates users with Public Key Infrastructure (PKI) certificates. With
+operating system authentication, user authentication can be performed if the
+user has an operating system account on their machine recognized by Oracle
+Database. One of the benefits of using external authentication is that
+database credentials do not need to be hard coded in the application.
 
 .. note::
 
-    Connecting to Oracle Database using external authentication is only
-    supported in node-oracledb Thick mode. See :ref:`enablingthick`.
+    Connecting to Oracle Database using external authentication with an Oracle
+    Wallet, TLS, or the operating system is supported in node-oracledb Thick
+    mode. See :ref:`enablingthick`.
+
+    Node-oracledb Thin mode only supports external authentication with TLS.
+    See :ref:`tlsextauth` for more information.
+
+**In node-oracledb Thick Mode**
 
 To use external authentication, set the :attr:`oracledb.externalAuth` property
 to *true*. This property can also be set in the ``connAttrs`` or ``poolAttrs``
@@ -2073,6 +2084,67 @@ connections exceeds ``poolMin`` and connections are idle for more than
 the :attr:`oracledb.poolTimeout` seconds, then the number of
 open connections does not fall below ``poolMin``.
 
+.. _tlsextauth:
+
+External Authentication Using TLS
+---------------------------------
+
+External authentication with Transport Layer Security (TLS) uses `Public Key
+Infrastructure (PKI) certificates <https://www.oracle.com/pls/topic/lookup?ctx
+=dblatest&id=GUID-6AD89576-526F-4D6B-A539-ADF4B840819F>`__ to authenticate
+users. This authentication method can be used in both node-oracledb Thin and
+Thick modes.
+
+To use TLS external authentication, you must set the
+:attr:`oracledb.externalAuth` property to *true*. This property can also be
+set in the ``externalAuth`` parameter of the :meth:`oracledb.getConnection()`
+or :meth:`oracledb.createPool()` calls. TLS external authentication can only
+be done for connections that are configured to use the *TCPS* protocol.
+
+For a standalone connection, you can use TLS authentication to authenticate
+the user as shown in the example below:
+
+.. code-block:: javascript
+
+    const config = { connectString: "tcps://localhost/orclpdb1", externalAuth: true };
+    const connection = await oracledb.getConnection(config);
+
+Note that TLS external authentication will not be enabled if you are using
+token-based authentication (that is, the ``accessToken`` property is set in
+:meth:`oracledb.getConnection()` or :meth:`oracledb.createPool()`).
+
+For a connection pool, you can authenticate with TLS as shown in the example
+below:
+
+.. code-block:: javascript
+
+    const config = { connectString: "tcps://localhost/orclpdb1", externalAuth: true };
+    const pool = await oracledb.createPool(config);
+    const connection = await pool.getConnection();
+
+    . . . // connection has access to the schema objects of the externally identified user
+
+    await connection.close();
+
+In node-oracledb Thick mode, ensure that the `SQLNET.AUTHENTICATION_SERVICES
+<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-FFDBCCFD-87EF
+-43B8-84DA-113720FCC095>`__ parameter contains *TCPS* as a value in the
+:ref:`sqlnet.ora <tnsadmin>` file. Note that *TCPS* is the default value of
+this parameter.
+
+Additional server side configuration is also required to enable external
+authentication using TLS:
+
+1. Create a user corresponding to the distinguished name (DN) in the
+   certificate using:
+
+   .. code-block:: sql
+
+     CREATE USER user_name IDENTIFIED EXTERNALLY AS 'user DN on certificate';
+
+2. Set the ``SSL_CLIENT_AUTHENTICATION`` parameter to *TRUE* in the server-side
+   :ref:`sqlnet.ora <tnsadmin>` file.
+
 .. _tokenbasedauthentication:
 
 Token-Based Authentication

doc/src/user_guide/troubleshooting.rst

@@ -170,3 +170,40 @@ NJS-116
           If your username uses the 10G password verifier, then you need to upgrade your password verifier in Oracle Database to 11G or later to use node-oracledb Thin mode. To upgrade your password verifier, see `Finding and Resetting User Passwords That Use the 10G Password Verifier <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-D7B09DFE-F55D-449A-8F8A-174D89936304>`__ for the detailed steps.
 
         - Or :ref:`enable Thick mode <enablingthick>` since node-oracledb Thick mode supports password verifiers 10G and later.
+
+.. _oraerr:
+
+ORA Error Messages
+------------------
+
+The error messages with the prefix ``ORA`` are generated by Oracle Database.
+
+.. _ora0107:
+
+ORA-0107
+++++++++
+
+.. list-table-with-summary::
+    :stub-columns: 1
+    :class: wy-table-responsive
+    :widths: 5 35
+    :summary: The first row displays the ORA-0107 error message. The second row displays the probable cause for the ORA-0107 error. The third row displays the possible solution to resolve the ORA-0107 error.
+
+    * - Message
+      - ``ORA-01017: invalid credential or not authorized; logon denied``
+    * - Cause
+      - An invalid credential was provided when accessing the Oracle Database or you were not authorized to access this database.
+    * - Action
+      - If external authentication is set to *true*, then verify the following:
+
+        - If :ref:`TLS Authentication <tlsextauth>` is enabled, then ensure that:
+
+          - A user has been created in Oracle Database corresponding to the distinguished name (DN) in the user certificate using::
+
+                CREATE USER user_name IDENTIFIED EXTERNALLY AS 'user DN on certificate';
+
+          - The parameter ``SSL_CLIENT_AUTHENTICATION`` is set to *TRUE* in the server-side :ref:`sqlnet.ora <tnsadmin>` file.
+
+        - If you are using :ref:`token-based authentication <tokenbasedauthentication>`, then ensure that you have provided a valid user access token.
+
+        Note that storing password credentials in an Oracle wallet is not supported in node-oracledb Thin mode.

lib/thin/sqlnet/networkSession.js

@@ -301,8 +301,6 @@ class NetworkSession {
     this.connected = true;
     this.cData = null;
     this.sndDatapkt = new Packet.DataPacket(this.sAtts.largeSDU);
-    this.sndDatapkt.offset = this.sndDatapkt.dataPtr;
-    this.sndDatapkt.len = this.sndDatapkt.bufLen;
     this.markerPkt = new Packet.MarkerPacket(this.sAtts.largeSDU);
     this.controlPkt = new Packet.ControlPacket();
     this.ntAdapter.largeSDU = this.sAtts.largeSDU;
@@ -319,6 +317,8 @@ class NetworkSession {
     }
 
     this.sndDatapkt.createPacket(constants.NSPDADAT); //Currently only used for disconnect
+    this.sndDatapkt.offset = this.sndDatapkt.dataPtr;
+    this.sndDatapkt.len = this.sndDatapkt.bufLen;
     return (true);
   }
 

lib/thin/sqlnet/sessionAtts.js

@@ -83,7 +83,7 @@ class SessionAtts {
             this.networkCompressionLevels.push('high');
         }
       }
-      if (params.networkCompressionThreshold > 200) {
+      if (params.networkCompressionThreshold >= 200) {
         this.networkCompressionThreshold = parseInt(params.networkCompressionThreshold);
       } else
         this.networkCompressionThreshold = 1024;