CSHARP-2171: SCRAM-SHA-256 Support

Author: vincentkam

THIRD-PARTY-NOTICES

@@ -0,0 +1,56 @@
+The MongoDB .NET Driver uses third-party libraries or other resources that may
+be distributed under licenses different than the MongoDB .NET Driver software.
+
+In the event that we accidentally failed to list a required notice,
+please bring it to our attention through any of the ways detailed here:
+
+           [email protected]
+
+The attached notices are provided for information only.
+
+For any licenses that require disclosure of source, sources are available at
+https://github.com/mongodb/mongo-csharp-driver.
+
+
+1) The following files: CryptographyHelpers.cs, HashAlgorithmName.cs, Rfc2898DeriveBytes.cs
+
+   Original work:
+     Copyright (c) 2016–2017 .NET Foundation and Contributors
+     The MIT License (MIT)
+     
+     Copyright (c) .NET Foundation and Contributors
+     
+     All rights reserved.
+     
+     Permission is hereby granted, free of charge, to any person obtaining a copy
+     of this software and associated documentation files (the "Software"), to deal
+     in the Software without restriction, including without limitation the rights
+     to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+     copies of the Software, and to permit persons to whom the Software is
+     furnished to do so, subject to the following conditions:
+     
+     The above copyright notice and this permission notice shall be included in all
+     copies or substantial portions of the Software.
+     
+     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+     LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+     OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+     SOFTWARE.
+    
+   Modified work:
+     Copyright (c) 2018–present MongoDB Inc.
+  
+     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
+     
+     http://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.

src/MongoDB.Driver.Core/Core/Authentication/DefaultAuthenticator.cs

@@ -14,15 +14,21 @@
 */
 
 using System;
+using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
+using MongoDB.Bson;
 using MongoDB.Driver.Core.Connections;
 using MongoDB.Driver.Core.Misc;
 
 namespace MongoDB.Driver.Core.Authentication
 {
     /// <summary>
-    /// The default authenticator (uses SCRAM-SHA1 if possible, falls back to MONGODB-CR otherwise).
+    /// The default authenticator.
+    /// If saslSupportedMechs is not present in the isMaster results for mechanism negotiation
+    /// uses SCRAM-SHA-1 when talking to servers >= 3.0. Prior to server 3.0, uses MONGODB-CR.
+    /// Else, uses SCRAM-SHA-256 if present in the list of mechanisms. Otherwise, uses 
+    /// SCRAM-SHA-1 the default, regardless of whether SCRAM-SHA-1 is in the list.
     /// </summary>
     public class DefaultAuthenticator : IAuthenticator
     {
@@ -48,10 +54,7 @@ internal DefaultAuthenticator(UsernamePasswordCredential credential, IRandomStri
 
         // properties
         /// <inheritdoc/>
-        public string Name
-        {
-            get { return "DEFAULT"; }
-        }
+        public string Name => "DEFAULT";
 
         // methods
         /// <inheritdoc/>
@@ -60,30 +63,83 @@ public void Authenticate(IConnection connection, ConnectionDescription descripti
             Ensure.IsNotNull(connection, nameof(connection));
             Ensure.IsNotNull(description, nameof(description));
 
-            var authenticator = CreateAuthenticator(description);
+            // If we don't have SaslSupportedMechs as part of the response, that means we didn't piggyback the initial
+            // isMaster request and should query the server (provided that the server >= 4.0), merging results into 
+            // a new ConnectionDescription
+            if (!description.IsMasterResult.HasSaslSupportedMechs 
+                && Feature.ScramSha256Authentication.IsSupported(description.ServerVersion))
+            {
+                var command = CustomizeInitialIsMasterCommand(IsMasterHelper.CreateCommand());
+                var isMasterProtocol = IsMasterHelper.CreateProtocol(command);
+                var isMasterResult = IsMasterHelper.GetResult(connection, isMasterProtocol, cancellationToken);
+                var mergedIsMasterResult = new IsMasterResult(description.IsMasterResult.Wrapped.Merge(isMasterResult.Wrapped));
+                description = new ConnectionDescription(
+                    description.ConnectionId, 
+                    mergedIsMasterResult, 
+                    description.BuildInfoResult);
+            }
+
+            var authenticator = CreateAuthenticator(connection, description);
             authenticator.Authenticate(connection, description, cancellationToken);
+            
         }
 
         /// <inheritdoc/>
-        public Task AuthenticateAsync(IConnection connection, ConnectionDescription description, CancellationToken cancellationToken)
+        public async Task AuthenticateAsync(IConnection connection, ConnectionDescription description, CancellationToken cancellationToken)
         {
             Ensure.IsNotNull(connection, nameof(connection));
             Ensure.IsNotNull(description, nameof(description));
+            
+            // If we don't have SaslSupportedMechs as part of the response, that means we didn't piggyback the initial
+            // isMaster request and should query the server (provided that the server >= 4.0), merging results into 
+            // a new ConnectionDescription
+            if (!description.IsMasterResult.HasSaslSupportedMechs 
+                && Feature.ScramSha256Authentication.IsSupported(description.ServerVersion))
+            {
+                var command = CustomizeInitialIsMasterCommand(IsMasterHelper.CreateCommand());
+                var isMasterProtocol = IsMasterHelper.CreateProtocol(command);
+                var isMasterResult = await IsMasterHelper.GetResultAsync(connection, isMasterProtocol, cancellationToken).ConfigureAwait(false);
+                var mergedIsMasterResult = new IsMasterResult(description.IsMasterResult.Wrapped.Merge(isMasterResult.Wrapped));
+                description = new ConnectionDescription(
+                    description.ConnectionId, 
+                    mergedIsMasterResult, 
+                    description.BuildInfoResult);
+            }  
+            
+            var authenticator = CreateAuthenticator(connection, description);
+            await authenticator.AuthenticateAsync(connection, description, cancellationToken).ConfigureAwait(false);
+        }
 
-            var authenticator = CreateAuthenticator(description);
-            return authenticator.AuthenticateAsync(connection, description, cancellationToken);
+
+        /// <inheritdoc/>
+        public BsonDocument CustomizeInitialIsMasterCommand(BsonDocument isMasterCommand)
+        {
+            return isMasterCommand.Merge(CreateSaslSupportedMechsRequest(_credential.Source, _credential.Username)); 
         }
 
-        private IAuthenticator CreateAuthenticator(ConnectionDescription description)
+        private static BsonDocument CreateSaslSupportedMechsRequest(string authenticationDatabaseName, string userName)
         {
-            if (Feature.ScramSha1Authentication.IsSupported(description.ServerVersion))
-            {
-                return new ScramSha1Authenticator(_credential, _randomStringGenerator);
-            }
-            else
+            return new BsonDocument {{"saslSupportedMechs", $"{authenticationDatabaseName}.{userName}"}};
+        }
+
+        // see https://github.com/mongodb/specifications/blob/master/source/auth/auth.rst#defaults
+        private IAuthenticator CreateAuthenticator(IConnection connection, ConnectionDescription description)
+        {            
+            // If a saslSupportedMechs field was present in the isMaster results for mechanism negotiation,
+            // then it MUST be inspected to select a default mechanism.
+            if (description.IsMasterResult.HasSaslSupportedMechs)
             {
-                return new MongoDBCRAuthenticator(_credential);
+                // If SCRAM-SHA-256 is present in the list of mechanisms, then it MUST be used as the default;
+                // otherwise, SCRAM-SHA-1 MUST be used as the default, regardless of whether SCRAM-SHA-1 is in the list.
+                return description.IsMasterResult.SaslSupportedMechs.Contains("SCRAM-SHA-256")
+                    ? (IAuthenticator) new ScramSha256Authenticator(_credential, _randomStringGenerator)
+                    :  new ScramSha1Authenticator(_credential, _randomStringGenerator);
             }
+             // If saslSupportedMechs is not present in the isMaster results for mechanism negotiation, then SCRAM-SHA-1
+             // MUST be used when talking to servers >= 3.0. Prior to server 3.0, MONGODB-CR MUST be used.
+            return Feature.ScramSha1Authentication.IsSupported(description.ServerVersion)
+                    ? (IAuthenticator) new ScramSha1Authenticator(_credential, _randomStringGenerator)
+                    : new MongoDBCRAuthenticator(_credential);
         }
     }
 }

src/MongoDB.Driver.Core/Core/Authentication/IAuthenticator.cs

@@ -16,6 +16,7 @@
 using System;
 using System.Threading;
 using System.Threading.Tasks;
+using MongoDB.Bson;
 using MongoDB.Driver.Core.Connections;
 
 namespace MongoDB.Driver.Core.Authentication
@@ -49,5 +50,12 @@ public interface IAuthenticator
         /// <param name="cancellationToken">The cancellation token.</param>
         /// <returns>A Task.</returns>
         Task AuthenticateAsync(IConnection connection, ConnectionDescription description, CancellationToken cancellationToken);
+        
+        /// <summary>
+        /// Optionally customizes isMaster command.
+        /// </summary>
+        /// <param name="isMasterCommand">Initial isMaster command.</param>
+        /// <returns>Optionally mutated isMaster command.</returns>
+        BsonDocument CustomizeInitialIsMasterCommand(BsonDocument isMasterCommand);
     }
 }

src/MongoDB.Driver.Core/Core/Authentication/MongoDBCRAuthenticator.cs

@@ -104,6 +104,12 @@ public async Task AuthenticateAsync(IConnection connection, ConnectionDescriptio
             }
         }
 
+        /// <inheritdoc/>
+        public BsonDocument CustomizeInitialIsMasterCommand(BsonDocument isMasterCommand)
+        {
+            return isMasterCommand;
+        }
+
         // private methods
         private CommandWireProtocol<BsonDocument> CreateAuthenticateProtocol(BsonDocument getNonceReply)
         {

src/MongoDB.Driver.Core/Core/Authentication/MongoDBX509Authenticator.cs

@@ -98,6 +98,12 @@ public async Task AuthenticateAsync(IConnection connection, ConnectionDescriptio
             }
         }
 
+        /// <inheritdoc/>
+        public BsonDocument CustomizeInitialIsMasterCommand(BsonDocument isMasterCommand)
+        {
+            return isMasterCommand; 
+        }
+
         // private methods
         private CommandWireProtocol<BsonDocument> CreateAuthenticateProtocol()
         {

src/MongoDB.Driver.Core/Core/Authentication/SaslAuthenticator.cs

@@ -129,6 +129,12 @@ public async Task AuthenticateAsync(IConnection connection, ConnectionDescriptio
             }
         }
 
+        /// <inheritdoc/>
+        public BsonDocument CustomizeInitialIsMasterCommand(BsonDocument isMasterCommand)
+        {
+            return isMasterCommand; 
+        }
+
         private CommandWireProtocol<BsonDocument> CreateCommandProtocol(BsonDocument command)
         {
             return new CommandWireProtocol<BsonDocument>(

src/MongoDB.Driver.Core/Core/Authentication/SaslMapParser.cs

@@ -0,0 +1,88 @@
+/* Copyright 2018–present MongoDB Inc.
+*
+* 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
+*
+* http://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.
+*/
+
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+
+namespace MongoDB.Driver.Core.Authentication
+{
+    /// <summary>
+    /// Per RFC5802: https://tools.ietf.org/html/rfc5802
+    /// "SCRAM is a SASL mechanism whose client response and server challenge
+    /// messages are text-based messages containing one or more attribute-
+    /// value pairs separated by commas. Each attribute has a one-letter
+    /// name."  
+    /// </summary>
+    internal static class SaslMapParser
+    {
+        private const int EOF = -1;
+
+        public static IDictionary<char, string> Parse(string text)
+        {
+            IDictionary<char, string> dict = new Dictionary<char, string>();
+
+            using (var reader = new StringReader(text))
+            {
+                while (reader.Peek() != EOF)
+                {
+                    dict.Add(ReadKeyValue(reader));
+                    if (reader.Peek() == ',')
+                    {
+                        Read(reader, ',');
+                    }
+                }
+            }
+
+            return dict;
+        }
+
+        private static KeyValuePair<char, string> ReadKeyValue(TextReader reader)
+        {
+            var key = ReadKey(reader);
+            Read(reader, '=');
+            var value = ReadValue(reader);
+            return new KeyValuePair<char, string>(key, value);
+        }
+
+        private static char ReadKey(TextReader reader)
+        {
+            // keys are of length 1.
+            return (char)reader.Read();
+        }
+
+        private static void Read(TextReader reader, char expected)
+        {
+            var ch = (char)reader.Read();
+            if (ch != expected)
+            {
+                throw new IOException(string.Format("Expected {0} but found {1}.", expected, ch));
+            }
+        }
+
+        private static string ReadValue(TextReader reader)
+        {
+            var sb = new StringBuilder();
+            var ch = reader.Peek();
+            while (ch != ',' && ch != EOF)
+            {
+                sb.Append((char)reader.Read());
+                ch = reader.Peek();
+            }
+
+            return sb.ToString();
+        }
+    }
+}