Changes to Kestrel's default supported TLS protocol versions

[halter73]

Changes to Kestrel's default supported TLS protocol versions

Kestrel now uses the system default TLS protocol versions rather than restricting connections to the TLS 1.1 and TLS 1.2 protocols like it did previously.

This allows TLS 1.3 to be used by default in environments that support it, but it also allows TLS 1.0 to be used in some environments (such as Windows Server 2016 by default) which is usually not desirable. To disable older protocols you can either do so system-wide (Windows instructions) or manually select which protocols you want to support in code as follows:

using System.Security.Authentication;
using Microsoft.AspNetCore.Hosting
using Microsoft.Extensions.Hosting;

// ...

.ConfigureWebHostDefaults(webBuilder =>
{
    webBuilder.UseKestrel(kestrelOptions =>
    {
        kestrelOptions.ConfigureHttpsDefaults(httpsOptions =>
        {
            httpsOptions.SslProtocols = SslProtocols.Tls12 | SslProtocols.Tls13;
        });
    });

// ...

Unfortunately, there's no API to exclude specific protocols.

Version introduced

ASP.NET Core 5.0.0-preview6

Old behavior

Kestrel required connections use TLS 1.1 or TLS 1.2 by default.

New behavior

Kestrel now allows the operating system to choose the best protocol to use, and to block protocols that are not secure.

Reason for change

To support TLS 1.3 and future TLS versions by default as they become available.

Recommended action

Unless your app has a specific reason not to, you should use the new defaults.

However, if you should verify your system is configured to allow only secure protocols. We recommend disabling TLS 1.0 which is currently enabled by default on all Windows versions, but can be disabled system-wide.

Category

ASP.NET

Affected APIs

• Microsoft.AspNetCore.Server.Kestrel.Https.HttpsConnectionAdapterOptions.SslProtocols now defaults to SslProtocols.None instead of SslProtocols.Tls12 | SslProtocols.Tls11.

To discuss this change, use the following issue: dotnet/aspnetcore#22563

---

Issue metadata

• Issue type: breaking-change