Added support for SNI (Server Name Indicator), an Oracle Database 23.7 network optimization feature

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -2574,6 +2574,20 @@ Oracledb Methods
             .. versionadded:: 5.2
 
                 The alias ``username``.
+        * - ``useSNI``
+          - Boolean
+          - Thin
+          - .. _createpoolpoolattrsusesni:
+
+            Enables the connection to use the TLS extension, Server Name Indication (SNI).
+
+            Usually, two TLS handshakes are required to establish a connection, one with the listener and the other with the server process. With useSNI, the connection information is sent in the SNI field which enables the listener to hand-off the connection to the appropriate server process without the listener having to perform a TLS handshake. SNI helps improve the connection establishment time.
+
+            The default is *False*.
+
+            This property requires Oracle Database 23.7 (or later).
+
+            .. versionadded:: 6.8
 
     **createPool(): accessToken Object Properties**
 
@@ -3214,6 +3228,20 @@ Oracledb Methods
             .. versionadded:: 5.2
 
                 The alias ``username``.
+        * - ``useSNI``
+          - Boolean
+          - Thin
+          - .. _getconnectiondbattrsusesni:
+
+            Enables the connection to use the TLS extension, Server Name Indication (SNI).
+
+            Usually, two TLS handshakes are required to establish a connection, one with the listener and the other with the server process. With useSNI, the connection information is sent in the SNI field which enables the listener to hand-off the connection to the appropriate server process without the listener having to perform a TLS handshake. SNI helps improve the connection establishment time.
+
+            The default is *False*.
+
+            This property requires Oracle Database 23.7 (or later).
+
+            .. versionadded:: 6.8
 
     **getConnection(): accessToken Object Properties**
 

doc/src/release_notes.rst

@@ -28,6 +28,9 @@ Common Changes
 Thin Mode Changes
 +++++++++++++++++
 
+#)  Added connection optimization feature which uses Server Name Indication (SNI)
+    extension of the TLS protocol. 
+ 
 #)  Added support for setting the :attr:`~oracledb.edition` when connecting to
     the database.
 

doc/src/user_guide/appendix_a.rst

@@ -469,6 +469,9 @@ are in a ``tnsnames.ora`` file.  All unrecognized parameters are ignored.
     * - POOL_CONNECTION_CLASS
       - :attr:`cclass <oracledb.connectionClass>`
       - Defines a logical name for connections.
+    * - USE_SNI
+      - :ref:`useSNI <getconnectiondbattrsusesni>`
+      - Indicates whether the TLS extension, Server Name Indication (SNI), is enabled.
 
 In node-oracledb Thick mode, the above values only work when connected to
 Oracle Database 21c or later.

lib/oracledb.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2015, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2015, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -362,6 +362,13 @@ async function _verifyOptions(options, inCreatePool) {
     outOptions.terminal = options.terminal;
   }
 
+  // useSNI must be a boolean
+  if (options.useSNI !== undefined) {
+    errors.assertParamPropValue(typeof options.useSNI === 'boolean', 1,
+      "useSNI");
+    outOptions.useSNI = options.useSNI;
+  }
+
   // check pool specific options
   if (inCreatePool) {
 

lib/thin/sqlnet/ezConnectResolver.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -57,7 +57,7 @@ const EXT_PARAM_SEP = '&';
 const DESCRIPTION_PARAMS = ["ENABLE", "FAILOVER", "LOAD_BALANCE",
   "RECV_BUF_SIZE", "SEND_BUF_SIZE", "SDU",
   "SOURCE_ROUTE", "RETRY_COUNT", "RETRY_DELAY",
-  "CONNECT_TIMEOUT", "TRANSPORT_CONNECT_TIMEOUT", "RECV_TIMEOUT"];
+  "CONNECT_TIMEOUT", "TRANSPORT_CONNECT_TIMEOUT", "RECV_TIMEOUT", "USE_SNI"];
 /*
    DESCRIPTION
     This class takes care resolving the EZConnect format to Long TNS URL format.
@@ -459,6 +459,7 @@ class EZConnectResolver {
     aliasMap.set("service_tag", "SERVICE_TAG");
     aliasMap.set("connection_id_prefix", "CONNECTION_ID_PREFIX");
     aliasMap.set("pool_boundary", "POOL_BOUNDARY");
+    aliasMap.set("use_sni", "USE_SNI");
     return aliasMap;
   }
 }module.exports = EZConnectResolver;

lib/thin/sqlnet/navNodes.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -246,6 +246,10 @@ class Description {
         this.failover = (childnv.atom.toLowerCase() == "yes"
                   || childnv.atom.toLowerCase() == "on"
                   || childnv.atom.toLowerCase() == "true");
+      } else if (childnv.name.toUpperCase() == "USE_SNI") {
+        this.params.useSNI = (childnv.atom.toLowerCase() == "yes"
+                            || childnv.atom.toLowerCase() == "on"
+                            || childnv.atom.toLowerCase() == "true");
       } else if (childnv.name.toUpperCase() == "ADDRESS_LIST") {
         child = new NavAddressList();
         child.initFromNVPair(childnv);
@@ -715,6 +719,9 @@ class NavDescription extends Description {
     if ('enable' in this.params) {
       cs.sBuf.push("(ENABLE=" + this.params.enable + ")");
     }
+    if ('useSNI' in this.params) {
+      cs.sBuf.push("(USE_SNI=" + this.params.useSNI + ")");
+    }
     if (('sslServerCertDN' in this.params) || ('sslServerDNMatch' in this.params) || ('walletLocation' in this.params) || ('sslAllowWeakDNMatch' in this.params)) {
       cs.sBuf.push("(SECURITY=");
       if ('sslServerCertDN' in this.params) {

lib/thin/sqlnet/ntTcp.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -34,7 +34,7 @@ const http = require("http");
 const Timers = require('timers');
 const constants = require("./constants.js");
 const errors = require("../../errors.js");
-const { findValue } = require("./nvStrToNvPair.js");
+const { findValue, findNVPair } = require("./nvStrToNvPair.js");
 
 const PACKET_HEADER_SIZE = 8;
 const DEFAULT_PORT = 1521;
@@ -48,6 +48,12 @@ const TCPCHA = 1 << 1 |    /* ASYNC support */
   1 << 9 |    /* Full Duplex support */
   1 << 12;    /* SIGPIPE Support */
 
+const sniAllowedCDParams = ["SERVICE_NAME", "INSTANCE_NAME", "SERVER", "COLOCATION_TAG", "CONNECTION_ID", "POOL_BOUNDARY",
+  "POOL_PURITY", "POOL_CONNECTION_CLASS", "POOL_NAME", "SERVICE_TAG", "CID"];
+const sniParams = ["SERVICE_NAME", "INSTANCE_NAME", "SERVER", "COLOCATION_TAG"];
+const sniMap = ['S', 'I', 'T', 'C'];
+const SNI_MAX_BYTES = 256;
+
 let streamNum = 1;
 
 /**
@@ -113,10 +119,13 @@ class NTTCP {
    */
   async tlsConnect(secureContext, connStream) {
     this.stream.removeAllListeners();
-    let connectErrCause;
+    let connectErrCause, sni = null;
+    if (this.atts.useSNI)
+      sni = this.generateSNI();
     const tlsOptions = {
       host: this.host,
       socket: connStream,
+      servername: sni,
       rejectUnauthorized: true,
       secureContext: secureContext,
       enableTrace: false,
@@ -557,6 +566,44 @@ class NTTCP {
     }
   }
 
+  /**
+   * Generate SNI data.
+   */
+  generateSNI() {
+    /* No SNI if source route is set */
+    if ((findValue(this.atts.cDataNVPair, ["DESCRIPTION", "SOURCE_ROUTE"]) == "yes") ||
+       (findValue(this.atts.cDataNVPair, ["DESCRIPTION", "ADDRESS_LIST", "SOURCE_ROUTE"]) == "yes"))
+      return null;
+
+    const cdnvp = findNVPair(this.atts.cDataNVPair, "CONNECT_DATA");
+    /* Loop through the list of params */
+    for (let i = 0; i < cdnvp.getListSize(); i++) {
+      const child = cdnvp.getListElement(i);
+      if (!sniAllowedCDParams.includes(child.name.toUpperCase()))
+        return null; /* No SNI for unsupported Connect Data params */
+    }
+
+    /* Generate SNI */
+    let value, sni = "";
+    for (let i = 0; i < sniParams.length; i++) {
+      if ((value = findValue(this.atts.cDataNVPair, ["DESCRIPTION", "CONNECT_DATA", sniParams[i]]))) {
+        if (sniParams[i] == 'SERVER') /* For server type just pick the first letter */
+          sni += sniMap[i] + "1" + "." + value[0] + ".";
+        else
+          sni += sniMap[i] + value.length + "." + value + ".";
+      }
+    }
+    sni += "V3." + constants.TNS_VERSION_DESIRED; /* Version */
+
+    const match_pattern = new RegExp("^[A-Za-z0-9._-]+$");
+    if (!(sni.match(match_pattern)))
+      return null; /* No SNI if special characters are present */
+
+    if (sni.length > SNI_MAX_BYTES)
+      return null; /* Max allowed length */
+
+    return sni;
+  }
 }
 
 module.exports = NTTCP;

lib/thin/sqlnet/sessionAtts.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -60,6 +60,7 @@ class SessionAtts {
     this.uuid = uuid;
     this.nt.sslServerDNMatch = true;
     this.nt.sslAllowWeakDNMatch = false;
+    this.nt.useSNI = false;
   }
 
   /**
@@ -119,6 +120,9 @@ class SessionAtts {
       if (params.httpsProxyPort >= 0) {
         this.nt.httpsProxyPort = parseInt(params.httpsProxyPort);
       }
+      if (typeof params.useSNI === 'boolean') {
+        this.nt.useSNI = params.useSNI;
+      }
     }
   }
 

test/ext/sqlnet-tests/sniTest.js

@@ -0,0 +1,120 @@
+/* Copyright (c) 2025, Oracle and/or its affiliates. */
+
+/******************************************************************************
+ *
+ * This software is dual-licensed to you under the Universal Permissive License
+ * (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+ * 2.0 as shown at https://www.apache.org/licenses/LICENSE-2.0. You may choose
+ * either license.
+ *
+ * If you elect to accept the software under the Apache License, Version 2.0,
+ * the following applies:
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * NAME
+ *   1. sniTest.js
+ *
+ * DESCRIPTION
+ *   This test checks that the SNI (Server Name Indication) extension is
+ *   correctly used when connecting to a TLS-enabled database.  With
+ *   NODE_ORACLEDB_DEBUG_PACKETS=on, the packet dump should not show a
+ *   RESEND(NSPTRS) packet with SNI set to true.
+ *
+ *   SNI can be set in dbconfig or the connection string.
+ *   To test SNI using connection string and config, you can try the following
+ *   - Set useSNI to true in dbconfig and USE_SNI = on in the connect string.
+ *   - Set useSNI to false in dbconfig and USE_SNI = off in the connect string.
+ *   - Set useSNI to false in dbconfig and USE_SNI = on in the connect string.
+ *   - Set useSNI to true in dbconfig and USE_SNI = off in the connect string.
+ *
+ *****************************************************************************/
+'use strict';
+const oracledb = require("oracledb");
+const assert = require('assert');
+const fs = require('fs').promises;
+const dbConfig = require('../../dbconfig.js');
+const testsUtil = require('../../testsUtil.js');
+const path = require('path');
+const os = require('os');
+
+describe('1. SNI (Server Name Indication) test', function() {
+  let isRunnable = false;
+  before(async function() {
+    isRunnable = await testsUtil.checkPrerequisites(2306000000, 2306000000);
+
+    if (!isRunnable || !oracledb.thin) this.skip();
+
+    process.env.NODE_ORACLEDB_DEBUG_PACKETS = 1; // Set to '1' to enable packet debugging
+  });
+
+  after(function() {
+    process.env.NODE_ORACLEDB_DEBUG_PACKETS = 0; // Set to '0' to disable packet debugging
+  });
+
+  it('1.1 useSNI parameter set to true in the config', async function() {
+    const tmpobj = await fs.mkdtemp(path.join(os.tmpdir(), 'tmp-'));
+    const tmpfile = path.join(tmpobj, "sniTest.txt");
+    const originalStdoutWrite = process.stdout.write;
+    process.stdout.write = (string) => {
+      fs.appendFile(tmpfile, string, (err) => {
+        if (err) {
+          console.error(err);
+        }
+      });
+      originalStdoutWrite.apply(process.stdout, arguments);
+    };
+    dbConfig.useSNI = true;
+    try {
+      const conn = await oracledb.getConnection(dbConfig);
+      const result = await conn.execute(`SELECT 'Hello World' FROM DUAL`);
+      assert.strictEqual(result.rows[0][0], 'Hello World');
+      await conn.close();
+      process.stdout.write = originalStdoutWrite;
+      const contents = await fs.readFile(tmpfile, {encoding: 'utf8'});
+      assert(!contents.includes('Receiving packet 3 on stream 3:\n' +
+                                '0000 : 00 08 00 00 0B 08 00 00 |........|'));
+    } finally {
+      await fs.unlink(tmpfile);
+      await fs.rmdir(tmpobj);
+    }
+  }); // 1.1
+
+  it('1.2 useSNI parameter set to false in the config', async function() {
+    const tmpobj = await fs.mkdtemp(path.join(os.tmpdir(), 'tmp-'));
+    const tmpfile = path.join(tmpobj, "sniTest.txt");
+    const originalStdoutWrite = process.stdout.write;
+    process.stdout.write = (string) => {
+      fs.appendFile(tmpfile, string, (err) => {
+        if (err) {
+          console.error(err);
+        }
+      });
+      originalStdoutWrite.apply(process.stdout, arguments);
+    };
+    dbConfig.useSNI = false;
+    try {
+      const conn = await oracledb.getConnection(dbConfig);
+      const result = await conn.execute(`SELECT 'Hello World' FROM DUAL`);
+      assert.strictEqual(result.rows[0][0], 'Hello World');
+      await conn.close();
+      process.stdout.write = originalStdoutWrite;
+      const contents = await fs.readFile(tmpfile, {encoding: 'utf8'});
+      assert(contents.includes('Receiving packet 3 on stream 3:\n' +
+        '0000 : 00 08 00 00 0B 08 00 00 |........|'));
+    } finally {
+      await fs.unlink(tmpfile);
+      await fs.rmdir(tmpobj);
+    }
+  }); // 1.2
+});