Skip to content

DirectTls transport — public API #67909

Closed
Closed

Description

@DeagleGross

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 publishes ITlsApplicationProtocolFeature — all of which live in Microsoft.AspNetCore.Server.Kestrel.Core. Putting it in its own assembly lets it take that Kestrel.Core reference 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 behind SYSLIB5007) and requires OpenSSL (libssl) at runtime. Isolating that in its own assembly keeps the experimental surface — and its NoWarn (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 claims DirectTlsEndpoint endpoints; 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 DirectTlsEndpoint use this transport. Any regular IPEndPoint (or UseHttps endpoint) continues to use the default Kestrel transport, so DirectTls and the default transport can coexist in the same host.

Activity

  1. self-assigned this
    on Jul 20, 2026
  2. added
    api-suggestionEarly API idea and discussion, it is NOT ready for implementation
    area-networkingIncludes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions
    on Jul 20, 2026
  3. added this to the .NET 11 Planning milestone on Jul 20, 2026
  4. halter73 commented on Jul 21, 2026

    @halter73
    Member

    API Review Notes:

    • Should this be a new package? Should it be part of the shared framework.
      • It should be a new package like all our other transports. It shouldn't
    • It'd be nice if the socket epoll logic/configuration like DirectTlsTransportOptions.WorkerCount was moved to the runtime, but this is an experimental API
    • It's not much different than the Socket Transport's IOQueueCount. We don't need a static default of 4. We can base it on Environment.ProcessorCount
    • Should UseDirectTlsTransport be called UseDirectTls?
      • This aligns more with UseSockets and UseQuic.
      • We like this change.
    • Do we like all DirectTlsEndpoint constructors?
      • Let's remove DirectTlsEndpoint(int port, DirectTlsEndpointOptions options) since it's not super obvious this listens to any API.
    • What assembly should DirectTlsEndpoint live in? Should it derive from IPEndpoint?
      • It's convenient for logging and APIs that expose the endpoint if it remains an IPEndpoint.
      • Kestrel.Core.dll so that the Socket transport can exclude it.
    • For DirectTlsEndpointOptions, would it be more capable if we copied TlsHandshakeCallbackOptions?
      • Maybe, but we think that copying HttpsConnectionAdapterOptions is more declarative.
      • If we can get rid of the HttpProtocols property, we should.

    API Approved!

    // Kestrel.Core.dll
    
    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(IPEndPoint endpoint, DirectTlsEndpointOptions options);
    
        // Per-endpoint TLS configuration. Never null (a default instance is created by the first ctor).
        public DirectTlsEndpointOptions Options { get; }
    }
    
    // Kestrel.Transport.DirectTls.dll
    
    [Experimental("ASPNETCORE_DIRECTTLS_001", UrlFormat = "https://aka.ms/aspnetcore/directtls")]
    public sealed class DirectTlsEndpointOptions
    {
        public X509Certificate2? ServerCertificate { get; set; }
        public Func<ConnectionContext?, string?, X509Certificate2?>? ServerCertificateSelector { get; set; }
        public SslProtocols SslProtocols { get; set; }
        public ClientCertificateMode ClientCertificateMode { get; set; }
        public Func<X509Certificate2, X509Chain?, SslPolicyErrors, bool>? ClientCertificateValidation { get; set; }
        public Action<ConnectionContext, ReadOnlySequence<byte>>? TlsClientHelloBytesCallback { get; set; }
    }
    
    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 UseDirectTls(this IWebHostBuilder hostBuilder);
    
        // Register the transport and configure transport-wide options.
        public static IWebHostBuilder UseDirectTls(
            this IWebHostBuilder hostBuilder,
            Action<DirectTlsTransportOptions> configureOptions);
    }
  5. added
    api-approvedAPI was approved in API review, it can be implemented
    and removed
    api-suggestionEarly API idea and discussion, it is NOT ready for implementation
    on Jul 21, 2026
  6. DeagleGross commented on Jul 24, 2026

    @DeagleGross
    MemberAuthor

    Note: current changes to the approved API from prototype at #67912:

    // ── DirectTlsTransportOptions ──────────────────────────────────────────────
    - public int WorkerCount { get; set; } = 4;                                          // fixed default 4
    + public int WorkerCount { get; set; } = <Environment.ProcessorCount-derived>;        // heuristic default
    
      // ── DirectTlsEndpointOptions ───────────────────────────────────────────────
    - public HttpProtocols HttpProtocols { get; set; }                                   // now internal (set from ListenOptions.Protocols)
    + public System.TimeSpan HandshakeTimeout { get; set; }                              // NEW (default 10s; mirrors HttpsConnectionAdapterOptions)
    + public int? WorkerCount { get; set; }                                             // NEW per-endpoint override of DirectTlsTransportOptions.WorkerCount
  7. halter73 commented on Aug 11, 2026

    @halter73
    Member

    Another thing worth noting that we didn't catch when approving the initial version of this API is that DirectTlsEndpointOptions needs to live in Kestrel.Core.dll due to its DirectTlsEndpointOptions reference. This feels worse than just having the DirectTlsEndpoint by 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.

  8. DeagleGross commented on Aug 17, 2026

    @DeagleGross
    MemberAuthor

    Implemented at #67912

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

api-approvedAPI was approved in API review, it can be implementedapi-proposalarea-networkingIncludes servers, yarp, json patch, bedrock, websockets, http client factory, and http abstractions

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions