CSHARP-2160: Implement SASLPrep

Author: vincentkam

Release Notes/Release Notes v2.7.0.md

@@ -0,0 +1,22 @@
+# .NET Driver Version 2.7.0 Release Notes
+
+## Known Issues:
+* Incomplete SCRAM-SHA-256 Support in .NET Standard: In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII passwords because SaslPrep is not fully implemented due to the lack of a string normalization function in .NET Standard 1.6. Normalizing the password into Unicode Normalization Form KC beforehand MAY help. SCRAM-SHA-1 is the recommended alternative for now.
+
+An online version of these release notes is available at:
+
+https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v2.7.0.md
+
+The full list of JIRA issues that are currently scheduled to be resolved in this release is available at:
+
+https://jira.mongodb.org/issues/?jql=project%20%3D%20CSHARP%20AND%20fixVersion%20%3D%202.7.0%20ORDER%20BY%20key%20ASC
+
+The list may change as we approach the release date.
+
+Documentation on the .NET driver can be found at:
+
+http://mongodb.github.io/mongo-csharp-driver/
+
+Upgrading
+
+There are no known backwards breaking changes in this release.

THIRD-PARTY-NOTICES

@@ -12,7 +12,7 @@ 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
+1. The following files: CryptographyHelpers.cs, HashAlgorithmName.cs, Rfc2898DeriveBytes.cs
 
    Original work:
      Copyright (c) 2016–2017 .NET Foundation and Contributors
@@ -54,3 +54,35 @@ https://github.com/mongodb/mongo-csharp-driver.
      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.
+
+2. SaslPrepHelper.cs
+
+   Original work:                                                             
+     Copyright (c) 2017 Tom Bentley                                               
+                                                                              
+     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.                                           
+                                                                              
+   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/SaslPrepHelper.cs

@@ -33,6 +33,8 @@ namespace MongoDB.Driver.Core.Authentication
 {
     /// <summary>
     /// A SCRAM-SHA256 SASL authenticator.
+    /// In .NET Standard, this class does not normalize the password in the credentials, so non-ASCII
+    /// passwords may not work unless they are normalized into Unicode Normalization Form KC beforehand.
     /// </summary>
     public sealed class ScramSha256Authenticator : ScramShaAuthenticator
     {
@@ -48,6 +50,8 @@ public sealed class ScramSha256Authenticator : ScramShaAuthenticator
         // constructors
         /// <summary>
         /// Initializes a new instance of the <see cref="ScramSha256Authenticator"/> class.
+        /// In .NET Standard, this class does not normalize the password in <paramref name="credential"/>, so non-ASCII
+        /// passwords may not work unless they are normalized into Unicode Normalization Form KC beforehand.
         /// </summary>
         /// <param name="credential">The credential.</param>
         public ScramSha256Authenticator(UsernamePasswordCredential credential)
@@ -71,17 +75,17 @@ private static byte[] H256(byte[] data)
         private static byte[] Hi256(UsernamePasswordCredential credential, byte[] salt, int iterations)
         {
 #if NET45
-            var passwordIntPtr = Marshal.SecureStringToGlobalAllocUnicode(credential.Password);
+            var passwordIntPtr = Marshal.SecureStringToGlobalAllocUnicode(credential.SaslPreppedPassword);
 #else
-            var passwordIntPtr = SecureStringMarshal.SecureStringToGlobalAllocUnicode(credential.Password);
+            var passwordIntPtr = SecureStringMarshal.SecureStringToGlobalAllocUnicode(credential.SaslPreppedPassword);
 #endif
             try
             {
-                var passwordChars = new char[credential.Password.Length];
+                var passwordChars = new char[credential.SaslPreppedPassword.Length];
                 var passwordCharsHandle = GCHandle.Alloc(passwordChars, GCHandleType.Pinned);
                 try
                 {
-                    Marshal.Copy(passwordIntPtr, passwordChars, 0, credential.Password.Length);
+                    Marshal.Copy(passwordIntPtr, passwordChars, 0, credential.SaslPreppedPassword.Length);
                     return Hi256(passwordChars, salt, iterations);
                 }
                 finally

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

@@ -26,6 +26,7 @@ namespace MongoDB.Driver.Core.Authentication
     public sealed class UsernamePasswordCredential
     {
         // fields
+        private readonly Lazy<SecureString> _saslPreppedPassword;
         private string _source;
         private SecureString _password;
         private string _username;
@@ -40,10 +41,19 @@ public sealed class UsernamePasswordCredential
         public UsernamePasswordCredential(string source, string username, string password)
             : this(source, username, ConvertPasswordToSecureString(password))
         {
+            // Compute saslPreppedPassword immediately and store it securely while the password is already in
+            // managed memory. We don't create a closure over the password so that it will hopefully get 
+            // garbage-collected sooner rather than later.
+            var saslPreppedPassword = ConvertPasswordToSecureString(SaslPrepHelper.SaslPrepStored(password));
+            _saslPreppedPassword = new Lazy<SecureString>(() => saslPreppedPassword);
         }
 
         /// <summary>
         /// Initializes a new instance of the <see cref="UsernamePasswordCredential"/> class.
+        /// Less secure when used in conjunction with SCRAM-SHA-256, due to the need to store the password in a managed
+        /// string in order to SaslPrep it.
+        /// See <a href="https://github.com/mongodb/specifications/blob/master/source/auth/auth.rst#scram-sha-256">Driver Authentication: SCRAM-SHA-256</a>
+        /// for additional details.
         /// </summary>
         /// <param name="source">The source.</param>
         /// <param name="username">The username.</param>
@@ -53,6 +63,10 @@ public UsernamePasswordCredential(string source, string username, SecureString p
             _source = Ensure.IsNotNullOrEmpty(source, nameof(source));
             _username = Ensure.IsNotNullOrEmpty(username, nameof(username));
             _password = Ensure.IsNotNull(password, nameof(password));
+            // defer computing the saslPreppedPassword until we need to since this will leak the password into managed
+            // memory
+            _saslPreppedPassword = new Lazy<SecureString>(
+                () => ConvertPasswordToSecureString(SaslPrepHelper.SaslPrepStored(GetInsecurePassword())));
         }
 
         // properties
@@ -67,6 +81,17 @@ public SecureString Password
             get { return _password; }
         }
 
+        /// <summary>
+        /// Gets the the SASLprepped password.
+        /// May create a cleartext copy of the password in managed memory the first time it is accessed.
+        /// Use only as needed e.g. for SCRAM-SHA-256.
+        /// </summary> 
+        /// <returns>The SASLprepped password.</returns>
+        public SecureString SaslPreppedPassword
+        {
+            get { return _saslPreppedPassword.Value; }
+        }
+        
         /// <summary>
         /// Gets the source.
         /// </summary>

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

@@ -95,6 +95,7 @@
     <Compile Include="Core\Authentication\Sspi\SspiHandle.cs" />
     <Compile Include="Core\Authentication\Sspi\SspiPackage.cs" />
     <Compile Include="Core\Authentication\Sspi\Win32Exception.cs" />
+    <Compile Include="Core\Authentication\SaslPrepHelper.cs" />
     <Compile Include="Core\Authentication\Vendored\CryptographyHelpers.cs" />
     <Compile Include="Core\Authentication\Vendored\HashAlgorithmName.cs" />
     <Compile Include="Core\Authentication\Vendored\Rfc2898DeriveBytes.cs" />

src/MongoDB.Driver.Core/MongoDB.Driver.Core.csproj

@@ -67,6 +67,10 @@ public MongoClient()
 
         /// <summary>
         /// Initializes a new instance of the MongoClient class.
+        /// In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII passwords because SaslPrep is
+        /// not fully implemented due to the lack of a string normalization function in .NET Standard 1.6.
+        /// Normalizing the password into Unicode Normalization Form KC beforehand MAY help.
+        /// SCRAM-SHA-1 is the recommended alternative for now.
         /// </summary>
         /// <param name="settings">The settings.</param>
         public MongoClient(MongoClientSettings settings)
@@ -78,6 +82,10 @@ public MongoClient(MongoClientSettings settings)
 
         /// <summary>
         /// Initializes a new instance of the MongoClient class.
+        /// In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII passwords because SaslPrep is
+        /// not fully implemented due to the lack of a string normalization function in .NET Standard 1.6.
+        /// Normalizing the password into Unicode Normalization Form KC beforehand MAY help.
+        /// SCRAM-SHA-1 is the recommended alternative for now.
         /// </summary>
         /// <param name="url">The URL.</param>
         public MongoClient(MongoUrl url)
@@ -87,6 +95,10 @@ public MongoClient(MongoUrl url)
 
         /// <summary>
         /// Initializes a new instance of the MongoClient class.
+        /// In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII passwords because SaslPrep is
+        /// not fully implemented due to the lack of a string normalization function in .NET Standard 1.6.
+        /// Normalizing the password into Unicode Normalization Form KC beforehand MAY help.
+        /// SCRAM-SHA-1 is the recommended alternative for now.
         /// </summary>
         /// <param name="connectionString">The connection string.</param>
         public MongoClient(string connectionString)

src/MongoDB.Driver/MongoClient.cs

@@ -41,7 +41,11 @@ public class MongoCredential : IEquatable<MongoCredential>
         /// <summary>
         /// Initializes a new instance of the <see cref="MongoCredential" /> class.
         /// </summary>
-        /// <param name="mechanism">Mechanism to authenticate with.</param>
+        /// <param name="mechanism">Mechanism to authenticate with.
+        /// In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII passwords because SaslPrep is
+        /// not fully implemented due to the lack of a string normalization function in .NET Standard 1.6.
+        /// Normalizing the password into Unicode Normalization Form KC beforehand MAY help.
+        /// SCRAM-SHA-1 is the recommended alternative for now.</param>
         /// <param name="identity">The identity.</param>
         /// <param name="evidence">The evidence.</param>
         public MongoCredential(string mechanism, MongoIdentity identity, MongoIdentityEvidence evidence)
@@ -80,6 +84,10 @@ public MongoIdentity Identity
 
         /// <summary>
         /// Gets the mechanism to authenticate with.
+        /// In .NET Standard, authenticating via SCRAM-SHA-256 may not work with non-ASCII passwords because SaslPrep is
+        /// not fully implemented due to the lack of a string normalization function in .NET Standard 1.6.
+        /// Normalizing the password into Unicode Normalization Form KC beforehand MAY help.
+        /// SCRAM-SHA-1 is the recommended alternative for now.
         /// </summary>
         public string Mechanism
         {

src/MongoDB.Driver/MongoCredential.cs

@@ -36,6 +36,10 @@ public sealed class PasswordEvidence : MongoIdentityEvidence
         // constructors
         /// <summary>
         /// Initializes a new instance of the <see cref="PasswordEvidence" /> class.
+        /// Less secure when used in conjunction with SCRAM-SHA-256, due to the need to store the password in a managed
+        /// string in order to SaslPrep it.
+        /// See <a href="https://github.com/mongodb/specifications/blob/master/source/auth/auth.rst#scram-sha-256">Driver Authentication: SCRAM-SHA-256</a>
+        /// for additional details.
         /// </summary>
         /// <param name="password">The password.</param>
         public PasswordEvidence(SecureString password)

src/MongoDB.Driver/PasswordEvidence.cs

@@ -32,6 +32,12 @@ public static object GetPropertyValue(object obj, string name, BindingFlags flag
             var propertyInfo = obj.GetType().GetProperty(name, flags);
             return propertyInfo.GetValue(obj);
         }
+        
+        public static object GetStaticFieldValue(Type type, string name, BindingFlags flags = BindingFlags.NonPublic | BindingFlags.Static)
+        {
+            var fieldInfo = GetDeclaredOrInheritedField(type, name, flags);
+            return fieldInfo.GetValue(null);
+        }
 
         public static object Invoke(object obj, string name, BindingFlags flags = BindingFlags.NonPublic | BindingFlags.Instance)
         {
@@ -63,6 +69,23 @@ public static object Invoke<T1>(object obj, string name, T1 arg1)
                 throw exception.InnerException;
             }
         }
+        
+        public static object InvokeStatic(Type type, string name, BindingFlags flags = BindingFlags.NonPublic | BindingFlags.Static)
+        {
+            var methodInfo = type.GetMethods(flags)
+                .Where(m => m.Name == name && m.GetParameters().Length == 0)
+                .Single();
+            return methodInfo.Invoke(null, new object[] { });
+        }
+
+        public static object InvokeStatic<T1>(Type type, string name, T1 arg1)
+        {
+            var parameterTypes = new[] { typeof(T1) };
+            var methodInfo = type.GetMethods(BindingFlags.NonPublic | BindingFlags.Static)
+                .Where(m => m.Name == name && m.GetParameters().Select(p => p.ParameterType).SequenceEqual(parameterTypes))
+                .Single();
+            return methodInfo.Invoke(null, new object[] { arg1 });
+        }
 
         public static void SetFieldValue(object obj, string name, object value, BindingFlags flags = BindingFlags.NonPublic | BindingFlags.Instance)
         {