Add TLS channel binding token access to ITlsConnectionFeature (#67436)

Author: DeagleGross

src/Http/Http.Features/src/ITlsConnectionFeature.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Security.Authentication.ExtendedProtection;
 using System.Security.Cryptography.X509Certificates;
 
 namespace Microsoft.AspNetCore.Http.Features;
@@ -19,4 +20,35 @@ public interface ITlsConnectionFeature
     /// Asynchronously retrieves the client certificate, if any.
     /// </summary>
     Task<X509Certificate2?> GetClientCertificateAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Attempts to retrieve the RFC 5929 TLS channel binding token (CBT) bytes for the
+    /// requested <paramref name="kind"/> from the current connection.
+    /// </summary>
+    /// <param name="kind">The kind of channel binding to retrieve.</param>
+    /// <param name="channelBindingToken">
+    /// When this method returns <see langword="true"/>, contains the channel binding token
+    /// bytes; otherwise, an empty <see cref="ReadOnlyMemory{T}"/>.
+    /// </param>
+    /// <returns>
+    /// <see langword="true"/> if the requested channel binding is available;
+    /// <see langword="false"/> otherwise (for example: the connection is not TLS,
+    /// the requested <paramref name="kind"/> is not supported by the server, or
+    /// channel binding is not enabled in server configuration).
+    /// </returns>
+    /// <remarks>
+    /// <para>
+    /// Channel binding tokens let in-channel authentication protocols (such as
+    /// Kerberos or NTLM negotiated over HTTPS) bind themselves cryptographically
+    /// to the underlying TLS channel, mitigating authentication relay attacks.
+    /// See <see href="https://datatracker.ietf.org/doc/html/rfc5929"/> for the
+    /// specification and Microsoft's "Extended Protection for Authentication"
+    /// documentation for the Windows usage model.
+    /// </para>
+    /// </remarks>
+    bool TryGetChannelBindingBytes(ChannelBindingKind kind, out ReadOnlyMemory<byte> channelBindingToken)
+    {
+        channelBindingToken = default;
+        return false;
+    }
 }

src/Http/Http.Features/src/ITlsTokenBindingFeature.cs

@@ -1,6 +1,8 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using Microsoft.AspNetCore.Shared;
+
 namespace Microsoft.AspNetCore.Http.Features;
 
 /// <summary>
@@ -12,6 +14,7 @@ namespace Microsoft.AspNetCore.Http.Features;
 /// client's machine. See <see href="https://datatracker.ietf.org/doc/draft-popov-token-binding/"/>
 /// for more information.
 /// </remarks>
+[Obsolete(Obsoletions.TlsTokenBindingFeatureMessage, DiagnosticId = Obsoletions.TlsTokenBindingFeatureDiagId, UrlFormat = Obsoletions.AspNetCoreDeprecate010Url)]
 public interface ITlsTokenBindingFeature
 {
     /// <summary>

src/Http/Http.Features/src/Microsoft.AspNetCore.Http.Features.csproj

@@ -16,4 +16,8 @@
     <Reference Include="Microsoft.Net.Http.Headers" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Compile Include="$(SharedSourceRoot)Obsoletions.cs" LinkBase="Shared" />
+  </ItemGroup>
+
 </Project>

src/Http/Http.Features/src/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.AspNetCore.Http.Features.ITlsConnectionFeature.TryGetChannelBindingBytes(System.Security.Authentication.ExtendedProtection.ChannelBindingKind kind, out System.ReadOnlyMemory<byte> channelBindingToken) -> bool

src/Security/Authentication/Cookies/src/CookieAuthenticationHandler.cs

@@ -480,7 +480,9 @@ protected override async Task HandleChallengeAsync(AuthenticationProperties prop
 
     private string? GetTlsTokenBinding()
     {
+#pragma warning disable ASPDEPR010 // ITlsTokenBindingFeature is obsolete; kept for back-compat inside cookie auth handler.
         var binding = Context.Features.Get<ITlsTokenBindingFeature>()?.GetProvidedTokenBindingId();
+#pragma warning restore ASPDEPR010
         return binding == null ? null : Convert.ToBase64String(binding);
     }
 }

src/Servers/HttpSys/samples/TlsFeaturesObserve/Program.cs

@@ -2,9 +2,11 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Buffers;
+using System.Buffers.Binary;
 using System.Diagnostics;
 using System.Reflection;
 using System.Runtime.InteropServices;
+using System.Security.Authentication.ExtendedProtection;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Connections.Features;
 using Microsoft.AspNetCore.Hosting;
@@ -23,10 +25,63 @@
     options.UrlPrefixes.Add("https://*:6000");
     options.Authentication.Schemes = AuthenticationSchemes.None;
     options.Authentication.AllowAnonymous = true;
+
+    // Expose the RFC 5929 TLS channel binding token
+    options.HttpAuthenticationHardeningLevel = HttpAuthenticationHardeningLevel.Medium;
 });
 
 var app = builder.Build();
 
+// Example middleware using ITlsConnectionFeature.TryGetChannelBindingBytes to load the channel binding token bytes and parse them.
+app.Use(async (context, next) =>
+{
+    var tlsFeature = context.Features.Get<ITlsConnectionFeature>();
+    if (tlsFeature is not null && tlsFeature.TryGetChannelBindingBytes(ChannelBindingKind.Endpoint, out var bytes))
+    {
+        // Parse the SEC_CHANNEL_BINDINGS header so we can see the RFC 5929 (https://datatracker.ietf.org/doc/html/rfc5929)
+        // application data ("tls-server-end-point:" + SHA-256 of the cert).
+        var span = bytes.Span;
+        if (span.Length < 32)
+        {
+            await context.Response.WriteAsync("\tITlsConnectionFeature.TryGetChannelBindingBytes(Endpoint) returned an unexpected payload (< 32 bytes).\n\n");
+            await next(context);
+            return;
+        }
+
+        var appLen = BinaryPrimitives.ReadUInt32LittleEndian(span.Slice(24, 4));
+        var appOff = BinaryPrimitives.ReadUInt32LittleEndian(span.Slice(28, 4));
+        if (appOff + appLen > (uint)span.Length)
+        {
+            await context.Response.WriteAsync("\tITlsConnectionFeature.TryGetChannelBindingBytes(Endpoint) returned an unexpected payload (appdata outside buffer).\n\n");
+            await next(context);
+            return;
+        }
+
+        var app = span.Slice((int)appOff, (int)appLen);
+        var asciiPrefix = System.Text.Encoding.ASCII.GetString(app[..Math.Min(21, app.Length)]);
+        var hash = Convert.ToHexString(app[Math.Min(21, app.Length)..]);
+
+        await context.Response.WriteAsync(
+            $"""
+                ITlsConnectionFeature.TryGetChannelBindingBytes(Endpoint)
+                ----------------------------------------------------------
+                raw length      = {bytes.Length} bytes (SEC_CHANNEL_BINDINGS header + appdata)
+                appdata length  = {appLen}
+                appdata offset  = {appOff}
+                ASCII prefix    = "{asciiPrefix}"
+                cert hash (hex) = {hash}
+
+
+            """);
+    }
+    else
+    {
+        await context.Response.WriteAsync("\tITlsConnectionFeature.TryGetChannelBindingBytes(Endpoint) returned false \n\n");
+    }
+
+    await next(context);
+});
+
 // Example middleware using TryGetTlsClientHello API to query TLS Client Hello raw bytes.
 app.Use(async (context, next) =>
 {

src/Servers/HttpSys/samples/TlsFeaturesObserve/TlsFeaturesObserve.csproj

@@ -13,6 +13,7 @@
     <Reference Include="Microsoft.AspNetCore.Authentication.Abstractions" />
     <Reference Include="Microsoft.AspNetCore.Authentication.Core" />
     <Reference Include="Microsoft.AspNetCore.Authorization.Policy" />
+    <Reference Include="Microsoft.AspNetCore.Cors" />
     <Reference Include="Microsoft.AspNetCore.Diagnostics" />
     <Reference Include="Microsoft.AspNetCore.Diagnostics.Abstractions" />
     <Reference Include="Microsoft.AspNetCore.HostFiltering" />

src/Servers/HttpSys/src/HttpAuthenticationHardeningLevel.cs

@@ -0,0 +1,42 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Server.HttpSys;
+
+/// <summary>
+/// Specifies the Http.Sys authentication hardening level that controls how strictly
+/// HTTP authentication (Kerberos/NTLM) is validated against the underlying TLS channel.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Corresponds to the Win32
+/// <see href="https://learn.microsoft.com/windows/win32/api/http/ne-http-http_authentication_hardening_levels"><c>HTTP_AUTHENTICATION_HARDENING_LEVELS</c></see>
+/// enumeration applied to the URL group's <c>HttpServerChannelBindProperty</c>.
+/// </para>
+/// <para>
+/// When set to <see cref="Medium"/> or <see cref="Strict"/>, Http.Sys is also
+/// instructed to attach the per-request <c>HTTP_REQUEST_CHANNEL_BIND_STATUS</c>
+/// so the application can retrieve the RFC 5929 TLS channel binding token via
+/// <see cref="Microsoft.AspNetCore.Http.Features.ITlsConnectionFeature.TryGetChannelBindingBytes"/>.
+/// </para>
+/// </remarks>
+public enum HttpAuthenticationHardeningLevel
+{
+    /// <summary>
+    /// Http.Sys does not enforce channel binding validation and does not expose the RFC 5929 TLS channel binding token to the application.
+    /// This matches the pre-hardening default behavior.
+    /// </summary>
+    Legacy = 0,
+
+    /// <summary>
+    /// Http.Sys validates channel binding tokens when clients supply them but tolerates their absence.
+    /// The per-request TLS channel binding token is exposed to the application.
+    /// </summary>
+    Medium = 1,
+
+    /// <summary>
+    /// Http.Sys requires channel binding tokens on authenticated requests and rejects those without one.
+    /// The per-request TLS channel binding token is exposed to the application.
+    /// </summary>
+    Strict = 2,
+}

src/Servers/HttpSys/src/HttpSysOptions.cs

@@ -120,6 +120,21 @@ public string? RequestQueueName
     /// </summary>
     public bool EnableKernelResponseBuffering { get; set; }
 
+    /// <summary>
+    /// Configures the Http.Sys authentication hardening level. Non-<see cref="HttpAuthenticationHardeningLevel.Legacy"/>
+    /// values instruct Http.Sys to validate the RFC 5929 TLS channel binding token (CBT) against
+    /// authenticated requests and to expose the per-request CBT to the application via
+    /// <see cref="Microsoft.AspNetCore.Http.Features.ITlsConnectionFeature.TryGetChannelBindingBytes"/>.
+    /// The default is <see cref="HttpAuthenticationHardeningLevel.Medium"/>.
+    /// </summary>
+    /// <remarks>
+    /// Setting this to <see cref="HttpAuthenticationHardeningLevel.Medium"/> or
+    /// <see cref="HttpAuthenticationHardeningLevel.Strict"/> both raises the hardening
+    /// level and sets the <c>HTTP_CHANNEL_BIND_SECURE_CHANNEL_TOKEN</c> flag on the URL
+    /// group's <c>HttpServerChannelBindProperty</c>.
+    /// </remarks>
+    public HttpAuthenticationHardeningLevel HttpAuthenticationHardeningLevel { get; set; } = HttpAuthenticationHardeningLevel.Medium;
+
     /// <summary>
     /// Gets or sets the maximum number of concurrent connections to accept. Set `-1` for infinite.
     /// Set to `null` to use the registry's machine-wide setting.
@@ -276,5 +291,6 @@ internal void Apply(UrlGroup urlGroup, RequestQueue? requestQueue)
 
         Authentication.SetUrlGroupSecurity(urlGroup);
         Timeouts.SetUrlGroupTimeouts(urlGroup);
+        urlGroup.SetChannelBindingProperty(HttpAuthenticationHardeningLevel);
     }
 }

src/Servers/HttpSys/src/NativeInterop/UrlGroup.cs

@@ -12,14 +12,13 @@ namespace Microsoft.AspNetCore.Server.HttpSys;
 
 internal sealed partial class UrlGroup : IDisposable
 {
-    private static readonly int BindingInfoSize =
-        Marshal.SizeOf<HTTP_BINDING_INFO>();
-    private static readonly int QosInfoSize =
-        Marshal.SizeOf<HTTP_QOS_SETTING_INFO>();
-    private static readonly int RequestPropertyInfoSize =
-        Marshal.SizeOf<HTTP_BINDING_INFO>();
-    private static readonly int ChannelBindInfoSize =
-        Marshal.SizeOf<HTTP_CHANNEL_BIND_INFO>();
+    // See https://learn.microsoft.com/windows/win32/api/http/ns-http-http_channel_bind_info
+    private const uint HTTP_CHANNEL_BIND_SECURE_CHANNEL_TOKEN = 0x00000008;
+
+    private static readonly int BindingInfoSize = Marshal.SizeOf<HTTP_BINDING_INFO>();
+    private static readonly int QosInfoSize = Marshal.SizeOf<HTTP_QOS_SETTING_INFO>();
+    private static readonly int RequestPropertyInfoSize = Marshal.SizeOf<HTTP_BINDING_INFO>();
+    private static readonly int ChannelBindInfoSize = Marshal.SizeOf<HTTP_CHANNEL_BIND_INFO>();
 
     private readonly ILogger _logger;
 
@@ -44,17 +43,30 @@ internal unsafe UrlGroup(ServerSession serverSession, RequestQueue requestQueue,
 
         Debug.Assert(urlGroupId != 0, "Invalid id returned by HttpCreateUrlGroup");
         Id = urlGroupId;
+    }
 
-        if (AppContext.TryGetSwitch("Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening", out var enabled) && enabled)
+    // Sets HttpServerChannelBindProperty with the requested hardening level and the HTTP_CHANNEL_BIND_SECURE_CHANNEL_TOKEN flag
+    // so the per-request CBT is delivered to the app.
+    internal unsafe void SetChannelBindingProperty(HttpAuthenticationHardeningLevel level)
+    {
+        var info = new HTTP_CHANNEL_BIND_INFO
         {
-            var channelBindingSettings = new HTTP_CHANNEL_BIND_INFO
+            Hardening = level switch
             {
-                Hardening = HTTP_AUTHENTICATION_HARDENING_LEVELS.HttpAuthenticationHardeningMedium,
-                ServiceNames = (HTTP_SERVICE_BINDING_BASE**)IntPtr.Zero,
-                NumberOfServiceNames = 0,
-            };
-            SetProperty(HTTP_SERVER_PROPERTY.HttpServerChannelBindProperty, new(&channelBindingSettings), (uint)ChannelBindInfoSize);
-        }
+                HttpAuthenticationHardeningLevel.Strict => HTTP_AUTHENTICATION_HARDENING_LEVELS.HttpAuthenticationHardeningStrict,
+                HttpAuthenticationHardeningLevel.Legacy => HTTP_AUTHENTICATION_HARDENING_LEVELS.HttpAuthenticationHardeningLegacy,
+                HttpAuthenticationHardeningLevel.Medium or _ => HTTP_AUTHENTICATION_HARDENING_LEVELS.HttpAuthenticationHardeningMedium,
+            },
+            ServiceNames = (HTTP_SERVICE_BINDING_BASE**)IntPtr.Zero,
+            NumberOfServiceNames = 0,
+
+            // optimize: Flags control if CBT is included in NativeRequest, and if legacy level is used, no point to load the CBT data.
+            Flags = level == HttpAuthenticationHardeningLevel.Legacy
+                ? default
+                : HTTP_CHANNEL_BIND_SECURE_CHANNEL_TOKEN,
+        };
+
+        SetProperty(HTTP_SERVER_PROPERTY.HttpServerChannelBindProperty, new IntPtr(&info), (uint)ChannelBindInfoSize, throwOnError: false);
     }
 
     internal ulong Id { get; private set; }