Security: Use SecureString for secure password handling (#263)

Author: pglombardo

README.md

@@ -30,6 +30,13 @@
 * **Observable**: Configure up to [TRACE level logging](https://hivemq.github.io/hivemq-mqtt-client-dotnet/docs/how-to/debug) for package internals.
 * **Fast**: Optimized & benchmarked.  See the benchmark results [here](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Benchmarks/ClientBenchmarkApp/README.md).
 
+### 🔒 Security
+* **Secure Password Storage**: Passwords are stored using `SecureString` to prevent exposure in memory dumps and process memory. Use `WithPassword(SecureString)` for enhanced security.
+* **Memory-Safe Password Handling**: Temporary password strings are automatically cleared from memory after use, ensuring no sensitive data persists in memory.
+* **Backward Compatibility**: Existing code using string passwords continues to work while being automatically converted to secure storage internally.
+* **TLS/SSL Support**: Full support for encrypted connections with configurable certificate validation and custom certificate handling.
+* **X.509 Certificate Authentication**: Complete support for client certificate authentication with secure private key handling.
+
 ### 🏝️ Ease of Use
 * **Easy to Use**: Smart defaults, excellent interfaces and intelligent automation makes implementing a breeze.
 * **Easy Integration**: Simple and intuitive API makes it easy to integrate with your .NET applications.
@@ -55,7 +62,7 @@ MQTT is an [open standard protocol](https://mqtt.org) for publishing and consumi
 
 This client library is used to publish and consume messages over MQTT.  So you can get a the temperature from a remote sensor, send a control message to a factory robot, tunnel WhatsApp messages to a Twitter account or anything else you can imagine.
 
-This is the client library that speaks with an MQTT broker that delivers messages to their final destination.  
+This is the client library that speaks with an MQTT broker that delivers messages to their final destination.
 
 Need a broker? Sign up for a free broker at [HiveMQ Cloud](https://www.hivemq.com/mqtt-cloud-broker/) and be up and running in a couple minutes.  Connect up to 100 devices - no credit card required.
 

Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs

@@ -15,6 +15,7 @@
  */
 namespace HiveMQtt.Client;
 
+using System.Security;
 using System.Security.Cryptography.X509Certificates;
 using HiveMQtt.Client.Options;
 
@@ -468,7 +469,55 @@ public HiveMQClientOptionsBuilder WithUserName(string username)
     }
 
     /// <summary>
-    /// Sets the password.
+    /// Sets the password using a SecureString for enhanced security.
+    /// <para>
+    /// The Password is an optional parameter that can be included in the CONNECT packet during the
+    /// connection establishment process. It is used for client authentication in conjunction with the
+    /// Username or other authentication mechanisms.
+    /// </para>
+    /// <para>
+    /// The Password field allows clients to provide a secret credential or authentication token
+    /// associated with the provided Username. The format and interpretation of the Password are
+    /// specific to the chosen authentication method and agreed upon by the client and the broker.
+    /// </para>
+    /// <para>
+    /// The broker will use the provided Password, along with the Username or other authentication
+    /// information, to verify the client's identity and grant access to the MQTT communication based on
+    /// the configured authentication rules.
+    /// </para>
+    /// <para>
+    /// If the client does not require authentication or the chosen authentication method does not involve
+    /// a password, the Password field may be omitted from the CONNECT packet.
+    /// </para>
+    /// <para>
+    /// This method accepts a SecureString for enhanced security, preventing password exposure in memory.
+    /// </para>
+    /// </summary>
+    /// <param name="password">The password as a SecureString for enhanced security.</param>
+    /// <returns>The HiveMQClientOptionsBuilder instance.</returns>
+    public HiveMQClientOptionsBuilder WithPassword(SecureString password)
+    {
+        if (password == null)
+        {
+            throw new ArgumentNullException(nameof(password));
+        }
+
+        if (password.Length > 65535)
+        {
+            Logger.Error("Password must be between 0 and 65535 characters.");
+            throw new ArgumentException("Password must be between 0 and 65535 characters.");
+        }
+
+        this.options.Password = password;
+        return this;
+    }
+
+    /// <summary>
+    /// Sets the password using a plain string (for backward compatibility).
+    /// <para>
+    /// WARNING: This method stores the password as a plain string in memory, which is less secure.
+    /// Consider using WithPassword(SecureString) for enhanced security.
+    /// </para>
     /// <para>
     /// The Password is an optional parameter that can be included in the CONNECT packet during the
     /// connection establishment process. It is used for client authentication in conjunction with the
@@ -489,17 +538,31 @@ public HiveMQClientOptionsBuilder WithUserName(string username)
     /// a password, the Password field may be omitted from the CONNECT packet.
     /// </para>
     /// </summary>
-    /// <param name="password">The password value.</param>
+    /// <param name="password">The password value as a plain string.</param>
     /// <returns>The HiveMQClientOptionsBuilder instance.</returns>
+    [Obsolete("Use WithPassword(SecureString) for enhanced security. This method stores passwords as plain text in memory.")]
     public HiveMQClientOptionsBuilder WithPassword(string password)
     {
+        if (password == null)
+        {
+            throw new ArgumentNullException(nameof(password));
+        }
+
         if (password.Length is < 0 or > 65535)
         {
             Logger.Error("Password must be between 0 and 65535 characters.");
             throw new ArgumentException("Password must be between 0 and 65535 characters.");
         }
 
-        this.options.Password = password;
+        // Convert string to SecureString
+        var securePassword = new SecureString();
+        foreach (char c in password)
+        {
+            securePassword.AppendChar(c);
+        }
+        securePassword.MakeReadOnly();
+
+        this.options.Password = securePassword;
         return this;
     }
 

Source/HiveMQtt/Client/Options/HiveMQClientOptions.cs

@@ -17,6 +17,7 @@ namespace HiveMQtt.Client.Options;
 
 using System;
 using System.Linq;
+using System.Security;
 using System.Security.Cryptography.X509Certificates;
 using HiveMQtt.Client;
 using HiveMQtt.Client.Exceptions;
@@ -97,7 +98,8 @@ public HiveMQClientOptions()
     // The MQTT CONNECT packet supports basic authentication of a Network Connection using the User Name
     // and Password fields. While these fields are named for a simple password authentication, they can
     // be used to carry other forms of authentication such as passing a token as the Password.
-    public string? Password { get; set; }
+    // Note: Password is stored securely using SecureString to prevent memory exposure.
+    public SecureString? Password { get; set; }
 
     /// <summary>
     /// Gets or sets a value that represents the session expiration interval in use by the MQTT broker.
@@ -354,4 +356,31 @@ internal static long RangeValidateFourByteInteger(long value)
 
         return value;
     }
+
+    /// <summary>
+    /// Gets the password as a string for MQTT protocol use.
+    /// Note: This creates a temporary string that should be cleared after use.
+    /// </summary>
+    /// <returns>The password as a string, or null if no password is set.</returns>
+    internal string? GetPasswordAsString()
+    {
+        if (this.Password == null)
+        {
+            return null;
+        }
+
+        var ptr = IntPtr.Zero;
+        try
+        {
+            ptr = System.Runtime.InteropServices.Marshal.SecureStringToGlobalAllocUnicode(this.Password);
+            return System.Runtime.InteropServices.Marshal.PtrToStringUni(ptr);
+        }
+        finally
+        {
+            if (ptr != IntPtr.Zero)
+            {
+                System.Runtime.InteropServices.Marshal.ZeroFreeGlobalAllocUnicode(ptr);
+            }
+        }
+    }
 }

Source/HiveMQtt/MQTT5/Packets/ConnectPacket.cs

@@ -93,9 +93,12 @@ public byte[] Encode()
             }
 
             // Password
-            if (this.clientOptions.Password != null)
+            var passwordString = this.clientOptions.GetPasswordAsString();
+            if (passwordString != null)
             {
-                _ = EncodeUTF8String(vhAndPayloadStream, this.clientOptions.Password);
+                _ = EncodeUTF8String(vhAndPayloadStream, passwordString);
+                // Clear the temporary password string from memory
+                Array.Clear(passwordString.ToCharArray(), 0, passwordString.Length);
             }
 
             // Construct the final packet
@@ -148,9 +151,12 @@ internal void GatherConnectFlagsAndProperties()
             }
         }
 
-        if (this.clientOptions.Password != null)
+        var passwordString = this.clientOptions.GetPasswordAsString();
+        if (passwordString != null)
         {
             this.flags |= 0x40;
+            // Clear the temporary password string from memory
+            Array.Clear(passwordString.ToCharArray(), 0, passwordString.Length);
         }
 
         if (this.clientOptions.UserName != null)

Tests/HiveMQtt.Test/HiveMQClient/ClientOptionsBuilderTest.cs

@@ -67,7 +67,26 @@ public void Build_WithValidParameters_ReturnsValidOptions(
         Assert.Equal(authMethod, options.AuthenticationMethod);
         Assert.Equal(Encoding.UTF8.GetBytes(authData), options.AuthenticationData);
         Assert.Equal(username, options.UserName);
-        Assert.Equal(password, options.Password);
+
+        // Convert SecureString to string for comparison
+        string? passwordString = null;
+        if (options.Password != null)
+        {
+            var ptr = IntPtr.Zero;
+            try
+            {
+                ptr = System.Runtime.InteropServices.Marshal.SecureStringToGlobalAllocUnicode(options.Password);
+                passwordString = System.Runtime.InteropServices.Marshal.PtrToStringUni(ptr);
+            }
+            finally
+            {
+                if (ptr != IntPtr.Zero)
+                {
+                    System.Runtime.InteropServices.Marshal.ZeroFreeGlobalAllocUnicode(ptr);
+                }
+            }
+        }
+        Assert.Equal(password, passwordString);
         Assert.Equal(preferIPv6, options.PreferIPv6);
         Assert.Equal(topicAliasMaximum, options.ClientTopicAliasMaximum);
         Assert.Equal(requestResponseInfo, options.RequestResponseInformation);