From 14b4b40f076dde913753bf1a2c3f2a576b1d2c58 Mon Sep 17 00:00:00 2001 From: Natalia Kondratyeva Date: Thu, 24 Apr 2025 16:41:47 +0200 Subject: [PATCH 01/13] Update http3.md --- .../fundamentals/servers/kestrel/http3.md | 36 +++++-------------- 1 file changed, 9 insertions(+), 27 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index 48d54e70258f..3f2b46d4ea46 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -20,29 +20,19 @@ uid: fundamentals/servers/kestrel/http3 > [!IMPORTANT] > Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2. -## HTTP/3 requirements - -HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols. - -### Windows - -* Windows 11 Build 22000 or later OR Windows Server 2022. -* TLS 1.3 or later connection. - -### Linux - -* `libmsquic` package installed. +## HTTP/3 benefits -`libmsquic` is published via Microsoft's official Linux package repository at `packages.microsoft.com`. To install this package: +HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a transport technology developed alongside HTTP/3 called [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html). -1. Add the `packages.microsoft.com` repository. See [Linux Software Repository for Microsoft Products](/windows-server/administration/linux-package-repository-for-microsoft-software) for instructions. -2. Install the `libmsquic` package using the distro's package manager. For example, `apt install libmsquic=1.9*` on Ubuntu. +HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: -**Note:** .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes. +* Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster. +* Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost. +* Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions yet. It may be available in a future release. -### macOS +## HTTP/3 requirements -HTTP/3 isn't currently supported on macOS and may be available in a future release. +HTTP/3 uses QUIC as its transport protocol. The ASP.NET Core implementation of HTTP/3 depends on [MsQuic](https://github.com/microsoft/msquic) to provide QUIC functionality. As a result, ASP.NET Core support of HTTP/3 depends on MsQuic platform requirements. For more information on how to install **MsQuic**, see [QUIC Platform dependencies](/dotnet/fundamentals/networking/quic/quic-overview#platform-dependencies). If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols. ## Getting started @@ -71,15 +61,7 @@ HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the [`alt-svc`](h * Set [`HttpRequestMessage.Version`](xref:System.Net.Http.HttpRequestMessage.Version) to 3.0, or * Set [`HttpRequestMessage.VersionPolicy`](xref:System.Net.Http.HttpRequestMessage.VersionPolicy) to [`HttpVersionPolicy.RequestVersionOrHigher`](xref:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher). -## HTTP/3 benefits - -HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called [QUIC](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport-34). - -HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: - -* Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster. -* Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost. -* Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 8. It may be available in a future release. +For more information on how to use HTTP/3 with `HttpClient`, see [HTTP/3 with .NET](/dotnet/core/extensions/httpclient-http3). :::moniker-end From 02c5b944114d5de3d98ebfd55cd80f86178d4d55 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 11:40:58 -0600 Subject: [PATCH 02/13] Update http3.md --- .../fundamentals/servers/kestrel/http3.md | 33 +++++++++++++++---- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index 3f2b46d4ea46..7bd06f60c051 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -22,13 +22,32 @@ uid: fundamentals/servers/kestrel/http3 ## HTTP/3 benefits -HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a transport technology developed alongside HTTP/3 called [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html). - -HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: - -* Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster. -* Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost. -* Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions yet. It may be available in a future release. +`HTTP/3`: + +* Is the latest version of the Hypertext Transfer Protocol. +* Builds on the strengths of `HTTP/2` while addressing some of its limitations, particularly in terms of performance, latency, reliability, and security. + ++---------------+-------------------------+-------------------------+ +| Feature | `HTTP/2` | `HTTP/3` | ++---------------+-------------------------+-------------------------+ +| Transport | Uses [TCP](https://developer.mozilla.org/docs/Glossary/TCP) | Uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) | +| Layer | | | +| Connection | Slower due to TCP + TLS | Faster with 0-RTT QUIC | +| Setup | handshake | handshakes | +| Head-of-Line | Affected by TCP-level | Eliminated with QUIC | +| Blocking | blocking | stream multiplexing | +| Encryption | TLS over TCP | TLS is built into QUIC | ++---------------+-------------------------+-------------------------+ + + +The key differences from `HTTP/2` to `HTTP/3` are: + +* **Transport Protocol**: `HTTP/3` uses QUIC instead of TCP. QUIC offers improved performance, lower latency, and better reliability, especially on mobile and lossy networks. +* **Head-of-Line Blocking**: `HTTP/2` can suffer from head-of-line blocking at the TCP level, where a delay in one stream can affect others. `HTTP/3`, with QUIC, provides independent streams, so packet loss in one stream doesn't stall others. +* **Connection Establishment**: `HTTP/3` with QUIC can establish connections faster, sometimes in zero round-trip time (0-RTT) for returning clients, as it combines transport and encryption handshakes. +* **Encryption**: `HTTP/3` mandates TLS 1.3 encryption, providing enhanced security by default, whereas it's optional in `HTTP/2`. +* **Multiplexing**: While both support multiplexing, `HTTP/3`'s implementation with QUIC is more efficient and avoids the TCP-level head-of-line blocking issues. +* **Connection Migration**: QUIC in `HTTP/3` allows connections to persist even when a client's IP address changes (like switching from Wi-Fi to cellular), improving mobile user experience. ## HTTP/3 requirements From a28d0ab901e835938d8b2eecf12dbbb8d2b8768b Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 11:59:36 -0600 Subject: [PATCH 03/13] Updated kestrel HTTP/3 -2 --- .../fundamentals/servers/kestrel/http3.md | 51 +++++++++---------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index 7bd06f60c051..c2f57450d9ea 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -5,7 +5,7 @@ description: Learn about using HTTP/3 with Kestrel, the cross-platform web serve monikerRange: '>= aspnetcore-6.0' ms.author: wigodbe ms.custom: mvc, linux-related-content -ms.date: 08/24/2023 +ms.date: 4/25/2024 uid: fundamentals/servers/kestrel/http3 --- @@ -20,38 +20,29 @@ uid: fundamentals/servers/kestrel/http3 > [!IMPORTANT] > Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2. -## HTTP/3 benefits +## HTTP/3 requirements -`HTTP/3`: +HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols. -* Is the latest version of the Hypertext Transfer Protocol. -* Builds on the strengths of `HTTP/2` while addressing some of its limitations, particularly in terms of performance, latency, reliability, and security. +### Windows -+---------------+-------------------------+-------------------------+ -| Feature | `HTTP/2` | `HTTP/3` | -+---------------+-------------------------+-------------------------+ -| Transport | Uses [TCP](https://developer.mozilla.org/docs/Glossary/TCP) | Uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) | -| Layer | | | -| Connection | Slower due to TCP + TLS | Faster with 0-RTT QUIC | -| Setup | handshake | handshakes | -| Head-of-Line | Affected by TCP-level | Eliminated with QUIC | -| Blocking | blocking | stream multiplexing | -| Encryption | TLS over TCP | TLS is built into QUIC | -+---------------+-------------------------+-------------------------+ +* Windows 11 Build 22000 or later OR Windows Server 2022. +* TLS 1.3 or later connection. +### Linux -The key differences from `HTTP/2` to `HTTP/3` are: +* `libmsquic` package installed. -* **Transport Protocol**: `HTTP/3` uses QUIC instead of TCP. QUIC offers improved performance, lower latency, and better reliability, especially on mobile and lossy networks. -* **Head-of-Line Blocking**: `HTTP/2` can suffer from head-of-line blocking at the TCP level, where a delay in one stream can affect others. `HTTP/3`, with QUIC, provides independent streams, so packet loss in one stream doesn't stall others. -* **Connection Establishment**: `HTTP/3` with QUIC can establish connections faster, sometimes in zero round-trip time (0-RTT) for returning clients, as it combines transport and encryption handshakes. -* **Encryption**: `HTTP/3` mandates TLS 1.3 encryption, providing enhanced security by default, whereas it's optional in `HTTP/2`. -* **Multiplexing**: While both support multiplexing, `HTTP/3`'s implementation with QUIC is more efficient and avoids the TCP-level head-of-line blocking issues. -* **Connection Migration**: QUIC in `HTTP/3` allows connections to persist even when a client's IP address changes (like switching from Wi-Fi to cellular), improving mobile user experience. +`libmsquic` is published via Microsoft's official Linux package repository at `packages.microsoft.com`. To install this package: -## HTTP/3 requirements +1. Add the `packages.microsoft.com` repository. See [Linux Software Repository for Microsoft Products](/windows-server/administration/linux-package-repository-for-microsoft-software) for instructions. +2. Install the `libmsquic` package using the distro's package manager. For example, `apt install libmsquic=1.9*` on Ubuntu. + +**Note:** .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes. + +### macOS -HTTP/3 uses QUIC as its transport protocol. The ASP.NET Core implementation of HTTP/3 depends on [MsQuic](https://github.com/microsoft/msquic) to provide QUIC functionality. As a result, ASP.NET Core support of HTTP/3 depends on MsQuic platform requirements. For more information on how to install **MsQuic**, see [QUIC Platform dependencies](/dotnet/fundamentals/networking/quic/quic-overview#platform-dependencies). If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols. +HTTP/3 isn't currently supported on macOS and may be available in a future release. ## Getting started @@ -80,7 +71,15 @@ HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the [`alt-svc`](h * Set [`HttpRequestMessage.Version`](xref:System.Net.Http.HttpRequestMessage.Version) to 3.0, or * Set [`HttpRequestMessage.VersionPolicy`](xref:System.Net.Http.HttpRequestMessage.VersionPolicy) to [`HttpVersionPolicy.RequestVersionOrHigher`](xref:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher). -For more information on how to use HTTP/3 with `HttpClient`, see [HTTP/3 with .NET](/dotnet/core/extensions/httpclient-http3). +## HTTP/3 benefits + +HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called [QUIC](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport-34). + +HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: + +* Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster. +* Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost. +* Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 8. It may be available in a future release. :::moniker-end From 7b7d3154d93926b87209d0b115e5c0ea65dc4728 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 12:05:57 -0600 Subject: [PATCH 04/13] copy V 8, moniker prep --- .../fundamentals/servers/kestrel/http3.md | 2 + .../servers/kestrel/includes/http-8.md | 69 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 aspnetcore/fundamentals/servers/kestrel/includes/http-8.md diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index c2f57450d9ea..01355872adb5 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -83,4 +83,6 @@ HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: :::moniker-end +[!INCLUDE[](~/fundamentals/servers/kestrel/includes/http3-8.md)] + [!INCLUDE[](~/fundamentals/servers/kestrel/includes/http3-6-7.md)] diff --git a/aspnetcore/fundamentals/servers/kestrel/includes/http-8.md b/aspnetcore/fundamentals/servers/kestrel/includes/http-8.md new file mode 100644 index 000000000000..a4d4cc4e54f4 --- /dev/null +++ b/aspnetcore/fundamentals/servers/kestrel/includes/http-8.md @@ -0,0 +1,69 @@ +:::moniker range="= aspnetcore-8.0" + +[HTTP/3](https://datatracker.ietf.org/doc/rfc9114/) is an approved standard and the third major version of HTTP. This article discusses the requirements for HTTP/3. HTTP/3 is fully supported in ASP.NET Core 7.0 and later. + +> [!IMPORTANT] +> Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2. + +## HTTP/3 requirements + +HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols. + +### Windows + +* Windows 11 Build 22000 or later OR Windows Server 2022. +* TLS 1.3 or later connection. + +### Linux + +* `libmsquic` package installed. + +`libmsquic` is published via Microsoft's official Linux package repository at `packages.microsoft.com`. To install this package: + +1. Add the `packages.microsoft.com` repository. See [Linux Software Repository for Microsoft Products](/windows-server/administration/linux-package-repository-for-microsoft-software) for instructions. +2. Install the `libmsquic` package using the distro's package manager. For example, `apt install libmsquic=1.9*` on Ubuntu. + +**Note:** .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes. + +### macOS + +HTTP/3 isn't currently supported on macOS and may be available in a future release. + +## Getting started + +HTTP/3 is not enabled by default. Add configuration to `Program.cs` to enable HTTP/3. + +:::code language="csharp" source="samples/6.x/KestrelSample/Snippets/Program.cs" id="snippet_Http3" highlight="7-8"::: + +The preceding code configures port 5001 to: + +* Use HTTP/3 alongside HTTP/1.1 and HTTP/2 by specifying `HttpProtocols.Http1AndHttp2AndHttp3`. +* Enable HTTPS with `UseHttps`. HTTP/3 requires HTTPS. + +Because not all routers, firewalls, and proxies properly support HTTP/3, HTTP/3 should be configured together with HTTP/1.1 and HTTP/2. This can be done by specifying [`HttpProtocols.Http1AndHttp2AndHttp3`](xref:Microsoft.AspNetCore.Server.Kestrel.Core.HttpProtocols.Http1AndHttp2AndHttp3) as an endpoint's supported protocols. + +For more information, see . + +## Alt-svc + +HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the [`alt-svc`](https://developer.mozilla.org/docs/Web/HTTP/Headers/Alt-Svc) header. That means the first request will normally use HTTP/1.1 or HTTP/2 before switching to HTTP/3. Kestrel automatically adds the `alt-svc` header if HTTP/3 is enabled. + +## Localhost testing + +* Browsers don't allow self-signed certificates on HTTP/3, such as the Kestrel development certificate. +* `HttpClient` can be used for localhost/loopback testing in .NET 6 or later. Extra configuration is required when using `HttpClient` to make an HTTP/3 request: + + * Set [`HttpRequestMessage.Version`](xref:System.Net.Http.HttpRequestMessage.Version) to 3.0, or + * Set [`HttpRequestMessage.VersionPolicy`](xref:System.Net.Http.HttpRequestMessage.VersionPolicy) to [`HttpVersionPolicy.RequestVersionOrHigher`](xref:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher). + +## HTTP/3 benefits + +HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called [QUIC](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport-34). + +HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: + +* Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster. +* Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost. +* Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 8. It may be available in a future release. + +:::moniker-end From bcdcaebdb97daa18d1715c9cbd697e3f0d62e3e1 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 12:09:20 -0600 Subject: [PATCH 05/13] copy V 8, moniker prep --- aspnetcore/fundamentals/servers/kestrel/http3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index 01355872adb5..bc1874362c02 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -13,7 +13,7 @@ uid: fundamentals/servers/kestrel/http3 [!INCLUDE[](~/includes/not-latest-version.md)] -:::moniker range=">= aspnetcore-8.0" +:::moniker range="> aspnetcore-8.0" [HTTP/3](https://datatracker.ietf.org/doc/rfc9114/) is an approved standard and the third major version of HTTP. This article discusses the requirements for HTTP/3. HTTP/3 is fully supported in ASP.NET Core 7.0 and later. From f75b0269f99da288754b5cd9fb7b41e919fabb96 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 12:13:40 -0600 Subject: [PATCH 06/13] copy V 8, moniker prep --- .../servers/kestrel/includes/{http-8.md => http3-8.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename aspnetcore/fundamentals/servers/kestrel/includes/{http-8.md => http3-8.md} (100%) diff --git a/aspnetcore/fundamentals/servers/kestrel/includes/http-8.md b/aspnetcore/fundamentals/servers/kestrel/includes/http3-8.md similarity index 100% rename from aspnetcore/fundamentals/servers/kestrel/includes/http-8.md rename to aspnetcore/fundamentals/servers/kestrel/includes/http3-8.md From 67b93ab5ffa6b5d7350a95be8cc6b3402dc3ad68 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 13:35:51 -0600 Subject: [PATCH 07/13] copy V 8, moniker prep --- .../fundamentals/servers/kestrel/http3.md | 4 +- .../servers/kestrel/includes/http3-8.md | 69 ------------------- 2 files changed, 1 insertion(+), 72 deletions(-) delete mode 100644 aspnetcore/fundamentals/servers/kestrel/includes/http3-8.md diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index bc1874362c02..c2f57450d9ea 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -13,7 +13,7 @@ uid: fundamentals/servers/kestrel/http3 [!INCLUDE[](~/includes/not-latest-version.md)] -:::moniker range="> aspnetcore-8.0" +:::moniker range=">= aspnetcore-8.0" [HTTP/3](https://datatracker.ietf.org/doc/rfc9114/) is an approved standard and the third major version of HTTP. This article discusses the requirements for HTTP/3. HTTP/3 is fully supported in ASP.NET Core 7.0 and later. @@ -83,6 +83,4 @@ HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: :::moniker-end -[!INCLUDE[](~/fundamentals/servers/kestrel/includes/http3-8.md)] - [!INCLUDE[](~/fundamentals/servers/kestrel/includes/http3-6-7.md)] diff --git a/aspnetcore/fundamentals/servers/kestrel/includes/http3-8.md b/aspnetcore/fundamentals/servers/kestrel/includes/http3-8.md deleted file mode 100644 index a4d4cc4e54f4..000000000000 --- a/aspnetcore/fundamentals/servers/kestrel/includes/http3-8.md +++ /dev/null @@ -1,69 +0,0 @@ -:::moniker range="= aspnetcore-8.0" - -[HTTP/3](https://datatracker.ietf.org/doc/rfc9114/) is an approved standard and the third major version of HTTP. This article discusses the requirements for HTTP/3. HTTP/3 is fully supported in ASP.NET Core 7.0 and later. - -> [!IMPORTANT] -> Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2. - -## HTTP/3 requirements - -HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols. - -### Windows - -* Windows 11 Build 22000 or later OR Windows Server 2022. -* TLS 1.3 or later connection. - -### Linux - -* `libmsquic` package installed. - -`libmsquic` is published via Microsoft's official Linux package repository at `packages.microsoft.com`. To install this package: - -1. Add the `packages.microsoft.com` repository. See [Linux Software Repository for Microsoft Products](/windows-server/administration/linux-package-repository-for-microsoft-software) for instructions. -2. Install the `libmsquic` package using the distro's package manager. For example, `apt install libmsquic=1.9*` on Ubuntu. - -**Note:** .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes. - -### macOS - -HTTP/3 isn't currently supported on macOS and may be available in a future release. - -## Getting started - -HTTP/3 is not enabled by default. Add configuration to `Program.cs` to enable HTTP/3. - -:::code language="csharp" source="samples/6.x/KestrelSample/Snippets/Program.cs" id="snippet_Http3" highlight="7-8"::: - -The preceding code configures port 5001 to: - -* Use HTTP/3 alongside HTTP/1.1 and HTTP/2 by specifying `HttpProtocols.Http1AndHttp2AndHttp3`. -* Enable HTTPS with `UseHttps`. HTTP/3 requires HTTPS. - -Because not all routers, firewalls, and proxies properly support HTTP/3, HTTP/3 should be configured together with HTTP/1.1 and HTTP/2. This can be done by specifying [`HttpProtocols.Http1AndHttp2AndHttp3`](xref:Microsoft.AspNetCore.Server.Kestrel.Core.HttpProtocols.Http1AndHttp2AndHttp3) as an endpoint's supported protocols. - -For more information, see . - -## Alt-svc - -HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the [`alt-svc`](https://developer.mozilla.org/docs/Web/HTTP/Headers/Alt-Svc) header. That means the first request will normally use HTTP/1.1 or HTTP/2 before switching to HTTP/3. Kestrel automatically adds the `alt-svc` header if HTTP/3 is enabled. - -## Localhost testing - -* Browsers don't allow self-signed certificates on HTTP/3, such as the Kestrel development certificate. -* `HttpClient` can be used for localhost/loopback testing in .NET 6 or later. Extra configuration is required when using `HttpClient` to make an HTTP/3 request: - - * Set [`HttpRequestMessage.Version`](xref:System.Net.Http.HttpRequestMessage.Version) to 3.0, or - * Set [`HttpRequestMessage.VersionPolicy`](xref:System.Net.Http.HttpRequestMessage.VersionPolicy) to [`HttpVersionPolicy.RequestVersionOrHigher`](xref:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher). - -## HTTP/3 benefits - -HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called [QUIC](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport-34). - -HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: - -* Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster. -* Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost. -* Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 8. It may be available in a future release. - -:::moniker-end From 91e5fee9d388bbd502ad0f3a0b62096f0cb52a73 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 13:39:43 -0600 Subject: [PATCH 08/13] Update Kestrel HTTP/3 docs --- .../fundamentals/servers/kestrel/http3.md | 50 ++++++++----------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index c2f57450d9ea..741a453fc773 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -20,29 +20,33 @@ uid: fundamentals/servers/kestrel/http3 > [!IMPORTANT] > Apps configured to take advantage of HTTP/3 should be designed to also support HTTP/1.1 and HTTP/2. -## HTTP/3 requirements - -HTTP/3 has different requirements depending on the operating system. If the platform that Kestrel is running on doesn't have all the requirements for HTTP/3, then it's disabled, and Kestrel will fall back to other HTTP protocols. - -### Windows - -* Windows 11 Build 22000 or later OR Windows Server 2022. -* TLS 1.3 or later connection. - -### Linux - -* `libmsquic` package installed. +## HTTP/3 benefits -`libmsquic` is published via Microsoft's official Linux package repository at `packages.microsoft.com`. To install this package: +`HTTP/3`: -1. Add the `packages.microsoft.com` repository. See [Linux Software Repository for Microsoft Products](/windows-server/administration/linux-package-repository-for-microsoft-software) for instructions. -2. Install the `libmsquic` package using the distro's package manager. For example, `apt install libmsquic=1.9*` on Ubuntu. +* Is the latest version of the Hypertext Transfer Protocol. +* Builds on the strengths of `HTTP/2` while addressing some of its limitations, particularly in terms of performance, latency, reliability, and security. -**Note:** .NET 6 is only compatible with the 1.9.x versions of libmsquic. Libmsquic 2.x is not compatible due to breaking changes. Libmsquic receives updates to 1.9.x when needed to incorporate security fixes. ++---------------+-------------------------+-------------------------+ +| Feature | `HTTP/2` | `HTTP/3` | ++---------------+-------------------------+-------------------------+ +| Transport | Uses [TCP](https://developer.mozilla.org/docs/Glossary/TCP) | Uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) | +| Layer | | | +| Connection | Slower due to TCP + TLS | Faster with 0-RTT QUIC | +| Setup | handshake | handshakes | +| Head-of-Line | Affected by TCP-level | Eliminated with QUIC | +| Blocking | blocking | stream multiplexing | +| Encryption | TLS over TCP | TLS is built into QUIC | ++---------------+-------------------------+-------------------------+ -### macOS +The key differences from `HTTP/2` to `HTTP/3` are: -HTTP/3 isn't currently supported on macOS and may be available in a future release. +* **Transport Protocol**: `HTTP/3` uses QUIC instead of TCP. QUIC offers improved performance, lower latency, and better reliability, especially on mobile and lossy networks. +* **Head-of-Line Blocking**: `HTTP/2` can suffer from head-of-line blocking at the TCP level, where a delay in one stream can affect others. `HTTP/3`, with QUIC, provides independent streams, so packet loss in one stream doesn't stall others. +* **Connection Establishment**: `HTTP/3` with QUIC can establish connections faster, sometimes in zero round-trip time (0-RTT) for returning clients, as it combines transport and encryption handshakes. +* **Encryption**: `HTTP/3` mandates TLS 1.3 encryption, providing enhanced security by default, whereas it's optional in `HTTP/2`. +* **Multiplexing**: While both support multiplexing, `HTTP/3`'s implementation with QUIC is more efficient and avoids the TCP-level head-of-line blocking issues. +* **Connection Migration**: QUIC in `HTTP/3` allows connections to persist even when a client's IP address changes (like switching from Wi-Fi to cellular), improving mobile user experience. ## Getting started @@ -71,16 +75,6 @@ HTTP/3 is discovered as an upgrade from HTTP/1.1 or HTTP/2 via the [`alt-svc`](h * Set [`HttpRequestMessage.Version`](xref:System.Net.Http.HttpRequestMessage.Version) to 3.0, or * Set [`HttpRequestMessage.VersionPolicy`](xref:System.Net.Http.HttpRequestMessage.VersionPolicy) to [`HttpVersionPolicy.RequestVersionOrHigher`](xref:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher). -## HTTP/3 benefits - -HTTP/3 uses the same semantics as HTTP/1.1 and HTTP/2: the same request methods, status codes, and message fields apply to all versions. The differences are in the underlying transport. Both HTTP/1.1 and HTTP/2 use TCP as their transport. HTTP/3 uses a new transport technology developed alongside HTTP/3 called [QUIC](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport-34). - -HTTP/3 and QUIC have a number of benefits compared to HTTP/1.1 and HTTP/2: - -* Faster response time of the first request. QUIC and HTTP/3 negotiates the connection in fewer round-trips between the client and the server. The first request reaches the server faster. -* Improved experience when there is connection packet loss. HTTP/2 multiplexes multiple requests via one TCP connection. Packet loss on the connection affects all requests. This problem is called "head-of-line blocking". Because QUIC provides native multiplexing, lost packets only impact the requests where data has been lost. -* Supports transitioning between networks. This feature is useful for mobile devices where it is common to switch between WIFI and cellular networks as a mobile device changes location. Currently, HTTP/1.1 and HTTP/2 connections fail with an error when switching networks. An app or web browsers must retry any failed HTTP requests. HTTP/3 allows the app or web browser to seamlessly continue when a network changes. Kestrel doesn't support network transitions in .NET 8. It may be available in a future release. - :::moniker-end [!INCLUDE[](~/fundamentals/servers/kestrel/includes/http3-6-7.md)] From 3848e48c591e96b5fa0baaa18b26524969e1f958 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 14:53:42 -0600 Subject: [PATCH 09/13] Update Kestrel HTTP/3 docs --- aspnetcore/fundamentals/servers/kestrel/http3.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index 741a453fc773..ab221ae93be9 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -27,9 +27,9 @@ uid: fundamentals/servers/kestrel/http3 * Is the latest version of the Hypertext Transfer Protocol. * Builds on the strengths of `HTTP/2` while addressing some of its limitations, particularly in terms of performance, latency, reliability, and security. -+---------------+-------------------------+-------------------------+ +|---------------|-------------------------|-------------------------| | Feature | `HTTP/2` | `HTTP/3` | -+---------------+-------------------------+-------------------------+ +|---------------|-------------------------|-------------------------| | Transport | Uses [TCP](https://developer.mozilla.org/docs/Glossary/TCP) | Uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) | | Layer | | | | Connection | Slower due to TCP + TLS | Faster with 0-RTT QUIC | @@ -37,7 +37,6 @@ uid: fundamentals/servers/kestrel/http3 | Head-of-Line | Affected by TCP-level | Eliminated with QUIC | | Blocking | blocking | stream multiplexing | | Encryption | TLS over TCP | TLS is built into QUIC | -+---------------+-------------------------+-------------------------+ The key differences from `HTTP/2` to `HTTP/3` are: From 8a36f8d6c926c91abbe9bb3224be958e2a64c429 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 14:57:11 -0600 Subject: [PATCH 10/13] Update Kestrel HTTP/3 docs --- aspnetcore/fundamentals/servers/kestrel/http3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index ab221ae93be9..d257cec80623 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -40,7 +40,7 @@ uid: fundamentals/servers/kestrel/http3 The key differences from `HTTP/2` to `HTTP/3` are: -* **Transport Protocol**: `HTTP/3` uses QUIC instead of TCP. QUIC offers improved performance, lower latency, and better reliability, especially on mobile and lossy networks. +* **Transport Protocol**: [`HTTP/3`](https://developer.mozilla.org/docs/Glossary/HTTP_3) uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) instead of TCP. QUIC offers improved performance, lower latency, and better reliability, especially on mobile and lossy networks. * **Head-of-Line Blocking**: `HTTP/2` can suffer from head-of-line blocking at the TCP level, where a delay in one stream can affect others. `HTTP/3`, with QUIC, provides independent streams, so packet loss in one stream doesn't stall others. * **Connection Establishment**: `HTTP/3` with QUIC can establish connections faster, sometimes in zero round-trip time (0-RTT) for returning clients, as it combines transport and encryption handshakes. * **Encryption**: `HTTP/3` mandates TLS 1.3 encryption, providing enhanced security by default, whereas it's optional in `HTTP/2`. From 814d9575fb91ed44c05a0b357e09ec332e69e7ef Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 14:58:53 -0600 Subject: [PATCH 11/13] Update Kestrel HTTP/3 docs --- aspnetcore/fundamentals/servers/kestrel/http3.md | 1 - 1 file changed, 1 deletion(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index d257cec80623..ec2a038f3d0d 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -27,7 +27,6 @@ uid: fundamentals/servers/kestrel/http3 * Is the latest version of the Hypertext Transfer Protocol. * Builds on the strengths of `HTTP/2` while addressing some of its limitations, particularly in terms of performance, latency, reliability, and security. -|---------------|-------------------------|-------------------------| | Feature | `HTTP/2` | `HTTP/3` | |---------------|-------------------------|-------------------------| | Transport | Uses [TCP](https://developer.mozilla.org/docs/Glossary/TCP) | Uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) | From fe4b59fe33efffe7779903bf02df16754e658bb4 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 15:02:09 -0600 Subject: [PATCH 12/13] Update Kestrel HTTP/3 docs --- aspnetcore/fundamentals/servers/kestrel/http3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index ec2a038f3d0d..c6671a657355 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -39,7 +39,7 @@ uid: fundamentals/servers/kestrel/http3 The key differences from `HTTP/2` to `HTTP/3` are: -* **Transport Protocol**: [`HTTP/3`](https://developer.mozilla.org/docs/Glossary/HTTP_3) uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) instead of TCP. QUIC offers improved performance, lower latency, and better reliability, especially on mobile and lossy networks. +* **Transport Protocol**: [`HTTP/3`](https://developer.mozilla.org/docs/Glossary/HTTP_3) uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) instead of [TCP](https://developer.mozilla.org/docs/Glossary/TCP). QUIC offers improved performance, lower latency, and better reliability, especially on mobile and lossy networks. * **Head-of-Line Blocking**: `HTTP/2` can suffer from head-of-line blocking at the TCP level, where a delay in one stream can affect others. `HTTP/3`, with QUIC, provides independent streams, so packet loss in one stream doesn't stall others. * **Connection Establishment**: `HTTP/3` with QUIC can establish connections faster, sometimes in zero round-trip time (0-RTT) for returning clients, as it combines transport and encryption handshakes. * **Encryption**: `HTTP/3` mandates TLS 1.3 encryption, providing enhanced security by default, whereas it's optional in `HTTP/2`. From d2e563c215dd26ed8c35a706ff2aae59b53421d4 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 24 Apr 2025 15:07:40 -0600 Subject: [PATCH 13/13] Update Kestrel HTTP/3 docs --- aspnetcore/fundamentals/servers/kestrel/http3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/aspnetcore/fundamentals/servers/kestrel/http3.md b/aspnetcore/fundamentals/servers/kestrel/http3.md index c6671a657355..75859f1cc6f9 100644 --- a/aspnetcore/fundamentals/servers/kestrel/http3.md +++ b/aspnetcore/fundamentals/servers/kestrel/http3.md @@ -27,6 +27,8 @@ uid: fundamentals/servers/kestrel/http3 * Is the latest version of the Hypertext Transfer Protocol. * Builds on the strengths of `HTTP/2` while addressing some of its limitations, particularly in terms of performance, latency, reliability, and security. +The following table summarizes the differences between `HTTP/2` and `HTTP/3`: + | Feature | `HTTP/2` | `HTTP/3` | |---------------|-------------------------|-------------------------| | Transport | Uses [TCP](https://developer.mozilla.org/docs/Glossary/TCP) | Uses [QUIC](https://www.rfc-editor.org/rfc/rfc9000.html) |