Use explicit hostname in DotNetty certificate validator (#8465)

* Clarify DotNetty hostname validation direction

* Use explicit hostname in certificate validator

Author: Aaronontheweb

docs/articles/remoting/security.md

@@ -125,10 +125,10 @@ When `suppress-validation = true`:
 
 ### Validation Strategies: HOCON vs Programmatic (v1.5.52+)
 
-Two independent validation decisions determine your TLS security posture:
+Three independent validation decisions determine your TLS security posture:
 
 1. **Chain Validation** - Verify certificate against trusted CAs (`suppress-validation`)
-2. **Hostname Validation** - Verify certificate CN/SAN matches target (`validate-certificate-hostname`)
+2. **Hostname Validation** - Verify an outbound server certificate CN/SAN matches the connection target (`validate-certificate-hostname`)
 3. **Mutual Authentication** - Require both sides authenticate (`require-mutual-authentication`)
 
 #### Decision Matrix: Which Combination to Use
@@ -151,10 +151,12 @@ When `validate-certificate-hostname = false` (the default):
 
 When `validate-certificate-hostname = true`:
 
-* Certificate CN (Common Name) or SAN (Subject Alternative Name) must match the target hostname
+* The outbound server certificate CN (Common Name) or SAN (Subject Alternative Name) must match the target hostname
 * Traditional TLS hostname validation as used in HTTPS
 * **Best for:** Client-server architectures with shared certificates and stable DNS names
 
+Hostname validation is an outbound server-identity check: the connecting node knows the hostname it intends to reach. The receiving node does not have an independently known hostname for an inbound client, so this setting does not infer one from the client's IP address or certificate. Use a `DotNettySslSetup` custom validator when inbound clients must satisfy application-specific identity or authorization rules such as certificate pinning, subject/issuer checks, or an explicit expected identity.
+
 **HOCON Example - P2P Cluster (Common Default):**
 
 ```hocon
@@ -370,7 +372,7 @@ Perform standard chain validation, then apply custom business logic:
 
 #### Hostname Validation
 
-Enable traditional TLS hostname validation (certificate CN/SAN must match target hostname). Use for client-server architectures with shared certificates:
+Enable traditional outbound TLS hostname validation (the server certificate CN/SAN must match the connection target). Use for client-server architectures with stable DNS names:
 
 [!code-csharp[HostnameValidationExample](../../../src/core/Akka.Docs.Tests/Configuration/TlsConfigurationSample.cs?name=HostnameValidationExample)]
 
@@ -385,7 +387,7 @@ Accept only certificates with specific subject names:
 | Method | Purpose |
 |--------|---------|
 | `ValidateChain()` | CA chain validation with full error details |
-| `ValidateHostname()` | Traditional TLS hostname validation (CN/SAN matching) |
+| `ValidateHostname()` | Uses the outbound `SslStream` result, or performs a direct CN/SAN comparison when an expected hostname is supplied |
 | `PinnedCertificate()` | Certificate pinning by thumbprint whitelist |
 | `ValidateSubject()` | Subject DN pattern matching (e.g., CN, O, OU) |
 | `ValidateIssuer()` | Issuer DN pattern matching |

src/core/Akka.Docs.Tests/Configuration/TlsConfigurationSample.cs

@@ -179,19 +179,19 @@ public static void CustomValidationLogicSetup()
 
         #region HostnameValidationExample
         /// <summary>
-        /// Example of enabling traditional hostname validation for client-server architectures.
+        /// Example of enabling traditional outbound hostname validation for client-server architectures.
         /// Use when all nodes share the same certificate with matching CN/SAN.
         /// </summary>
         public static void HostnameValidationSetup()
         {
             var certificate = LoadCertificate("path/to/certificate.pfx", "password");
 
-            // Enable both chain validation and hostname validation
+            // Enable both chain validation and outbound server hostname validation
             var sslSetup = new DotNettySslSetup(
                 certificate: certificate,
                 suppressValidation: false,
                 requireMutualAuthentication: true,
-                validateCertificateHostname: true  // Enable traditional TLS hostname validation
+                validateCertificateHostname: true  // Validate the outbound server certificate against the target hostname
             );
         }
         #endregion
@@ -221,4 +221,4 @@ public static void SubjectValidationSetup()
         }
         #endregion
     }
-}
+}

src/core/Akka.Remote.Tests/Transport/CertificateValidationHelpersSpec.cs

@@ -7,6 +7,7 @@
 
 using System;
 using System.Net.Security;
+using System.Security.Cryptography;
 using System.Security.Cryptography.X509Certificates;
 using Akka.Event;
 using Akka.Remote.Transport.DotNetty;
@@ -21,6 +22,7 @@ namespace Akka.Remote.Tests.Transport
     public class CertificateValidationHelpersSpec : AkkaSpec
     {
         private const string ValidCertPath = "Resources/akka-validcert.pfx";
+        private const string ClientCertPath = "Resources/akka-client-cert.pfx";
         private const string Password = "password";
         private readonly ILoggingAdapter _log;
 
@@ -139,6 +141,67 @@ public void PinnedCertificate_should_reject_non_matching_thumbprint()
 
         #endregion
 
+        #region ValidateHostname Tests
+
+        [Fact(DisplayName = "ValidateHostname should compare an explicitly supplied expected hostname")]
+        public void ValidateHostname_should_compare_explicit_expected_hostname()
+        {
+            using var cert = CertificateHelper.LoadPkcs12(ClientCertPath, Password);
+            var matchingValidator = CertificateValidation.ValidateHostname("AkkaTestClient");
+            var rejectingValidator = CertificateValidation.ValidateHostname("unrelated.invalid");
+
+            Assert.True(matchingValidator(cert, null, "test-peer", SslPolicyErrors.None, _log));
+            EventFilter.Error(contains: "expected 'unrelated.invalid'").ExpectOne(() =>
+            {
+                Assert.False(rejectingValidator(cert, null, "test-peer", SslPolicyErrors.None, _log));
+            });
+        }
+
+        [Fact(DisplayName = "ValidateHostname should match any DNS subject alternative name")]
+        public void ValidateHostname_should_match_any_DNS_subject_alternative_name()
+        {
+            using var key = RSA.Create(2048);
+            var request = new CertificateRequest("CN=client.internal", key, HashAlgorithmName.SHA256,
+                RSASignaturePadding.Pkcs1);
+            var subjectAlternativeNames = new SubjectAlternativeNameBuilder();
+            subjectAlternativeNames.AddDnsName("first.internal");
+            subjectAlternativeNames.AddDnsName("second.internal");
+            request.CertificateExtensions.Add(subjectAlternativeNames.Build());
+            using var cert = request.CreateSelfSigned(DateTimeOffset.UtcNow.AddMinutes(-1),
+                DateTimeOffset.UtcNow.AddMinutes(5));
+            var validator = CertificateValidation.ValidateHostname("second.internal");
+
+            Assert.True(validator(cert, null, "test-peer", SslPolicyErrors.None, _log));
+        }
+
+        [Fact(DisplayName = "ValidateHostname without an expected hostname should use SslStream policy errors")]
+        public void ValidateHostname_without_expected_hostname_should_use_policy_errors()
+        {
+            using var cert = CertificateHelper.LoadPkcs12(ClientCertPath, Password);
+            var validator = CertificateValidation.ValidateHostname();
+
+            Assert.True(validator(cert, null, "test-peer", SslPolicyErrors.None, _log));
+            EventFilter.Error(contains: "Hostname validation failed").ExpectOne(() =>
+            {
+                Assert.False(validator(cert, null, "test-peer",
+                    SslPolicyErrors.RemoteCertificateNameMismatch, _log));
+            });
+        }
+
+        [Fact(DisplayName = "ValidateHostname should reject an invalid explicit hostname")]
+        public void ValidateHostname_should_reject_invalid_explicit_hostname()
+        {
+            using var cert = CertificateHelper.LoadPkcs12(ClientCertPath, Password);
+            var validator = CertificateValidation.ValidateHostname("not a valid hostname!");
+
+            EventFilter.Error(contains: "unable to validate expected hostname").ExpectOne(() =>
+            {
+                Assert.False(validator(cert, null, "test-peer", SslPolicyErrors.None, _log));
+            });
+        }
+
+        #endregion
+
         #region ValidateSubject Tests
 
         [Fact(DisplayName = "ValidateSubject should reject null certificate")]
@@ -242,4 +305,4 @@ public void Combine_should_short_circuit_on_first_failure()
 
         #endregion
     }
-}
+}

src/core/Akka.Remote/Configuration/Remote.conf

@@ -576,7 +576,8 @@ akka {
         require-mutual-authentication = true
 
         # Enable or disable certificate hostname validation during TLS handshake.
-        # When true: Traditional TLS hostname validation is performed (certificate CN/SAN must match target hostname)
+        # When true: Traditional outbound TLS hostname validation is performed
+        # (the server certificate CN/SAN must match the connection target hostname)
         # When false: Only validates certificate chain against CA, ignores hostname mismatches
         #
         # Set to false for scenarios such as:
@@ -585,6 +586,9 @@ akka {
         #   - Service discovery with dynamic addresses
         #
         # Default: false (disabled for backward compatibility and mutual TLS flexibility)
+        #
+        # This setting does not infer a hostname for inbound client certificates. Use a
+        # DotNettySslSetup custom validator for application-specific inbound client authorization.
         validate-certificate-hostname = false
       }
     }

src/core/Akka.Remote/Transport/DotNetty/DotNettySslSetup.cs

@@ -15,7 +15,7 @@ namespace Akka.Remote.Transport.DotNetty;
 /// Programmatic setup for DotNetty SSL/TLS configuration.
 /// Provides a fluent API alternative to HOCON configuration.
 /// </summary>
-public sealed class DotNettySslSetup: Setup
+public sealed class DotNettySslSetup : Setup
 {
     /// <summary>
     /// Constructor for backward compatibility - defaults to RequireMutualAuthentication = true, ValidateCertificateHostname = false
@@ -44,7 +44,7 @@ public DotNettySslSetup(X509Certificate2 certificate, bool suppressValidation, b
     /// <param name="certificate">X509 certificate used to establish SSL/TLS</param>
     /// <param name="suppressValidation">When true, suppresses certificate chain validation (use only for development/testing)</param>
     /// <param name="requireMutualAuthentication">When true, requires mutual TLS authentication (both client and server present certificates)</param>
-    /// <param name="validateCertificateHostname">When true, enables hostname validation (certificate CN/SAN must match target hostname)</param>
+    /// <param name="validateCertificateHostname">When true, enables outbound hostname validation (server certificate CN/SAN must match target hostname)</param>
     public DotNettySslSetup(X509Certificate2 certificate, bool suppressValidation, bool requireMutualAuthentication, bool validateCertificateHostname)
         : this(certificate, suppressValidation, requireMutualAuthentication, validateCertificateHostname, customValidator: null)
     {
@@ -68,7 +68,7 @@ public DotNettySslSetup(X509Certificate2 certificate, bool suppressValidation, b
     /// <param name="certificate">X509 certificate used to establish SSL/TLS</param>
     /// <param name="suppressValidation">When true, suppresses certificate chain validation (use only for development/testing)</param>
     /// <param name="requireMutualAuthentication">When true, requires mutual TLS authentication (both client and server present certificates)</param>
-    /// <param name="validateCertificateHostname">When true, enables hostname validation (certificate CN/SAN must match target hostname)</param>
+    /// <param name="validateCertificateHostname">When true, enables outbound hostname validation (server certificate CN/SAN must match target hostname)</param>
     /// <param name="customValidator">Custom certificate validation callback (overrides config-based validation when provided)</param>
     public DotNettySslSetup(X509Certificate2 certificate, bool suppressValidation, bool requireMutualAuthentication, bool validateCertificateHostname, CertificateValidationCallback? customValidator)
     {
@@ -97,7 +97,8 @@ public DotNettySslSetup(X509Certificate2 certificate, bool suppressValidation, b
     public bool RequireMutualAuthentication { get; }
 
     /// <summary>
-    /// When true, enables traditional TLS hostname validation (certificate CN/SAN must match target hostname).
+    /// When true, enables traditional outbound TLS hostname validation
+    /// (the server certificate CN/SAN must match the connection target hostname).
     /// When false, only validates certificate chain against CA, ignores hostname mismatches.
     /// Default is false for backward compatibility and to support mutual TLS scenarios with per-node certificates,
     /// IP-based connections, or dynamic service discovery.

src/core/Akka.Remote/Transport/DotNetty/DotNettyTransportSettings.cs

@@ -11,6 +11,7 @@
 using System.Linq;
 using System.Net;
 using System.Net.Security;
+using System.Security.Cryptography;
 using System.Security.Cryptography.X509Certificates;
 using Akka.Actor;
 using Akka.Configuration;
@@ -114,10 +115,10 @@ namespace Akka.Remote.Transport.DotNetty
     ///     Used for performance-tuning the DotNetty channels to maximize I/O performance.
     /// </param>
     internal sealed record DotNettyTransportSettings(
-        TransportMode TransportMode, 
+        TransportMode TransportMode,
         bool EnableSsl,
         TimeSpan ConnectTimeout,
-        string Hostname, 
+        string Hostname,
         string PublicHostname,
         int Port,
         int? PublicPort,
@@ -132,7 +133,7 @@ internal sealed record DotNettyTransportSettings(
         int Backlog,
         bool EnforceIpFamily,
         int? ReceiveBufferSize,
-        int? SendBufferSize, 
+        int? SendBufferSize,
         int? WriteBufferHighWaterMark,
         int? WriteBufferLowWaterMark,
         bool BackwardsCompatibilityModeEnabled,
@@ -193,7 +194,7 @@ public static DotNettyTransportSettings Create(Config config, SslSettings? sslSe
 
             var transportMode = config.GetString("transport-protocol", "tcp").ToLower();
             var host = config.GetString("hostname");
-            if (string.IsNullOrWhiteSpace(host)) 
+            if (string.IsNullOrWhiteSpace(host))
                 host = IPAddress.Any.ToString();
 
             var publicHost = config.GetString("public-hostname");
@@ -257,7 +258,7 @@ private static int ComputeWorkerPoolSize(Config config)
 
         internal DotNettyTransportSettings Validate()
         {
-            if (MaxFrameSize < 32000) 
+            if (MaxFrameSize < 32000)
                 throw new ArgumentException("maximum-frame-size must be at least 32000 bytes", nameof(MaxFrameSize));
 
             return this;
@@ -367,7 +368,8 @@ private static X509KeyStorageFlags ParseKeyStorageFlag(string str)
         public readonly bool RequireMutualAuthentication;
 
         /// <summary>
-        /// When true, enables traditional TLS hostname validation (certificate CN/SAN must match target hostname).
+        /// When true, enables traditional outbound TLS hostname validation
+        /// (the server certificate CN/SAN must match the connection target hostname).
         /// When false, only validates certificate chain against CA, ignores hostname mismatches.
         /// Default is false for backward compatibility and to support mutual TLS scenarios with per-node certificates,
         /// IP-based connections, or dynamic service discovery.
@@ -565,10 +567,13 @@ public static CertificateValidationCallback ValidateChain(
         }
 
         /// <summary>
-        /// Validate certificate hostname (CN/SAN) matches expected hostname.
-        /// Use for: Per-node certificates, FQDN-based identity.
-        /// Applies bidirectionally on both client and server.
+        /// Without an explicit hostname, validates the outbound server certificate using the hostname result
+        /// supplied by <see cref="SslStream"/>. When <paramref name="expectedHostname"/> is supplied, compares
+        /// that name directly against the certificate CN/SAN.
+        /// This helper does not infer a hostname for inbound client certificates.
         /// </summary>
+        /// <param name="expectedHostname">Optional hostname to compare directly against the certificate.</param>
+        /// <param name="log">Optional logger for validation failures.</param>
         public static CertificateValidationCallback ValidateHostname(
             string? expectedHostname = null,
             ILoggingAdapter? log = null)
@@ -583,15 +588,37 @@ public static CertificateValidationCallback ValidateHostname(
                     return false;
                 }
 
-                var hostname = expectedHostname ?? peer;
+                if (expectedHostname == null)
+                {
+                    if ((errors & SslPolicyErrors.RemoteCertificateNameMismatch) == 0)
+                        return true;
 
-                if ((errors & SslPolicyErrors.RemoteCertificateNameMismatch) == 0) return true;
-                var cn = cert.GetNameInfo(X509NameType.DnsName, false);
+                    var certificateName = cert.GetNameInfo(X509NameType.DnsName, false);
+                    (log ?? nonClosureLog).Error(
+                        "Hostname validation failed for {0}: certificate name is '{1}'",
+                        peer, certificateName);
+                    return false;
+                }
+
+                try
+                {
+                    if (cert.MatchesHostname(expectedHostname))
+                        return true;
+                }
+                catch (Exception ex) when (ex is ArgumentException or CryptographicException)
+                {
+                    (log ?? nonClosureLog).Error(
+                        ex,
+                        "Hostname validation failed for {0}: unable to validate expected hostname '{1}'",
+                        peer, expectedHostname);
+                    return false;
+                }
+
+                var name = cert.GetNameInfo(X509NameType.DnsName, false);
                 (log ?? nonClosureLog).Error(
-                    "Hostname validation failed for {0}: expected '{1}', certificate CN is '{2}'",
-                    peer, hostname, cn);
+                    "Hostname validation failed for {0}: expected '{1}', certificate name is '{2}'",
+                    peer, expectedHostname, name);
                 return false;
-
             };
         }