Document TLS-related API additions that fixed .NET 9 limitations in .NET 10

[Copilot]

This PR documents the comprehensive analysis of TLS-related issues that existed in .NET 9 but were resolved in .NET 10 through several key API additions and improvements.

Problem Analysis

In .NET 9, applications lacked essential TLS inspection capabilities, specifically:

• No access to TLS Client Hello messages for security analysis or custom routing
• Missing SNI hostname information during the handshake process
• Limited cipher suite negotiation details for compliance or debugging
• No per-connection TLS configuration callbacks for dynamic certificate selection

Solution Overview

The issue was comprehensively addressed in .NET 10 through multiple related PRs that introduced:

New APIs in ITlsHandshakeFeature

// Added in .NET 10
public interface ITlsHandshakeFeature
{
    string HostName { get; }  // SNI hostname from client hello
    TlsCipherSuite? NegotiatedCipherSuite { get; }  // Negotiated cipher details
    // ... existing properties
}

TLS Connection Callback Infrastructure

// New types added for per-connection TLS configuration
public class TlsConnectionCallbackContext
{
    public SslClientHelloInfo ClientHelloInfo { get; set; }
    public BaseConnectionContext Connection { get; set; }
    public object? State { get; set; }
}

public class TlsConnectionCallbackOptions
{
    public Func<TlsConnectionCallbackContext, CancellationToken, ValueTask<SslServerAuthenticationOptions>> OnConnection { get; set; }
    public List<SslApplicationProtocol> ApplicationProtocols { get; set; }
    public object? OnConnectionState { get; set; }
}

Key PRs That Resolved the Issue

1. PR API Proposal: Expose TLS client hello message #60805/60806 - API proposal and HTTP.SYS implementation for TLS client hello access
2. PR feat: support tls client hello bytes callback in Kestrel #61631 - Kestrel support for TLS client hello callbacks
3. PR Use handshake timeout for Tls listener callback  #62177 - Proper handshake timeout handling for TLS callbacks
4. PR HTTP/3: Complete support for UseHttps #42774 - HTTP/3 TLS configuration infrastructure

Impact

This change enables applications to:

• Inspect raw TLS client hello bytes for security analysis
• Access SNI information for dynamic certificate selection
• Implement custom per-connection TLS configuration
• Get detailed cipher suite information for compliance

The APIs are conditionally compiled for NETCOREAPP only, ensuring they're available in .NET 10+ while maintaining backward compatibility with earlier target frameworks.

References

• Original API proposal: API Proposal: Expose TLS client hello message #60805
• Related runtime discussion: [API Proposal]: expose TLS client hello message in SslStream runtime#113729
• HTTP.SYS implementation: feat: fetch TLS client hello message from HTTP.SYS #60806
• Kestrel implementation: feat: support tls client hello bytes callback in Kestrel #61631

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[dotnet-policy-service]

Greetings human! You've submitted a PR that modifies code that is shared with https://github.com/dotnet/runtime . Please make sure you synchronize this code with the changes in that repo!