diff --git a/README.md b/README.md index 84d0cf5d..9a751ce4 100644 --- a/README.md +++ b/README.md @@ -675,6 +675,8 @@ Server=localhost,1433;Database=database;User Id=username;Password=password;Encry Driver=msnodesqlv8;Server=(local)\INSTANCE;Database=database;UID=DOMAIN\username;PWD=password;Encrypt=true ``` +`Encrypt` takes `true`, `yes`, `mandatory` or `1` to encrypt, and `false`, `no`, `optional` or `0` to not encrypt. It also takes `strict`, which sets `options.encrypt` to `'strict'` and turns on TDS 8.0 strict encryption with the [tedious](#tedious) and [MSNodeSQLv8](#msnodesqlv8) drivers. These values are not case sensitive. With the tedious driver, a connection that does not encrypt fails if the server requires encryption. + ##### Azure Active Directory Authentication Connection String Several types of Azure Authentication are supported: @@ -726,7 +728,7 @@ require('mssql').connect({...config, beforeConnect: conn => { ``` - **options.instanceName** - The instance name to connect to. The SQL Server Browser service must be running on the database server, and UDP port 1434 on the database server must be reachable. - **options.useUTC** - A boolean determining whether or not use UTC time for values without time zone offset (default: `true`). -- **options.encrypt** - A boolean determining whether or not the connection will be encrypted (default: `true`). +- **options.encrypt** - A boolean determining whether or not the connection will be encrypted, or `'strict'` to use TDS 8.0 strict encryption (default: `true`). In a connection string, `Encrypt=strict` sets `'strict'`. - **options.tdsVersion** - The version of TDS to use (default: `7_4`, available: `7_1`, `7_2`, `7_3_A`, `7_3_B`, `7_4`). - **options.appName** - Application name used for SQL server logging. - **options.abortTransactionOnError** - A boolean determining whether to rollback a transaction automatically if any error is encountered during the given transaction's execution. This sets the value for `XACT_ABORT` during the initial SQL phase of a connection. @@ -765,6 +767,7 @@ msnodesqlv8 5 and earlier round `float` and `real` values, and `decimal` values - **connectionString** - Connection string (default: see below). - **options.instanceName** - The instance name to connect to. The SQL Server Browser service must be running on the database server, and UDP port 1444 on the database server must be reachable. - **options.trustedConnection** - Use Windows Authentication (default: `false`). +- **options.encrypt** - A boolean determining whether or not the connection will be encrypted, or `'strict'` to use TDS 8.0 strict encryption (default: `false`). `'strict'` writes `Encrypt=Strict` to the connection string, which needs ODBC Driver 18 or later, so set `driver` to that driver, for example `driver: 'ODBC Driver 18 for SQL Server'`. - **options.useUTC** - A boolean determining whether or not to use UTC time for values without time zone offset (default: `true`). Default connection string when connecting to port: diff --git a/lib/base/connection-pool.js b/lib/base/connection-pool.js index e11be7f6..3dd07a33 100644 --- a/lib/base/connection-pool.js +++ b/lib/base/connection-pool.js @@ -15,6 +15,8 @@ const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnosti // parser handles it the same as a left-out key. const NODE_MSSQL_SCHEMA = Object.fromEntries(Object.entries({ ...MSSQL_SCHEMA, + // read as a string, because `strict` is a valid value as well as a boolean + encrypt: { ...MSSQL_SCHEMA.encrypt, type: 'string' }, useutc: { type: 'boolean' }, stream: { type: 'boolean' }, parsejson: { type: 'boolean' }, @@ -239,11 +241,20 @@ class ConnectionPool extends EventEmitter { } break } - case 'encrypt': + case 'encrypt': { + // an empty value is not set + if (!value.trim()) { + break + } + const encrypt = value.toLowerCase() Object.assign(config.options, { - encrypt: !!value + // `strict` is TDS 8.0 strict encryption, and `optional` is a + // synonym of `false` (as in SqlClient 5 and ODBC Driver 18); other + // values have the boolean meaning of @tediousjs/connection-string + encrypt: encrypt === 'strict' ? 'strict' : !['false', 'no', '0', 'optional'].includes(encrypt) }) break + } case 'enlist': break case 'failover partner': diff --git a/lib/msnodesqlv8/connection-pool.js b/lib/msnodesqlv8/connection-pool.js index 7b50d56a..d137ec74 100644 --- a/lib/msnodesqlv8/connection-pool.js +++ b/lib/msnodesqlv8/connection-pool.js @@ -30,7 +30,8 @@ class ConnectionPool extends BaseConnectionPool { Uid: this.config.user, Pwd: this.config.password, Trusted_Connection: !!this.config.options.trustedConnection, - Encrypt: !!this.config.options.encrypt + // ODBC Driver 18 and later accept Strict (TDS 8.0); older drivers do not + Encrypt: this.config.options.encrypt === 'strict' ? 'Strict' : !!this.config.options.encrypt }) } diff --git a/test/common/unit.js b/test/common/unit.js index a1d4a95d..43ced42e 100644 --- a/test/common/unit.js +++ b/test/common/unit.js @@ -857,6 +857,56 @@ describe('connection string encrypt option', () => { assert.strictEqual(config.options.encrypt, false) }) + it('parses Encrypt=1 as true', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=1') + assert.strictEqual(config.options.encrypt, true) + }) + + it('parses Encrypt=0 as false', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=0') + assert.strictEqual(config.options.encrypt, false) + }) + + it('parses Encrypt=FALSE as false', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=FALSE') + assert.strictEqual(config.options.encrypt, false) + }) + + it('parses Encrypt=mandatory as true', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=mandatory') + assert.strictEqual(config.options.encrypt, true) + }) + + it('parses Encrypt=optional as false', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=optional') + assert.strictEqual(config.options.encrypt, false) + }) + + it('parses Encrypt=Optional as false', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=Optional') + assert.strictEqual(config.options.encrypt, false) + }) + + it('parses Encrypt=strict as strict', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=strict') + assert.strictEqual(config.options.encrypt, 'strict') + }) + + it('parses Encrypt=Strict as strict', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=Strict') + assert.strictEqual(config.options.encrypt, 'strict') + }) + + it('parses Encrypt=STRICT as strict', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt=STRICT') + assert.strictEqual(config.options.encrypt, 'strict') + }) + + it('parses a quoted Encrypt strict value as strict', () => { + const config = BasePool._parseConnectionString('Server=localhost;Encrypt={strict}') + assert.strictEqual(config.options.encrypt, 'strict') + }) + it('uses the tedious default when Encrypt is empty', () => { const config = new ConnectionPool('Server=localhost;Encrypt=;Database=db')._config() assert.strictEqual(config.options.encrypt, true) @@ -867,6 +917,77 @@ describe('connection string encrypt option', () => { const config = new ConnectionPool('Server=localhost;Encrypt=false')._config() assert.strictEqual(config.options.encrypt, false) }) + + it('uses Encrypt=Strict in the tedious config', () => { + const config = new ConnectionPool('Server=localhost;Encrypt=Strict')._config() + assert.strictEqual(config.options.encrypt, 'strict') + }) + + describe('msnodesqlv8', () => { + const Module = require('node:module') + // msnodesqlv8 is a native module that only the Windows CI jobs install, so a stand-in + // keeps the connection string that the pool opens, and refuses the connection + const STUB = 'msnodesqlv8-stub' + const POOL = require.resolve('../../lib/msnodesqlv8/connection-pool') + let resolveFilename + let MsnodesqlPool + let connectionString + + before(() => { + resolveFilename = Module._resolveFilename + Module._resolveFilename = function (request, ...rest) { + return request === 'msnodesqlv8' ? STUB : resolveFilename.call(this, request, ...rest) + } + const exports = { + open (cfg, callback) { + connectionString = cfg.conn_str + setImmediate(callback, new Error('no server')) + } + } + require.cache[STUB] = { id: STUB, filename: STUB, loaded: true, exports } + MsnodesqlPool = require(POOL) + }) + + after(() => { + Module._resolveFilename = resolveFilename + delete require.cache[STUB] + delete require.cache[POOL] + }) + + const open = async config => { + connectionString = undefined + await assert.rejects(new MsnodesqlPool(config)._poolCreate(), /no server/) + return connectionString + } + + it('writes Encrypt=Strict for Encrypt=strict', async () => { + assert.match(await open('Server=localhost;Encrypt=strict'), /;Encrypt=Strict$/) + }) + + it('writes Encrypt=Strict for an encrypt option of strict', async () => { + assert.match(await open({ server: 'localhost', options: { encrypt: 'strict' } }), /;Encrypt=Strict$/) + }) + + it('writes Encrypt=Yes for Encrypt=true', async () => { + assert.match(await open('Server=localhost;Encrypt=true'), /;Encrypt=Yes$/) + }) + + it('writes Encrypt=No for Encrypt=false', async () => { + assert.match(await open('Server=localhost;Encrypt=false'), /;Encrypt=No$/) + }) + + it('writes Encrypt=Yes for Encrypt=mandatory', async () => { + assert.match(await open('Server=localhost;Encrypt=mandatory'), /;Encrypt=Yes$/) + }) + + it('writes Encrypt=No for Encrypt=optional', async () => { + assert.match(await open('Server=localhost;Encrypt=optional'), /;Encrypt=No$/) + }) + + it('writes Encrypt=No when Encrypt is left out', async () => { + assert.match(await open('Server=localhost'), /;Encrypt=No$/) + }) + }) }) describe('connection string empty values', () => {