Edit

Share via

Kestrel: HTTP/2 disabled over TLS on incompatible Windows versions

  • Article

To enable HTTP/2 over Transport Layer Security (TLS) on Windows, two requirements need to be met:

  • Application-Layer Protocol Negotiation (ALPN) support, which is available starting with Windows 8.1 and Windows Server 2012 R2.
  • A set of ciphers compatible with HTTP/2, which is available starting with Windows 10 and Windows Server 2016.

As such, Kestrel's behavior when HTTP/2 over TLS is configured has changed to:

  • Downgrade to Http1 and log a message at the Information level when ListenOptions.HttpProtocols is set to Http1AndHttp2. Http1AndHttp2 is the default value for ListenOptions.HttpProtocols.
  • Throw a NotSupportedException when ListenOptions.HttpProtocols is set to Http2.

For discussion, see issue dotnet/aspnetcore#23068.

Version introduced

ASP.NET Core 5.0

Old behavior

The following table outlines the behavior when HTTP/2 over TLS is configured.

Protocols Windows 7,
Windows Server 2008 R2,
or earlier		 Windows 8,
Windows Server 2012		 Windows 8.1,
Windows Server 2012 R2		 Windows 10,
Windows Server 2016,
or newer
Http2 Throw NotSupportedException Error during TLS handshake Error during TLS handshake * No error
Http1AndHttp2 Downgrade to Http1 Downgrade to Http1 Error during TLS handshake * No error

* Configure compatible cipher suites to enable these scenarios.

New behavior

The following table outlines the behavior when HTTP/2 over TLS is configured.

Protocols Windows 7,
Windows Server 2008 R2,
or earlier		 Windows 8,
Windows Server 2012		 Windows 8.1,
Windows Server 2012 R2		 Windows 10,
Windows Server 2016,
or newer
Http2 Throw NotSupportedException Throw NotSupportedException Throw NotSupportedException ** No error
Http1AndHttp2 Downgrade to Http1 Downgrade to Http1 Downgrade to Http1 ** No error

** Configure compatible cipher suites and set the app context switch Microsoft.AspNetCore.Server.Kestrel.EnableWindows81Http2 to true to enable these scenarios.

Reason for change

This change ensures compatibility errors for HTTP/2 over TLS on older Windows versions are surfaced as early and as clearly as possible.

Ensure HTTP/2 over TLS is disabled on incompatible Windows versions. Windows 8.1 and Windows Server 2012 R2 are incompatible since they lack the necessary ciphers by default. However, it's possible to update the Computer Configuration settings to use HTTP/2 compatible ciphers. For more information, see TLS cipher suites in Windows 8.1. Once configured, HTTP/2 over TLS on Kestrel must be enabled by setting the app context switch Microsoft.AspNetCore.Server.Kestrel.EnableWindows81Http2. For example:

AppContext.SetSwitch("Microsoft.AspNetCore.Server.Kestrel.EnableWindows81Http2", true);

No underlying support has changed. For example, HTTP/2 over TLS has never worked on Windows 8 or Windows Server 2012. This change modifies how errors in these unsupported scenarios are presented.

Affected APIs

None