Documentation: Add Security Best Practices Page (#308)

Author: pglombardo

Documentation/docs/connecting.md

@@ -74,6 +74,7 @@ var connectResult = await client.ConnectAsync().ConfigureAwait(false);
 
 ## See Also
 
+* [Security Best Practices](/docs/security) - Comprehensive security guide
 * [HiveMQClientOptionsBuilder Reference](/docs/reference/client_options_builder)
 * [Automatic Reconnect](/docs/reference/automatic_reconnect)
 * [How to Set a Last Will & Testament](/docs/how-to/set-lwt)

Documentation/docs/how-to/client-certificates.md

@@ -33,11 +33,36 @@ var options = new HiveMQClientOptionsBuilder()
 var client = new HiveMQClient(options);
 ```
 
-## Using Certificates with a Passwords
+## Using Certificates with Passwords
 
-If your certificate and protected with a password, you can either instantiate the
-`X509Certificate2` object manually and pass it to the HiveMQtt client with
-`WithClientCertificate`:
+If your certificate is protected with a password, you can use `SecureString` for enhanced security (recommended), or pass the password directly.
+
+### Using SecureString (Recommended)
+
+For enhanced security, use `SecureString` to prevent password exposure in memory:
+
+```csharp
+using System.Security;
+using HiveMQtt.Client;
+
+// Create SecureString for the certificate password
+var certPassword = new SecureString();
+foreach (char c in GetPasswordFromSecureSource())
+{
+    certPassword.AppendChar(c);
+}
+certPassword.MakeReadOnly();
+
+var options = new HiveMQClientOptionsBuilder()
+    .WithClientCertificate("path/to/certificate-with-password.pfx", certPassword)
+    .Build();
+
+var client = new HiveMQClient(options);
+```
+
+### Using X509Certificate2 Directly
+
+You can also instantiate the `X509Certificate2` object manually:
 
 ```csharp
 using HiveMQtt.Client;
@@ -54,12 +79,16 @@ var options = new HiveMQClientOptionsBuilder()
 var client = new HiveMQClient(options);
 ```
 
-...or alternatively, just pass the string path to the certificate with the password:
+### Using String Password (Deprecated)
+
+:::warning
+The string password overload is deprecated. Use `SecureString` for enhanced security.
+:::
 
 ```csharp
 using HiveMQtt.Client;
-using System.Security.Cryptography.X509Certificates;
 
+// ⚠️ This generates a deprecation warning - use SecureString instead
 var options = new HiveMQClientOptionsBuilder()
     .WithClientCertificate(
         "path/to/certificate-with-password.pem",
@@ -198,6 +227,7 @@ TLS negotiation with client certificates is based on the `X509Certificate2` clas
 
 ## See Also
 
+* [Security Best Practices](/docs/security) - Comprehensive security guide including SecureString usage
 * [X509 Client Certificate Authentication - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-x509-client-certificate-authentication/)
 * [TLS/SSL - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-tls-ssl/)
 * [HiveMQClientOptionsBuilder.cs](https://github.com/hivemq/hivemq-mqtt-client-dotnet/blob/main/Source/HiveMQtt/Client/HiveMQClientOptionsBuilder.cs)

Documentation/docs/how-to/connect-with-auth.md

@@ -35,6 +35,10 @@ if (connectResult.ReasonCode == ConnAckReasonCode.Success)
 Never hardcode credentials in your source code. Use environment variables, configuration files, or a secrets manager.
 :::
 
+:::tip SecureString Support
+For enhanced security, use `SecureString` to prevent password exposure in memory. See the [Security Best Practices](/docs/security#securestring-for-credentials) guide for details.
+:::
+
 ### Using Environment Variables
 
 ```csharp
@@ -95,6 +99,7 @@ switch (connectResult.ReasonCode)
 
 ## See Also
 
+- [Security Best Practices](/docs/security) - Comprehensive security guide including SecureString usage
 - [Authentication with Username and Password - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-authentication-username-password/)
 - [Advanced Authentication Mechanisms - MQTT Security Fundamentals](https://www.hivemq.com/blog/mqtt-security-fundamentals-advanced-authentication-mechanisms/)
 - [HiveMQ Cloud - Authentication and Authorization](https://docs.hivemq.com/hivemq-cloud/authn-authz.html)

Documentation/docs/intro.md

@@ -39,8 +39,10 @@ Then check out the [Quickstart Guide](/docs/quickstart) to begin.
 
 ### Security
 - **TLS/SSL Encryption**: Secure connections out of the box
+- **SecureString Support**: [Secure credential handling](/docs/security#securestring-for-credentials) to prevent password exposure in memory
 - **X.509 Client Certificates**: [Full support](/docs/how-to/client-certificates) for certificate-based authentication
 - **Username/Password Auth**: Simple credential-based authentication
+- **[Security Best Practices](/docs/security)**: Comprehensive guide for secure implementations
 
 ### Developer Experience
 - **Extensive Event System**: [Hook into all operations](/docs/events) from connection to packet level