feat: add handshake Exception on ITlsHandshakeFeature (#65807)

DeagleGross · web-flow · commit b37503cd5310 · 2026-04-08T19:08:25.000-07:00
diff --git a/src/Servers/Connections.Abstractions/src/Features/ITlsHandshakeFeature.cs b/src/Servers/Connections.Abstractions/src/Features/ITlsHandshakeFeature.cs
@@ -82,4 +82,12 @@ public interface ITlsHandshakeFeature
     [Obsolete(Obsoletions.RuntimeTlsCipherAlgorithmEnumsMessage, DiagnosticId = Obsoletions.RuntimeTlsCipherAlgorithmEnumsDiagId, UrlFormat = Obsoletions.RuntimeSharedUrlFormat)]
 #endif
     int KeyExchangeStrength { get; }
+
+#if NET11_0_OR_GREATER
+    /// <summary>
+    /// Gets the exception that occurred during the TLS handshake, if any.
+    /// <see langword="null"/> if the handshake succeeded or has not yet completed.
+    /// </summary>
+    Exception? Exception => null;
+#endif
 }
diff --git a/src/Servers/Connections.Abstractions/src/PublicAPI/net11.0/PublicAPI.Unshipped.txt b/src/Servers/Connections.Abstractions/src/PublicAPI/net11.0/PublicAPI.Unshipped.txt
@@ -1 +1,2 @@
 #nullable enable
+Microsoft.AspNetCore.Connections.Features.ITlsHandshakeFeature.Exception.get -> System.Exception?
diff --git a/src/Servers/Kestrel/Core/src/Internal/TlsConnectionFeature.cs b/src/Servers/Kestrel/Core/src/Internal/TlsConnectionFeature.cs
@@ -16,9 +16,23 @@ internal sealed class TlsConnectionFeature : ITlsConnectionFeature, ITlsApplicat
 {
     private readonly SslStream _sslStream;
     private readonly ConnectionContext _context;
+    private bool _snapshotted;
+
     private X509Certificate2? _clientCert;
     private Task<X509Certificate2?>? _clientCertTask;
 
+    private SslProtocols _protocol;
+    private TlsCipherSuite? _negotiatedCipherSuite;
+    private ReadOnlyMemory<byte> _applicationProtocol;
+#pragma warning disable SYSLIB0058 // Obsolete TLS cipher algorithm enums
+    private CipherAlgorithmType _cipherAlgorithm;
+    private int _cipherStrength;
+    private HashAlgorithmType _hashAlgorithm;
+    private int _hashStrength;
+    private ExchangeAlgorithmType _keyExchangeAlgorithm;
+    private int _keyExchangeStrength;
+#pragma warning restore SYSLIB0058
+
     public TlsConnectionFeature(SslStream sslStream, ConnectionContext context)
     {
         ArgumentNullException.ThrowIfNull(sslStream);
@@ -28,6 +42,47 @@ public TlsConnectionFeature(SslStream sslStream, ConnectionContext context)
         _context = context;
     }
 
+    /// <summary>
+    /// Captures all SslStream-backed property values so they remain accessible after the SslStream is disposed.
+    /// Must be called before disposing the SslStream.
+    /// </summary>
+    internal void Snapshot()
+    {
+        if (_snapshotted)
+        {
+            return;
+        }
+        _snapshotted = true;
+
+        if (_sslStream is null)
+        {
+            return;
+        }
+
+        try
+        {
+            _protocol = _sslStream.SslProtocol;
+            _negotiatedCipherSuite = _sslStream.NegotiatedCipherSuite;
+            _applicationProtocol = _sslStream.NegotiatedApplicationProtocol.Protocol.ToArray();
+
+#pragma warning disable SYSLIB0058 // Obsolete TLS cipher algorithm enums
+            _cipherAlgorithm = _sslStream.CipherAlgorithm;
+            _cipherStrength = _sslStream.CipherStrength;
+            _hashAlgorithm = _sslStream.HashAlgorithm;
+            _hashStrength = _sslStream.HashStrength;
+            _keyExchangeAlgorithm = _sslStream.KeyExchangeAlgorithm;
+            _keyExchangeStrength = _sslStream.KeyExchangeStrength;
+#pragma warning restore SYSLIB0058
+
+            _clientCert ??= ConvertToX509Certificate2(_sslStream.RemoteCertificate);
+        }
+        catch
+        {
+            // If the handshake never completed, SslStream properties may throw.
+            // The snapshotted fields will retain their default values.
+        }
+    }
+
     internal bool AllowDelayedClientCertificateNegotation { get; set; }
 
     public X509Certificate2? ClientCertificate
@@ -45,33 +100,35 @@ public X509Certificate2? ClientCertificate
 
     public string HostName { get; set; } = string.Empty;
 
-    public ReadOnlyMemory<byte> ApplicationProtocol => _sslStream.NegotiatedApplicationProtocol.Protocol;
+    public ReadOnlyMemory<byte> ApplicationProtocol => _snapshotted ? _applicationProtocol : _sslStream.NegotiatedApplicationProtocol.Protocol;
 
-    public SslProtocols Protocol => _sslStream.SslProtocol;
+    public SslProtocols Protocol => _snapshotted ? _protocol : _sslStream.SslProtocol;
 
     public SslStream SslStream => _sslStream;
 
-    // We don't store the values for these because they could be changed by a renegotiation.
+    public Exception? Exception { get; set; }
+
+    // After Snapshot() is called, all values are served from cached fields instead of the SslStream.
 
-    public TlsCipherSuite? NegotiatedCipherSuite => _sslStream.NegotiatedCipherSuite;
+    public TlsCipherSuite? NegotiatedCipherSuite => _snapshotted ? _negotiatedCipherSuite : _sslStream.NegotiatedCipherSuite;
 
     [Obsolete(Obsoletions.RuntimeTlsCipherAlgorithmEnumsMessage, DiagnosticId = Obsoletions.RuntimeTlsCipherAlgorithmEnumsDiagId, UrlFormat = Obsoletions.RuntimeSharedUrlFormat)]
-    public CipherAlgorithmType CipherAlgorithm => _sslStream.CipherAlgorithm;
+    public CipherAlgorithmType CipherAlgorithm => _snapshotted ? _cipherAlgorithm : _sslStream.CipherAlgorithm;
 
     [Obsolete(Obsoletions.RuntimeTlsCipherAlgorithmEnumsMessage, DiagnosticId = Obsoletions.RuntimeTlsCipherAlgorithmEnumsDiagId, UrlFormat = Obsoletions.RuntimeSharedUrlFormat)]
-    public int CipherStrength => _sslStream.CipherStrength;
+    public int CipherStrength => _snapshotted ? _cipherStrength : _sslStream.CipherStrength;
 
     [Obsolete(Obsoletions.RuntimeTlsCipherAlgorithmEnumsMessage, DiagnosticId = Obsoletions.RuntimeTlsCipherAlgorithmEnumsDiagId, UrlFormat = Obsoletions.RuntimeSharedUrlFormat)]
-    public HashAlgorithmType HashAlgorithm => _sslStream.HashAlgorithm;
+    public HashAlgorithmType HashAlgorithm => _snapshotted ? _hashAlgorithm : _sslStream.HashAlgorithm;
 
     [Obsolete(Obsoletions.RuntimeTlsCipherAlgorithmEnumsMessage, DiagnosticId = Obsoletions.RuntimeTlsCipherAlgorithmEnumsDiagId, UrlFormat = Obsoletions.RuntimeSharedUrlFormat)]
-    public int HashStrength => _sslStream.HashStrength;
+    public int HashStrength => _snapshotted ? _hashStrength : _sslStream.HashStrength;
 
     [Obsolete(Obsoletions.RuntimeTlsCipherAlgorithmEnumsMessage, DiagnosticId = Obsoletions.RuntimeTlsCipherAlgorithmEnumsDiagId, UrlFormat = Obsoletions.RuntimeSharedUrlFormat)]
-    public ExchangeAlgorithmType KeyExchangeAlgorithm => _sslStream.KeyExchangeAlgorithm;
+    public ExchangeAlgorithmType KeyExchangeAlgorithm => _snapshotted ? _keyExchangeAlgorithm : _sslStream.KeyExchangeAlgorithm;
 
     [Obsolete(Obsoletions.RuntimeTlsCipherAlgorithmEnumsMessage, DiagnosticId = Obsoletions.RuntimeTlsCipherAlgorithmEnumsDiagId, UrlFormat = Obsoletions.RuntimeSharedUrlFormat)]
-    public int KeyExchangeStrength => _sslStream.KeyExchangeStrength;
+    public int KeyExchangeStrength => _snapshotted ? _keyExchangeStrength : _sslStream.KeyExchangeStrength;
 
     public Task<X509Certificate2?> GetClientCertificateAsync(CancellationToken cancellationToken)
     {
diff --git a/src/Servers/Kestrel/Core/src/Middleware/HttpsConnectionMiddleware.cs b/src/Servers/Kestrel/Core/src/Middleware/HttpsConnectionMiddleware.cs
@@ -187,6 +187,8 @@ public async Task OnConnectionAsync(ConnectionContext context)
         }
         catch (OperationCanceledException ex)
         {
+            feature.Exception = ex;
+            feature.Snapshot();
             RecordHandshakeFailed(_metrics, startTimestamp, Stopwatch.GetTimestamp(), metricsContext, metricsTagsFeature, ex);
 
             _logger.AuthenticationTimedOut();
@@ -195,6 +197,8 @@ public async Task OnConnectionAsync(ConnectionContext context)
         }
         catch (IOException ex)
         {
+            feature.Exception = ex;
+            feature.Snapshot();
             RecordHandshakeFailed(_metrics, startTimestamp, Stopwatch.GetTimestamp(), metricsContext, metricsTagsFeature, ex);
 
             _logger.AuthenticationFailed(ex);
@@ -203,6 +207,8 @@ public async Task OnConnectionAsync(ConnectionContext context)
         }
         catch (AuthenticationException ex)
         {
+            feature.Exception = ex;
+            feature.Snapshot();
             RecordHandshakeFailed(_metrics, startTimestamp, Stopwatch.GetTimestamp(), metricsContext, metricsTagsFeature, ex);
 
             _logger.AuthenticationFailed(ex);
@@ -238,7 +244,16 @@ public async Task OnConnectionAsync(ConnectionContext context)
             await using (sslStream)
             await using (sslDuplexPipe)
             {
-                await _next(context);
+                try
+                {
+                    await _next(context);
+                }
+                finally
+                {
+                    // Snapshot SslStream-backed properties before disposal so outer middleware
+                    // can still read ITlsHandshakeFeature after the connection completes.
+                    feature.Snapshot();
+                }
                 // Dispose the inner stream (SslDuplexPipe) before disposing the SslStream
                 // as the duplex pipe can hit an ODE as it still may be writing.
             }
diff --git a/src/Servers/Kestrel/samples/SampleApp/Startup.cs b/src/Servers/Kestrel/samples/SampleApp/Startup.cs
@@ -105,9 +105,27 @@ public static Task Main(string[] args)
 
                         options.Listen(IPAddress.Loopback, basePort + 1, listenOptions =>
                         {
-                            listenOptions.Protocols = Microsoft.AspNetCore.Server.Kestrel.Core.HttpProtocols.Http1;
+                            listenOptions.Use(next => async context =>
+                            {
+                                await next(context);
+
+                                var tlsHandshakeFeature = context.Features.Get<ITlsHandshakeFeature>();
+                                if (tlsHandshakeFeature?.Exception is { } ex)
+                                {
+                                    Console.WriteLine($"[TLS Handshake Failed] ConnectionId={context.ConnectionId}, Exception={ex.GetType().Name}: {ex.Message}");
+                                }
+                            });
+
                             listenOptions.UseHttps();
                             listenOptions.UseConnectionLogging();
+
+                            listenOptions.Use(next => async context =>
+                            {
+                                var tlsHandshakeFeature = context.Features.Get<ITlsHandshakeFeature>();
+                                Console.WriteLine($"[TLS Handshake OK] ConnectionId={context.ConnectionId}, Protocol={tlsHandshakeFeature.Protocol}");
+
+                                await next(context);
+                            });
                         });
 
                         options.ListenLocalhost(basePort + 2, listenOptions =>
diff --git a/src/Servers/Kestrel/test/InMemory.FunctionalTests/HttpsConnectionMiddlewareTests.cs b/src/Servers/Kestrel/test/InMemory.FunctionalTests/HttpsConnectionMiddlewareTests.cs
@@ -202,6 +202,107 @@ void ConfigureListenOptions(ListenOptions listenOptions)
         }
     }
 
+    [Fact]
+    public async Task HandshakeExceptionIsAvailableAfterHandshakeFailure()
+    {
+        var handshakeFeatureTcs = new TaskCompletionSource<ITlsHandshakeFeature>(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        void ConfigureListenOptions(ListenOptions listenOptions)
+        {
+            // Outer middleware wraps the HTTPS middleware and can inspect the feature after it returns.
+            listenOptions.Use(next => async connectionContext =>
+            {
+                await next(connectionContext);
+
+                var feature = connectionContext.Features.Get<ITlsHandshakeFeature>();
+                handshakeFeatureTcs.TrySetResult(feature);
+            });
+
+            listenOptions.UseHttps(new HttpsConnectionAdapterOptions { ServerCertificate = _x509Certificate2 });
+        }
+
+        await using (var server = new TestServer(context => Task.CompletedTask, new TestServiceContext(LoggerFactory), ConfigureListenOptions))
+        {
+            using var connection = server.CreateConnection();
+            await using var sslStream = new SslStream(connection.Stream);
+
+            var clientAuthOptions = new SslClientAuthenticationOptions
+            {
+                TargetHost = "localhost",
+                // Only enabling an obsolete protocol should cause a handshake failure.
+#pragma warning disable CS0618 // Type or member is obsolete
+                EnabledSslProtocols = SslProtocols.Ssl2,
+#pragma warning restore CS0618
+            };
+
+            using var handshakeCts = new CancellationTokenSource(TestConstants.DefaultTimeout);
+            await Assert.ThrowsAnyAsync<Exception>(() => sslStream.AuthenticateAsClientAsync(clientAuthOptions, handshakeCts.Token));
+
+            var handshakeFeature = await handshakeFeatureTcs.Task.DefaultTimeout();
+            Assert.NotNull(handshakeFeature);
+            Assert.NotNull(handshakeFeature.Exception);
+        }
+    }
+
+    [Fact]
+    public async Task HandshakeFeaturePropertiesAreAccessibleAfterHandshakeTimeout()
+    {
+        var handshakeFeatureTcs = new TaskCompletionSource<ITlsHandshakeFeature>(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        void ConfigureListenOptions(ListenOptions listenOptions)
+        {
+            listenOptions.Use(next => async connectionContext =>
+            {
+                await next(connectionContext);
+
+                var feature = connectionContext.Features.Get<ITlsHandshakeFeature>();
+                handshakeFeatureTcs.TrySetResult(feature);
+            });
+
+            listenOptions.UseHttps(o =>
+            {
+                o.ServerCertificate = _x509Certificate2;
+                o.HandshakeTimeout = TimeSpan.FromSeconds(2);
+            });
+        }
+
+        await using (var server = new TestServer(context => Task.CompletedTask, new TestServiceContext(LoggerFactory), ConfigureListenOptions))
+        {
+            using var connection = server.CreateConnection();
+            // Don't send any TLS data — let the handshake time out.
+            Assert.Equal(0, await connection.Stream.ReadAsync(new byte[1], 0, 1).DefaultTimeout());
+
+            var handshakeFeature = await handshakeFeatureTcs.Task.DefaultTimeout();
+            Assert.NotNull(handshakeFeature);
+            Assert.IsAssignableFrom<OperationCanceledException>(handshakeFeature.Exception);
+        }
+    }
+
+    [Fact]
+    public async Task HandshakeExceptionIsNullOnSuccessfulHandshake()
+    {
+        ITlsHandshakeFeature capturedFeature = null;
+
+        void ConfigureListenOptions(ListenOptions listenOptions)
+        {
+            listenOptions.UseHttps(new HttpsConnectionAdapterOptions { ServerCertificate = _x509Certificate2 });
+        }
+
+        await using (var server = new TestServer(context =>
+        {
+            capturedFeature = context.Features.Get<ITlsHandshakeFeature>();
+            Assert.NotNull(capturedFeature);
+            Assert.Null(capturedFeature.Exception);
+            return context.Response.WriteAsync("hello world");
+        }, new TestServiceContext(LoggerFactory), ConfigureListenOptions))
+        {
+            var result = await server.HttpClientSlim.GetStringAsync($"https://localhost:{server.Port}/", validateCertificate: false);
+            Assert.Equal("hello world", result);
+        }
+
+        Assert.NotNull(capturedFeature);
+    }
+
     [Fact]
     public async Task RequireCertificateFailsWhenNoCertificate()
     {

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`#nullable enable`
	`2`	`+Microsoft.AspNetCore.Connections.Features.ITlsHandshakeFeature.Exception.get -> System.Exception?`
Original file line number	Diff line number	Diff line change
`@@ -187,6 +187,8 @@ public async Task OnConnectionAsync(ConnectionContext context)`
`187`	`187`	`}`
`188`	`188`	`catch (OperationCanceledException ex)`
`189`	`189`	`{`
	`190`	`+ feature.Exception = ex;`
	`191`	`+ feature.Snapshot();`
`190`	`192`	`RecordHandshakeFailed(_metrics, startTimestamp, Stopwatch.GetTimestamp(), metricsContext, metricsTagsFeature, ex);`
`191`	`193`
`192`	`194`	`_logger.AuthenticationTimedOut();`
`@@ -195,6 +197,8 @@ public async Task OnConnectionAsync(ConnectionContext context)`
`195`	`197`	`}`
`196`	`198`	`catch (IOException ex)`
`197`	`199`	`{`
	`200`	`+ feature.Exception = ex;`
	`201`	`+ feature.Snapshot();`
`198`	`202`	`RecordHandshakeFailed(_metrics, startTimestamp, Stopwatch.GetTimestamp(), metricsContext, metricsTagsFeature, ex);`
`199`	`203`
`200`	`204`	`_logger.AuthenticationFailed(ex);`
`@@ -203,6 +207,8 @@ public async Task OnConnectionAsync(ConnectionContext context)`
`203`	`207`	`}`
`204`	`208`	`catch (AuthenticationException ex)`
`205`	`209`	`{`
	`210`	`+ feature.Exception = ex;`
	`211`	`+ feature.Snapshot();`
`206`	`212`	`RecordHandshakeFailed(_metrics, startTimestamp, Stopwatch.GetTimestamp(), metricsContext, metricsTagsFeature, ex);`
`207`	`213`
`208`	`214`	`_logger.AuthenticationFailed(ex);`
`@@ -238,7 +244,16 @@ public async Task OnConnectionAsync(ConnectionContext context)`
`238`	`244`	`await using (sslStream)`
`239`	`245`	`await using (sslDuplexPipe)`
`240`	`246`	`{`
`241`		`- await _next(context);`
	`247`	`+ try`
	`248`	`+ {`
	`249`	`+ await _next(context);`
	`250`	`+ }`
	`251`	`+ finally`
	`252`	`+ {`
	`253`	`+ // Snapshot SslStream-backed properties before disposal so outer middleware`
	`254`	`+ // can still read ITlsHandshakeFeature after the connection completes.`
	`255`	`+ feature.Snapshot();`
	`256`	`+ }`
`242`	`257`	`// Dispose the inner stream (SslDuplexPipe) before disposing the SslStream`
`243`	`258`	`// as the duplex pipe can hit an ODE as it still may be writing.`
`244`	`259`	`}`