Repository navigation
Description
This proposal was prototyped before - look at #67912
Status: experimental, Linux-only. Every public type and member below is gated behind the
[Experimental("ASPNETCORE_DIRECTTLS_001")]diagnostic (UrlFormat = https://aka.ms/aspnetcore/directtls). Consumers opt in with#pragma warning disable ASPNETCORE_DIRECTTLS_001(or<NoWarn>).
0. Background
TLS termination in Kestrel today goes through SslStream, which copies application bytes through managed BIO buffers on top of the socket. The goal of DirectTls is to make TLS-bound traffic perform better by terminating TLS directly on the socket's file descriptor. It does this with the runtime's low-level, fd-bound OpenSSL TLS session (System.Net.Security.TlsContext / TlsSocketSession from dotnet/runtime#128871), so encrypted bytes are read from and written to the socket fd without the extra SslStream buffering layer. The transport is a drop-in alternative for a Kestrel HTTPS endpoint — same certificates, SNI, ALPN, and mTLS knobs — that you opt into per endpoint.
1. Why a separate assembly
DirectTls ships as its own assembly, Microsoft.AspNetCore.Server.Kestrel.Transport.DirectTls, rather than being folded into Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets or Kestrel core. Like the other Kestrel transports, the assembly is part of the ASP.NET Core shared framework (<IsAspNetCoreApp>true</IsAspNetCoreApp>), so it is present on any ASP.NET Core host — it is not a separate NuGet package you acquire. The separation is about layering, isolation, and trimmability, not distribution:
-
Layering — it references Kestrel core directly. Unlike the general-purpose Sockets/Quic transports (which only know about raw bytes), DirectTls terminates TLS and is tightly integrated with Kestrel's HTTPS semantics: it reads
HttpProtocols(ALPN),ClientCertificateMode, and publishesITlsApplicationProtocolFeature— all of which live inMicrosoft.AspNetCore.Server.Kestrel.Core. Putting it in its own assembly lets it take thatKestrel.Corereference without dragging TLS/OpenSSL concerns into the default socket transport, which stays a plaintext, protocol-agnostic byte pipe. The dependency direction is one-way (Transport.DirectTls→Kestrel.Core); core never references the transport, so there is no cycle. -
Dependency isolation. The transport consumes an experimental runtime API (
TlsContext/TlsSocketSession, gated behindSYSLIB5007) and requires OpenSSL (libssl) at runtime. Isolating that in its own assembly keeps the experimental surface — and itsNoWarn(SYSLIB5007,ASPNETCORE_DIRECTTLS_001) — out of the shipped Kestrel transport assemblies. -
Trimmable / opt-in. The transport is only wired up when you call
UseDirectTlsTransport(). The assembly is marked<IsTrimmable>true</IsTrimmable>, so for trimmed or Native AOT apps that never call it, the linker can remove it entirely — you don't pay for it if you don't use it. Registration is additive:UseDirectTlsTransport()adds the transport next to the default one and only claimsDirectTlsEndpointendpoints; every other endpoint keeps using the default transport. -
Experimental gate. The
[Experimental("ASPNETCORE_DIRECTTLS_001")]attribute is the real opt-in: you must explicitly suppress the diagnostic to use the API, which keeps it clearly separate from stable Kestrel surface while it is being validated.
2. API surface
Two namespaces are involved:
Microsoft.AspNetCore.Hosting— the registration extension methods.Microsoft.AspNetCore.Server.Kestrel.Transport.DirectTls— the endpoint and options types.
2.1 Registration — WebHostBuilderDirectTlsExtensions
namespace Microsoft.AspNetCore.Hosting;
[Experimental("ASPNETCORE_DIRECTTLS_001", UrlFormat = "https://aka.ms/aspnetcore/directtls")]
public static class WebHostBuilderDirectTlsExtensions
{
// Register the transport with defaults.
public static IWebHostBuilder UseDirectTlsTransport(this IWebHostBuilder hostBuilder);
// Register the transport and configure transport-wide options.
public static IWebHostBuilder UseDirectTlsTransport(
this IWebHostBuilder hostBuilder,
Action<DirectTlsTransportOptions> configureOptions);
}Call this after UseKestrel(). The DirectTls factory is registered additively (last-registered is tried first), and its CanBind claims only DirectTlsEndpoint; all other endpoint types fall through to the default transport.
2.2 Transport-wide options — DirectTlsTransportOptions
namespace Microsoft.AspNetCore.Server.Kestrel.Transport.DirectTls;
[Experimental("ASPNETCORE_DIRECTTLS_001", UrlFormat = "https://aka.ms/aspnetcore/directtls")]
public sealed class DirectTlsTransportOptions
{
// Number of epoll event-pump threads the transport spreads accepted connections across. Default: 4.
public int WorkerCount { get; set; } = 4;
}2.3 The endpoint — DirectTlsEndpoint
An IPEndPoint subtype that opts a single Kestrel listener into the DirectTls transport. Bind it with KestrelServerOptions.Listen(...) (or ListenAnyIP / ListenLocalhost).
namespace Microsoft.AspNetCore.Server.Kestrel.Transport.DirectTls;
[Experimental("ASPNETCORE_DIRECTTLS_001", UrlFormat = "https://aka.ms/aspnetcore/directtls")]
public sealed class DirectTlsEndpoint : IPEndPoint
{
public DirectTlsEndpoint(IPAddress address, int port);
public DirectTlsEndpoint(IPAddress address, int port, DirectTlsEndpointOptions options);
public DirectTlsEndpoint(int port, DirectTlsEndpointOptions options); // listens on IPAddress.Any
public DirectTlsEndpoint(IPEndPoint endpoint, DirectTlsEndpointOptions options);
// Per-endpoint TLS configuration. Never null (a default instance is created by the first ctor).
public DirectTlsEndpointOptions Options { get; }
}2.4 Per-endpoint TLS configuration — DirectTlsEndpointOptions
DirectTls is TLS-only: every endpoint terminates TLS, so a server certificate is required (either ServerCertificate or ServerCertificateSelector). The members mirror HttpsConnectionAdapterOptions so an existing HTTPS endpoint maps over with the same knobs.
namespace Microsoft.AspNetCore.Server.Kestrel.Transport.DirectTls;
[Experimental("ASPNETCORE_DIRECTTLS_001", UrlFormat = "https://aka.ms/aspnetcore/directtls")]
public sealed class DirectTlsEndpointOptions
{
// The certificate presented during the handshake (used when the selector is unset or returns null).
public X509Certificate2? ServerCertificate { get; set; }
// Selects the certificate from the connection + SNI host parsed from the ClientHello. Returning null falls back to ServerCertificate.
public Func<ConnectionContext?, string?, X509Certificate2?>? ServerCertificateSelector { get; set; }
// Protocols offered on this endpoint; drives the ALPN list (h2 is offered when Http2 is included). Default: HttpProtocols.Http1AndHttp2.
public HttpProtocols HttpProtocols { get; set; }
// Allowable TLS versions. Default: SslProtocols.None (OS default).
public SslProtocols SslProtocols { get; set; }
// Whether a client certificate is requested/required (mTLS). Default: ClientCertificateMode.NoCertificate. ClientCertificateMode.DelayCertificate is not supported.
public ClientCertificateMode ClientCertificateMode { get; set; }
// Validates a client certificate when one is requested. Return true to accept. When unset, a certificate is accepted only when it produced no SslPolicyErrors.
public Func<X509Certificate2, X509Chain?, SslPolicyErrors, bool>? ClientCertificateValidation { get; set; }
// Observes the raw ClientHello record bytes as soon as they are parsed (fingerprinting/telemetry). Observation only — it cannot alter or reject the handshake.
public Action<ConnectionContext, ReadOnlySequence<byte>>? TlsClientHelloBytesCallback { get; set; }
}| Member | Type | Default | Equivalent in today's API | Purpose |
|---|---|---|---|---|
ServerCertificate |
X509Certificate2? |
null |
HttpsConnectionAdapterOptions.ServerCertificate |
Static server certificate. |
ServerCertificateSelector |
Func<ConnectionContext?, string?, X509Certificate2?>? |
null |
HttpsConnectionAdapterOptions.ServerCertificateSelector (identical signature) |
Per-connection SNI certificate selection. |
HttpProtocols |
HttpProtocols |
Http1AndHttp2 |
ListenOptions.Protocols |
ALPN advertisement (h2 negotiation). |
SslProtocols |
SslProtocols |
None |
HttpsConnectionAdapterOptions.SslProtocols |
Allowable TLS versions. |
ClientCertificateMode |
ClientCertificateMode |
NoCertificate |
HttpsConnectionAdapterOptions.ClientCertificateMode |
mTLS request/require (no DelayCertificate). |
ClientCertificateValidation |
Func<X509Certificate2, X509Chain?, SslPolicyErrors, bool>? |
null |
HttpsConnectionAdapterOptions.ClientCertificateValidation (identical signature) |
Client certificate acceptance. |
TlsClientHelloBytesCallback |
Action<ConnectionContext, ReadOnlySequence<byte>>? |
null |
HttpsConnectionAdapterOptions.TlsClientHelloBytesCallback (identical signature) |
Raw ClientHello observation. |
3. Usage from Program.cs
3.1 Minimal — one HTTPS endpoint
using System.Net;
using System.Security.Cryptography.X509Certificates;
using Microsoft.AspNetCore.Server.Kestrel.Transport.DirectTls;
#pragma warning disable ASPNETCORE_DIRECTTLS_001
var builder = WebApplication.CreateBuilder(args);
// Register the DirectTls transport AFTER UseKestrel.
builder.WebHost.UseKestrel();
builder.WebHost.UseDirectTlsTransport();
builder.WebHost.ConfigureKestrel(options =>
{
var endpoint = new DirectTlsEndpoint(IPAddress.Any, 5001);
endpoint.Options.ServerCertificate =
X509Certificate2.CreateFromPemFile("server.crt", "server.key");
options.Listen(endpoint);
});
var app = builder.Build();
app.MapGet("/", (HttpContext ctx) => $"Hello over {ctx.Request.Protocol}");
app.Run();3.2 Full-featured endpoint — SNI selection, ALPN/HTTP-2, ClientHello observation
var p256 = X509Certificate2.CreateFromPemFile("server-p256.crt", "server-p256.key");
var p384 = X509Certificate2.CreateFromPemFile("server-p384.crt", "server-p384.key");
builder.WebHost.ConfigureKestrel(options =>
{
var endpoint = new DirectTlsEndpoint(IPAddress.Any, 5001);
// ALPN: offer h2 and http/1.1.
endpoint.Options.HttpProtocols = HttpProtocols.Http1AndHttp2;
// Per-connection certificate selection by ClientHello SNI host.
endpoint.Options.ServerCertificateSelector = (connection, host) =>
string.Equals(host, "p384.example", StringComparison.OrdinalIgnoreCase) ? p384 : p256;
// Observe the raw ClientHello (bytes[0] == 0x16 handshake record). Observation only.
endpoint.Options.TlsClientHelloBytesCallback = (connection, clientHelloBytes) =>
Console.WriteLine($"[ClientHello] {connection.ConnectionId}: {clientHelloBytes.Length} bytes");
options.Listen(endpoint);
});3.3 Mutual TLS (client certificates)
builder.WebHost.ConfigureKestrel(options =>
{
// Bind on IPAddress.Any via the (int port, options) convenience ctor.
var endpoint = new DirectTlsEndpoint(5001, new DirectTlsEndpointOptions
{
ServerCertificate = serverCertificate,
ClientCertificateMode = ClientCertificateMode.RequireCertificate,
ClientCertificateValidation = (clientCert, chain, errors) => errors == SslPolicyErrors.None,
});
options.Listen(endpoint);
});3.4 Tuning the transport (event-pump threads)
builder.WebHost.UseKestrel();
builder.WebHost.UseDirectTlsTransport(transport =>
{
transport.WorkerCount = 8; // number of epoll pump threads
});Note: Only endpoints bound as a
DirectTlsEndpointuse this transport. Any regularIPEndPoint(orUseHttpsendpoint) continues to use the default Kestrel transport, so DirectTls and the default transport can coexist in the same host.
Activity
halter73 commentedon Jul 21, 2026
API Review Notes:
DirectTlsTransportOptions.WorkerCountwas moved to the runtime, but this is an experimental APIIOQueueCount. We don't need a static default of4. We can base it onEnvironment.ProcessorCountUseDirectTlsTransportbe calledUseDirectTls?UseSocketsandUseQuic.DirectTlsEndpointconstructors?DirectTlsEndpoint(int port, DirectTlsEndpointOptions options)since it's not super obvious this listens to any API.DirectTlsEndpointlive in? Should it derive fromIPEndpoint?IPEndpoint.DirectTlsEndpointOptions, would it be more capable if we copiedTlsHandshakeCallbackOptions?HttpsConnectionAdapterOptionsis more declarative.HttpProtocolsproperty, we should.API Approved!
DirectTls: apply API-review-approved cosmetic changes
DeagleGross commentedon Jul 24, 2026
Note: current changes to the approved API from prototype at #67912:
DirectTls: apply API-review-approved cosmetic changes
halter73 commentedon Aug 11, 2026
Another thing worth noting that we didn't catch when approving the initial version of this API is that
DirectTlsEndpointOptionsneeds to live inKestrel.Core.dlldue to itsDirectTlsEndpointOptionsreference. This feels worse than just having theDirectTlsEndpointby itself live in the Core assembly. This might be a reason to instead add a marker interface or something to exclude the endpoint from the normal Socket transport. Then neither the endpoint nor the options would need to live in the Core assembly.[Experimental] DirectTls transport implementation (#67912)
DeagleGross commentedon Aug 17, 2026
Implemented at #67912