Merge pull request #1436 from ruiquelhas/master

sidorares · web-flow · commit dadef383098b · 2022-01-27T17:45:27.000+11:00
Add support for multi-factor authentication
diff --git a/documentation/Authentication-Switch.md b/documentation/Authentication-Switch.md
@@ -1,16 +1,46 @@
 # Authentication switch request
 
-During connection phase the server may ask client to switch to a different auth method.
-If `authSwitchHandler` connection config option is set it must be a function that receive
-switch request data and respond via callback. Note that if `mysql_native_password` method is
-requested it will be handled internally according to [Authentication::Native41]( https://dev.mysql.com/doc/internals/en/secure-password-authentication.html#packet-Authentication::Native41) and
-`authSwitchHandler` won't be invoked. `authSwitchHandler` MAY be called multiple times if
-plugin algorithm requires multiple roundtrips of data exchange between client and server.
-First invocation always has `({pluginName, pluginData})` signature, following calls - `({pluginData})`.
-The client respond with opaque blob matching requested plugin via `callback(null, data: Buffer)`.
+During the connection phase the server may ask the client to switch to a different auth method.
+If the `authPlugins` connection config option is set, it must be an object where each key
+is the name of a potential authentication plugin requested by the server, and the corresponding
+value must be a function that optionally receives the connection config options and returns
+another function, which in turn, optionally receives the switch request data.
+
+The plugin is loaded with a `({user,password,...})` signature, and each call has a `(pluginData)`
+signature. Each call should make the plugin return any additional authentication data (`Buffer`)
+that should be sent back to the server, either synchronously or asynchronously using a `Promise`,
+or should yield an error accordingly.
 
 Example: (imaginary `ssh-key-auth` plugin) pseudo code
 
+```js
+const conn = mysql.createConnection({
+  user: 'test_user',
+  password: 'test',
+  database: 'test_database',
+  authPlugins: {
+    'ssh-key-auth': function ({password}) {
+      return function (pluginData) {
+        return getPrivate(key)
+          .then(key => {
+            const response = encrypt(key, password, pluginData);
+            // continue handshake by sending response data
+            return response;
+          })
+          .catch(err => {
+            // throw error to propagate error to connect/changeUser handlers
+          });
+      };
+    }
+  }
+});
+```
+
+There is also a deprecated API where if a `authSwitchHandler` connection config option is set
+it must be a function that receives switch request data and responds via a callback. In this case,
+the first invocation always has a `({pluginName, pluginData})` signature, following calls - `({pluginData})`.
+The client replies with an opaque blob matching the requested plugin via `callback(null, data: Buffer)`.
+
 ```js
 const conn = mysql.createConnection({
   user: 'test_user',
@@ -33,4 +63,47 @@ const conn = mysql.createConnection({
 });
 ```
 
-Initial handshake always performed using `mysql_native_password` plugin. This will be possible to override in the future versions.
+The initial handshake is always performed using `mysql_native_password` plugin. This will be possible to override in future versions.
+
+Note that if the `mysql_native_password` method is requested it will be handled internally according
+to [Authentication::Native41]( https://dev.mysql.com/doc/internals/en/secure-password-authentication.html#packet-Authentication::Native41)
+and no `authPlugins` function or the `authSwitchHandler` will be invoked.
+
+These MAY be called multiple times if the plugin algorithm requires multiple roundtrips of data
+exchange between client and server.
+
+## Multi-factor authentication
+
+If the user requires multi-factor authentication in the server, the client will receive a `AuthNextFactor`
+request, which is similar in structure to the regular authentication switch request and contains the name
+and possible initial data for the additional authentication factor plugin (up to 3). Additional passwords
+can be provided using the connection config options - `password2` and `password3`. Again, for each
+authentication factor, multiple roundtrips of data exchange can be required by the plugin algoritm.
+
+```js
+const conn = mysql.createConnection({
+  user: 'test_user',
+  password: 'secret1',
+  password2: 'secret2',
+  password3: 'secret3',
+  database: 'test_database',
+  authPlugins: {
+    // password1 === password
+    'auth-plugin1': function ({password1}) {
+      return function (serverPluginData) {
+        return clientPluginData(password1, serverPluginData);
+      };
+    },
+    'auth-plugin2': function ({password2}) {
+      return function (serverPluginData) {
+        return clientPluginData(password2, serverPluginData);
+      };
+    },
+    'auth-plugin3': function ({password3}) {
+      return function (serverPluginData) {
+        return clientPluginData(password3, serverPluginData);
+      };
+    }
+  }
+});
+```
diff --git a/lib/commands/change_user.js b/lib/commands/change_user.js
@@ -1,7 +1,14 @@
+// This file was modified by Oracle on September 21, 2021.
+// The changes involve saving additional authentication factor passwords
+// in the command scope and enabling multi-factor authentication in the
+// client-side when the server supports it.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const Command = require('./command.js');
 const Packets = require('../packets/index.js');
+const ClientConstants = require('../constants/client');
 const ClientHandshake = require('./client_handshake.js');
 const CharsetToEncoding = require('../constants/charset_encodings.js');
 
@@ -11,10 +18,15 @@ class ChangeUser extends Command {
     this.onResult = callback;
     this.user = options.user;
     this.password = options.password;
+    // "password1" is an alias of "password"
+    this.password1 = options.password;
+    this.password2 = options.password2;
+    this.password3 = options.password3;
     this.database = options.database;
     this.passwordSha1 = options.passwordSha1;
     this.charsetNumber = options.charsetNumber;
     this.currentConfig = options.currentConfig;
+    this.authenticationFactor = 0;
   }
   start(packet, connection) {
     const newPacket = new Packets.ChangeUser({
@@ -35,6 +47,13 @@ class ChangeUser extends Command {
     // reset prepared statements cache as all statements become invalid after changeUser
     connection._statements.reset();
     connection.writePacket(newPacket.toPacket());
+    // check if the server supports multi-factor authentication
+    const multiFactorAuthentication = connection.serverCapabilityFlags & ClientConstants.MULTI_FACTOR_AUTHENTICATION;
+    if (multiFactorAuthentication) {
+      // if the server supports multi-factor authentication, we enable it in
+      // the client
+      this.authenticationFactor = 1;
+    }
     return ChangeUser.prototype.handshakeResult;
   }
 }
diff --git a/lib/commands/client_handshake.js b/lib/commands/client_handshake.js
@@ -3,6 +3,11 @@
 // emitted in the command instance itself.
 // Modifications copyright (c) 2021, Oracle and/or its affiliates.
 
+// This file was modified by Oracle on September 21, 2021.
+// Handshake workflow now supports additional authentication factors requested
+// by the server.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const Command = require('./command.js');
@@ -26,6 +31,7 @@ class ClientHandshake extends Command {
     super();
     this.handshake = null;
     this.clientFlags = clientFlags;
+    this.authenticationFactor = 0;
   }
 
   start() {
@@ -51,6 +57,14 @@ class ClientHandshake extends Command {
     }
     this.user = connection.config.user;
     this.password = connection.config.password;
+    // "password1" is an alias to the original "password" value
+    // to make it easier to integrate multi-factor authentication
+    this.password1 = connection.config.password;
+    // "password2" and "password3" are the 2nd and 3rd factor authentication
+    // passwords, which can be undefined depending on the authentication
+    // plugin being used
+    this.password2 = connection.config.password2;
+    this.password3 = connection.config.password3;
     this.passwordSha1 = connection.config.passwordSha1;
     this.database = connection.config.database;
     this.autPluginName = this.handshake.autPluginName;
@@ -109,6 +123,12 @@ class ClientHandshake extends Command {
     connection.connectionId = this.handshake.connectionId;
     const serverSSLSupport =
       this.handshake.capabilityFlags & ClientConstants.SSL;
+    // multi factor authentication is enabled with the
+    // "MULTI_FACTOR_AUTHENTICATION" capability and should only be used if it
+    // is supported by the server
+    const multiFactorAuthentication =
+      this.handshake.capabilityFlags & ClientConstants.MULTI_FACTOR_AUTHENTICATION;
+    this.clientFlags = this.clientFlags | multiFactorAuthentication;
     // use compression only if requested by client and supported by server
     connection.config.compress =
       connection.config.compress &&
@@ -141,17 +161,36 @@ class ClientHandshake extends Command {
     } else {
       this.sendCredentials(connection);
     }
+    if (multiFactorAuthentication) {
+      // if the server supports multi-factor authentication, we enable it in
+      // the client
+      this.authenticationFactor = 1;
+    }
     return ClientHandshake.prototype.handshakeResult;
   }
 
   handshakeResult(packet, connection) {
     const marker = packet.peekByte();
-    if (marker === 0xfe || marker === 1) {
+    // packet can be OK_Packet, ERR_Packet, AuthSwitchRequest, AuthNextFactor
+    // or AuthMoreData
+    if (marker === 0xfe || marker === 1 || marker === 0x02) {
       const authSwitch = require('./auth_switch');
       try {
         if (marker === 1) {
           authSwitch.authSwitchRequestMoreData(packet, connection, this);
         } else {
+          // if authenticationFactor === 0, it means the server does not support
+          // the multi-factor authentication capability
+          if (this.authenticationFactor !== 0) {
+            // if we are past the first authentication factor, we should use the
+            // corresponding password (if there is one)
+            connection.config.password = this[`password${this.authenticationFactor}`];
+            // update the current authentication factor
+            this.authenticationFactor += 1;
+          }
+          // if marker === 0x02, it means it is an AuthNextFactor packet,
+          // which is similar in structure to an AuthSwitchRequest packet,
+          // so, we can use it directly
           authSwitch.authSwitchRequest(packet, connection, this);
         }
         return ClientHandshake.prototype.handshakeResult;
diff --git a/lib/connection.js b/lib/connection.js
@@ -8,6 +8,11 @@
 // there is a fatal error.
 // Modifications copyright (c) 2021, Oracle and/or its affiliates.
 
+// This file was modified by Oracle on September 21, 2021.
+// The changes involve passing additional authentication factor passwords
+// to the ChangeUser Command instance.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const Net = require('net');
@@ -671,7 +676,12 @@ class Connection extends EventEmitter {
       new Commands.ChangeUser(
         {
           user: options.user || this.config.user,
-          password: options.password || this.config.password,
+          // for the purpose of multi-factor authentication, or not, the main
+          // password (used for the 1st authentication factor) can also be
+          // provided via the "password1" option
+          password: options.password || options.password1 || this.config.password || this.config.password1,
+          password2: options.password2 || this.config.password2,
+          password3: options.password3 || this.config.password3,
           passwordSha1: options.passwordSha1 || this.config.passwordSha1,
           database: options.database || this.config.database,
           timeout: options.timeout,
diff --git a/lib/connection_config.js b/lib/connection_config.js
@@ -1,3 +1,10 @@
+// This file was modified by Oracle on September 21, 2021.
+// New connection options for additional authentication factors were
+// introduced.
+// Multi-factor authentication capability is now enabled if one of these
+// options is used.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const { URL } = require('url');
@@ -30,6 +37,11 @@ const validOptions = {
   namedPlaceholders: 1,
   nestTables: 1,
   password: 1,
+  // with multi-factor authentication, the main password (used for the first
+  // authentication factor) can be provided via password1
+  password1: 1,
+  password2: 1,
+  password3: 1,
   passwordSha1: 1,
   pool: 1,
   port: 1,
@@ -81,7 +93,12 @@ class ConnectionConfig {
     this.localAddress = options.localAddress;
     this.socketPath = options.socketPath;
     this.user = options.user || undefined;
-    this.password = options.password || undefined;
+    // for the purpose of multi-factor authentication, or not, the main
+    // password (used for the 1st authentication factor) can also be
+    // provided via the "password1" option
+    this.password = options.password || options.password1 || undefined;
+    this.password2 = options.password2 || undefined;
+    this.password3 = options.password3 || undefined;
     this.passwordSha1 = options.passwordSha1 || undefined;
     this.database = options.database;
     this.connectTimeout = isNaN(options.connectTimeout)
diff --git a/lib/constants/client.js b/lib/constants/client.js
@@ -1,3 +1,9 @@
+// This file was modified by Oracle on September 21, 2021.
+// New capability for multi-factor authentication based on mandatory session
+// trackers, that are signaled with an extra single-byte prefix on new
+// versions of the MySQL server.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 // Manually extracted from mysql-5.5.23/include/mysql_com.h
@@ -29,3 +35,5 @@ exports.DEPRECATE_EOF = 0x01000000; /* Can send OK after a Text Resultset. */
 
 exports.SSL_VERIFY_SERVER_CERT = 0x40000000;
 exports.REMEMBER_OPTIONS = 0x80000000;
+
+exports.MULTI_FACTOR_AUTHENTICATION = 0x10000000; /* multi-factor authentication */
diff --git a/lib/packets/auth_next_factor.js b/lib/packets/auth_next_factor.js
@@ -0,0 +1,35 @@
+// Copyright (c) 2021, Oracle and/or its affiliates.
+
+'use strict';
+
+const Packet = require('../packets/packet');
+
+class AuthNextFactor {
+  constructor(opts) {
+    this.pluginName = opts.pluginName;
+    this.pluginData = opts.pluginData;
+  }
+
+  toPacket(encoding) {
+    const length = 6 + this.pluginName.length + this.pluginData.length;
+    const buffer = Buffer.allocUnsafe(length);
+    const packet = new Packet(0, buffer, 0, length);
+    packet.offset = 4;
+    packet.writeInt8(0x02);
+    packet.writeNullTerminatedString(this.pluginName, encoding);
+    packet.writeBuffer(this.pluginData);
+    return packet;
+  }
+
+  static fromPacket(packet, encoding) {
+    packet.readInt8(); // marker
+    const name = packet.readNullTerminatedString(encoding);
+    const data = packet.readBuffer();
+    return new AuthNextFactor({
+      pluginName: name,
+      pluginData: data
+    });
+  }
+}
+
+module.exports = AuthNextFactor;
diff --git a/lib/packets/index.js b/lib/packets/index.js
@@ -3,10 +3,15 @@
 // binary server packet.
 // Modifications copyright (c) 2021, Oracle and/or its affiliates.
 
+// This file was modified by Oracle on September 21, 2021.
+// The new AuthNextFactor packet is now available.
+// Modifications copyright (c) 2021, Oracle and/or its affiliates.
+
 'use strict';
 
 const process = require('process');
 
+const AuthNextFactor = require('./auth_next_factor');
 const AuthSwitchRequest = require('./auth_switch_request');
 const AuthSwitchRequestMoreData = require('./auth_switch_request_more_data');
 const AuthSwitchResponse = require('./auth_switch_response');
@@ -27,6 +32,7 @@ const SSLRequest = require('./ssl_request');
 const TextRow = require('./text_row');
 
 const ctorMap = {
+  AuthNextFactor,
   AuthSwitchRequest,
   AuthSwitchRequestMoreData,
   AuthSwitchResponse,
diff --git a/test/integration/connection/test-change-user-multi-factor.js b/test/integration/connection/test-change-user-multi-factor.js
diff --git a/test/integration/test-auth-switch-multi-factor.js b/test/integration/test-auth-switch-multi-factor.js
diff --git a/typings/mysql/lib/Connection.d.ts b/typings/mysql/lib/Connection.d.ts
