Skip to content

Commit e9b3c7d

Browse files
committed
Add docs for HTTP.Sys CBT hardening
1 parent 8a27499 commit e9b3c7d

3 files changed

Lines changed: 51 additions & 2 deletions

File tree

aspnetcore/fundamentals/servers/httpsys.md

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Learn about HTTP.sys, a web server for ASP.NET Core on Windows. Bui
66
monikerRange: '>= aspnetcore-2.1'
77
ms.author: tdykstra
88
ms.custom: mvc
9-
ms.date: 03/26/2026
9+
ms.date: 04/30/2026
1010
uid: fundamentals/servers/httpsys
1111
---
1212
# HTTP.sys web server implementation in ASP.NET Core
@@ -99,6 +99,29 @@ Http.Sys also supports sending an AltSvc HTTP/2 protocol message rather than a r
9999

100100
HTTP.sys delegates to kernel mode authentication with the Kerberos authentication protocol. User mode authentication isn't supported with Kerberos and HTTP.sys. The machine account must be used to decrypt the Kerberos token/ticket that's obtained from Active Directory and forwarded by the client to the server to authenticate the user. Register the Service Principal Name (SPN) for the host, not the user of the app.
101101

102+
### Enable channel binding token (CBT) hardening
103+
104+
Channel binding tokens (CBT) tie Windows authentication to the underlying TLS channel, which helps mitigate NTLM relay and man-in-the-middle attacks. For HTTPS endpoints that use Windows authentication with HTTP.sys, you can opt in to CBT hardening by setting the `Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening` AppContext switch to `true`.
105+
106+
Enable the switch in your project's `runtimeconfig.template.json` file:
107+
108+
```json
109+
{
110+
"configProperties": {
111+
"Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening": true
112+
}
113+
}
114+
```
115+
116+
Or set the switch programmatically before building the host in `Program.cs`:
117+
118+
```csharp
119+
AppContext.SetSwitch("Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening", true);
120+
```
121+
122+
> [!WARNING]
123+
> CBT hardening is off by default. Enabling it can cause Windows authentication to fail for clients or proxies that don't support channel binding. Test thoroughly in your environment before enabling in production.
124+
102125
### Support for kernel-mode response buffering
103126

104127
In some scenarios, high volumes of small writes with high latency can cause significant performance impact to `HTTP.sys`. This impact is due to the lack of a <xref:System.IO.Pipelines.Pipe> buffer in the `HTTP.sys` implementation. To improve performance in these scenarios, support for response buffering is included in `HTTP.sys`. Enable buffering by setting [HttpSysOptions.EnableKernelResponseBuffering](https://github.com/dotnet/aspnetcore/blob/main/src/Servers/HttpSys/src/HttpSysOptions.cs#L120) to `true`.

aspnetcore/fundamentals/servers/httpsys/includes/httpsys8-9.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,29 @@ Http.Sys also supports sending an AltSvc HTTP/2 protocol message rather than a r
7979

8080
HTTP.sys delegates to kernel mode authentication with the Kerberos authentication protocol. User mode authentication isn't supported with Kerberos and HTTP.sys. The machine account must be used to decrypt the Kerberos token/ticket that's obtained from Active Directory and forwarded by the client to the server to authenticate the user. Register the Service Principal Name (SPN) for the host, not the user of the app.
8181

82+
### Enable channel binding token (CBT) hardening
83+
84+
Channel binding tokens (CBT) tie Windows authentication to the underlying TLS channel, which helps mitigate NTLM relay and man-in-the-middle attacks. For HTTPS endpoints that use Windows authentication with HTTP.sys, you can opt in to CBT hardening by setting the `Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening` AppContext switch to `true`.
85+
86+
Enable the switch in your project's `runtimeconfig.template.json` file:
87+
88+
```json
89+
{
90+
"configProperties": {
91+
"Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening": true
92+
}
93+
}
94+
```
95+
96+
Or set the switch programmatically before building the host in `Program.cs`:
97+
98+
```csharp
99+
AppContext.SetSwitch("Microsoft.AspNetCore.Server.HttpSys.EnableCBTHardening", true);
100+
```
101+
102+
> [!WARNING]
103+
> CBT hardening is off by default. Enabling it can cause Windows authentication to fail for clients or proxies that don't support channel binding. Test thoroughly in your environment before enabling in production.
104+
82105
### Support for kernel-mode response buffering
83106

84107
In some scenarios, high volumes of small writes with high latency can cause significant performance impact to `HTTP.sys`. This impact is due to the lack of a <xref:System.IO.Pipelines.Pipe> buffer in the `HTTP.sys` implementation. To improve performance in these scenarios, support for response buffering is included in `HTTP.sys`. Enable buffering by setting [HttpSysOptions.EnableKernelResponseBuffering](https://github.com/dotnet/aspnetcore/blob/main/src/Servers/HttpSys/src/HttpSysOptions.cs#L120) to `true`.

aspnetcore/security/authentication/windowsauth.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Learn how to configure Windows Authentication in ASP.NET Core for I
55
monikerRange: '>= aspnetcore-3.1'
66
ms.author: wpickett
77
ms.custom: mvc
8-
ms.date: 10/17/2025
8+
ms.date: 04/30/2026
99
uid: security/authentication/windowsauth
1010
ms.ai: assisted
1111
---
@@ -262,6 +262,9 @@ The following code adds authentication and configures the app's web host to use
262262
> [!NOTE]
263263
> HTTP.sys delegates to [Kernel Mode](/windows-hardware/drivers/gettingstarted/user-mode-and-kernel-mode) authentication with the Kerberos authentication protocol. [User Mode](/windows-hardware/drivers/gettingstarted/user-mode-and-kernel-mode) authentication isn't supported with Kerberos and HTTP.sys. The machine account must be used to decrypt the Kerberos token/ticket that's obtained from Active Directory and forwarded by the client to the server to authenticate the user. Register the Service Principal Name (SPN) for the host, not the user of the app.
264264
265+
> [!TIP]
266+
> To further protect Windows authentication over HTTPS, consider enabling channel binding token (CBT) hardening. For details, see [Enable channel binding token (CBT) hardening](xref:fundamentals/servers/httpsys#enable-channel-binding-token-cbt-hardening).
267+
265268
<!-- DOC AUTHOR NOTE
266269
267270
The following hub.docker.com link is a valid URL,

0 commit comments

Comments
 (0)