Editare

Partajați prin

Transport Layer Security (TLS) best practices with .NET Framework

Note

This page contains .NET Framework TLS information. If you're looking for .NET TLS information, see: TLS/SSL Best Practices

.NET Framework supports the use of the Transport Layer Security (TLS) protocol to secure network communications.

What is Transport Layer Security (TLS)?

Warning

TLS 1.0 and 1.1 has been deprecated by RFC8996. This document covers TLS 1.2 and TLS 1.3 only.

The Transport Layer Security (TLS) protocol is an industry latest version of the standard designed to help protect the privacy of information communicated over the Internet. TLS 1.3 is a standard that provides security improvements over previous versions. This article presents recommendations to secure .NET Framework applications that use the TLS protocol.

Who can benefit from this document?

TLS support in .NET Framework

Since the .NET Framework is dependent on Schannel on Windows, which versions can be negotiated and which version will be used depends on the operating system.

Here is an updated example table showing the highest supported TLS version for different combinations of operating system versions and .NET Framework target versions:

.NET Framework Target Version Windows 10 Windows 11
3.5 TLS 1.2 TLS 1.2
4.6.2 TLS 1.2 TLS 1.3
4.7 TLS 1.2 TLS 1.3
4.7.1 TLS 1.2 TLS 1.3
4.7.2 TLS 1.2 TLS 1.3
4.8 TLS 1.2 TLS 1.3
4.8.1 TLS 1.2 TLS 1.3

For more information see TLS protocol version support in Schannel.

Recommendations

  • For TLS 1.3, target .NET Framework 4.8 or later. Check Audit your code section how to verify your target framework.
  • Do not specify the TLS version explicitly, i.e. don't use the method overloads of SslStream that take an explicit SslProtocols parameter.
    • That way your code will let the OS decide on the TLS version.
    • If you must set ServicePointManager.SecurityProtocol, then set it to SecurityProtocolType.SystemDefault. That will also use OS default.
    • If you must use the method overloads of SslStream that take an explicit SslProtocols parameter, then pass SslProtocols.SystemDefault as argument. That will also use OS default.
  • Perform a thorough code audit to verify you're not specifying a TLS or SSL version explicitly.

Warning

Do not use SslProtocols.Default, because it sets TLS version to SSL3 and TLS 1.0 which are obsoleted.

When your app lets the OS choose the TLS version:

  • It automatically takes advantage of new TLS protocols added in the future.
  • The OS blocks protocols that are discovered not to be secure (for example, SSL3 and TLS 1.0).

This article explains how to enable the strongest security available for the version of .NET Framework that your app targets and runs on. When an app explicitly sets a security protocol and version, it opts out of any other alternative, and opts out of .NET Framework and OS default behavior. If you want your app to be able to negotiate a TLS 1.3 connection, explicitly setting to a lower TLS version prevents a TLS 1.3 connection.

If you can't avoid specifying a protocol version explicitly, we strongly recommend that you specify TLS 1.2 or TLS 1.3 (which is currently considered secure). For guidance on identifying and removing TLS 1.0 dependencies, download the Solving the TLS 1.0 Problem white paper.

WCF supports TLS 1.2 as the default in .NET Framework 4.7. Starting with .NET Framework 4.7.1, WCF defaults to the operating system configured version. If an application is explicitly configured with SslProtocols.None, WCF uses the operating system default setting when using the NetTcp transport.

You can ask questions about this document in the GitHub issue Transport Layer Security (TLS) best practices with the .NET Framework.

Audit your code and make code changes

For ASP.NET applications, inspect the <system.web><httpRuntime targetFramework> element of web.config to verify you're using the targeting intended version of the .NET Framework.

For Windows Forms and other applications, see How to: Target a Version of the .NET Framework.

Use the following sections to verify you're not using a specific TLS or SSL version.

Explicitly set a security protocol

If you must explicitly set a security protocol instead of letting .NET or the OS pick the security protocol, pick these protocols:

  • For .NET Framework 3.5: TLS 1.2
  • For .NET Framework 4.6.2 or later: TLS 1.3

If you can't find specified protocols in enum, you can add those as an extension file. See below:

SslProtocolExtensions.cs

namespace System.Security.Authentication
{
    public static class SslProtocolsExtensions
    {
        // For .NET Framework 3.5
        public const SslProtocols Tls12 = (SslProtocols)3072;
        // For .NET Framework 4.6.2 and later
        public const SslProtocols Tls13 = (SslProtocols)12288;
    }
}

SecurityProtocolExtensions.cs

using System.Security.Authentication;

namespace System.Net
{
    public static class SecurityProtocolTypeExtensions
    {
        // For .NET Framework 3.5
        public const SecurityProtocolType Tls12 = (SecurityProtocolType)SslProtocolsExtensions.Tls12;
        // For .NET Framework 4.6.2 and later
        public const SecurityProtocolType Tls13 = (SecurityProtocolType)SslProtocolsExtensions.Tls13;
    }
}

For more information, see Support for TLS System Default Versions included in .NET Framework 3.5 on Windows 8.1 and Windows Server 2012 R2.

For System.Net APIs (HttpClient, SslStream)

The following sections show how to configure your application to use "currently considered secure versions" of TLS (namely TLS 1.2 and TLS 1.3) if it targets .NET Framework 4.7 or later.

For HttpClient and HttpWebRequest

ServicePointManager uses the default security protocol configured in the OS. To get the default OS choice, if possible, don't set a value for the ServicePointManager.SecurityProtocol property, which defaults to SecurityProtocolType.SystemDefault.

Because the SecurityProtocolType.SystemDefault setting causes the ServicePointManager to use the default security protocol configured by the operating system, your application might run differently based on the OS it's run on. For example, Windows 10 uses TLS 1.2, while Windows 11 uses TLS 1.3.

For SslStream

SslStream defaults to the security protocol and version chosen by the OS. To get the default OS best choice, if possible, don't use the method overloads of SslStream that take an explicit SslProtocols parameter. Otherwise, pass SslProtocols.None. We recommend that you don't use Default; setting SslProtocols.Default forces the use of SSL 3.0 /TLS 1.0 and prevents TLS 1.2.

Don't set a value for the SecurityProtocol property (for HTTP networking).

Don't use the method overloads of SslStream that take an explicit SslProtocols parameter (for TCP sockets networking). When you retarget your app to .NET Framework 4.7 or later versions, you'll be following the best practices recommendation.

For WCF apps

The following sections show how to configure your application to use "currently considered secure versions" of TLS (namely, TLS 1.2 and TLS 1.3).

Using TCP transport using transport security with certificate credentials

WCF uses the same networking stack as the rest of .NET Framework.

If you're targeting 4.7.1, WCF is configured to allow the OS to choose the best security protocol by default unless explicitly configured:

  • In your application configuration file.
  • Or, in your application in the source code.

By default, .NET Framework 4.7 and later versions are configured to use TLS 1.2 and allow connections using TLS 1.1 or TLS 1.0. Configure WCF to allow the OS to choose the best security protocol by configuring your binding to use SslProtocols.None. You can set this on SslProtocols. SslProtocols.None can be accessed from Transport. NetTcpSecurity.Transport can be accessed from Security.

If you're using a custom binding:

  • Configure WCF to allow the OS to choose the best security protocol by setting SslProtocols to use SslProtocols.None.
  • Or configure the protocol used with the configuration path system.serviceModel/bindings/customBinding/binding/sslStreamSecurity:sslProtocols.

If you're not using a custom binding and you're setting your WCF binding using configuration, set the protocol used with the configuration path system.serviceModel/bindings/netTcpBinding/binding/security/transport:sslProtocols.

Using Message Security with certificate credentials

.NET Framework 4.7 and later versions by default use the protocol specified in the SecurityProtocol property. When the AppContextSwitch Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols is set to true, WCF chooses the best protocol, up to TLS 1.0.

Configure security via AppContext switches

The AppContext switches described in this section are relevant if your app targets, or runs on, .NET Framework 4.6.2 or a later version. Whether by default, or by setting them explicitly, the switches should be false if possible. If you want to configure security via one or both switches, then don't specify a security protocol value in your code; doing so overrides the switches.

The switches have the same effect whether you're doing HTTP networking (ServicePointManager) or TCP sockets networking (SslStream).

Switch.System.Net.DontEnableSchUseStrongCrypto

A value of false for Switch.System.Net.DontEnableSchUseStrongCrypto causes your app to use strong cryptography. A value of false for DontEnableSchUseStrongCrypto uses more secure network protocols (TLS 1.2 and TLS 1.1) and blocks protocols that are not secure. For more info, see The SCH_USE_STRONG_CRYPTO flag. A value of true disables strong cryptography for your app. This switch affects only client (outgoing) connections in your application.

If your app targets .NET Framework 4.6.2 or later versions, this switch defaults to false. That's a secure default, which we recommend. If your app runs on .NET Framework 4.6.2, but targets an earlier version, the switch defaults to true. In that case, you should explicitly set it to false.

DontEnableSchUseStrongCrypto should only have a value of true if you need to connect to legacy services that don't support strong cryptography and can't be upgraded.

Switch.System.Net.DontEnableSystemDefaultTlsVersions

A value of false for Switch.System.Net.DontEnableSystemDefaultTlsVersions causes your app to allow the operating system to choose the protocol. A value of true causes your app to use protocols picked by the .NET Framework.

If your app targets .NET Framework 4.7 or later versions, this switch defaults to false. That's a secure default that we recommend. If your app runs on .NET Framework 4.7 or later versions, but targets an earlier version, the switch defaults to true. In that case, you should explicitly set it to false.

Configure Schannel protocols in the Windows Registry

You can use the registry for fine-grained control over the protocols that your client or server app negotiates. Your app's networking goes through Schannel (which is another name for Secure Channel). By configuring Schannel, you can configure your app's behavior.

Start with the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols registry key. Under that key you can create any subkeys in the set TLS 1.2, TLS 1.3. Under each of those subkeys, you can create subkeys Client and/or Server. Under Client and Server, you can create DWORD values DisabledByDefault (0 or 1) and Enabled (0 or 1).

For more information see: TLS Registry Settings - Schannel

The SCH_USE_STRONG_CRYPTO flag

When it's enabled (by default, or by an AppContext switch), .NET Framework uses the SCH_USE_STRONG_CRYPTO flag when your app initiates a TLS connection to a server. .NET Framework passes the flag to Schannel to instruct it to disable known weak cryptographic algorithms, cipher suites, and TLS/SSL protocol versions that may be otherwise enabled for better interoperability. For more information, see:

The SCH_USE_STRONG_CRYPTO flag is also passed to Schannel for client (outgoing) connections when you explicitly use the Tls11 or Tls12 enumerated values of SecurityProtocolType or SslProtocols. The SCH_USE_STRONG_CRYPTO flag is used only for connections where your application acts the role of the client. You can disable weak protocols and algorithms when your applications acts the role of the server by configuring the machine-wide Schannel registry settings.

  • Last updated on