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

[Rick-Anderson]

Use this issue to ask questions about the Transport Layer Security (TLS) best practices with the .NET Framework document.

[RamanBut-Husaim]

@Rick-Anderson @mairaw hello.

Would like to clarify the information present in the following section - https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls#for-wcf-using-net-framework-35---452-using-tcp-transport-security-with-certificate-credentials.

These versions of the WCF framework are hardcoded to use values SSL 3.0 and TLS 1.0. These values cannot be changed. You must update and retarget to NET Framework 4.6 or later versions to use TLS 1.1 and 1.2.

Do I understand correctly that it covers the case with basic http binding that uses certificate for authentication on the transport level?

<binding name="some-binding" >
  <security mode="Transport">
    <transport clientCredentialType="Certificate" />
  </security>
</binding>

Thanks.

[mconnew]

Hi @RamanBut-Husaim. The section which you quoted only applies to using the TCP transport in WCF. For the HTTP transport with a WCF client doesn't do anything specific. Internally we use HttpWebRequest so we will just have the behavior that HttpWebRequest will have. For the HTTP transport with a WCF client, we have the behavior that the OS components IIS or HTTP.SYS are configured to use.

[RamanBut-Husaim]

@mconnew Understood. Thanks a lot for the quick reply!

[bjorncoltof]

Hi @Rick-Anderson, the article covers enabling TLS 1.2 quite well, is it possible to extend it with information about how to enforce TLS 1.2?

[karelz]

@bjorncoltof I don't believe we have mechanisms to forbid certain protocol versions via app-wide/machine-wide configuration (incl. registry). Maybe the OS has something like that?

cc @davidsh

[davidsh]

Maybe the OS has something like that?

Yes, Windows OS has registry keys you can set to enable/disable various TLS protocol versions.

See: https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings

For example:

Registry path: HKLM SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols

To disable the TLS 1.0 protocol, create an Enabled entry in the appropriate subkey. This entry does not exist in the registry by default. After you have created the entry, change the DWORD value to 0. To enable the protocol, change the DWORD value to 1.

Subkey | Description
Client | Controls the use of TLS 1.0 on the TLS client.
Server | Controls the use of TLS 1.0 on the TLS server.
DisabledByDefault | Flag to disable TLS 1.0 by default.

[blowdart]

https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/manage-ssl-protocols-in-ad-fs also has some powershell should you want to avoid the regedit.

[coolzsunil]

I am a little confused after reading your article - https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls#if-your-app-targets-a-net-framework-version-earlier-than-47

In the section - If your app targets a .NET Framework version earlier than 4.7 - For .NET Framework 3.5 - 4.5.1 and not WCF

it is mentioned - Set the SchUseStrongCrypto and SystemDefaultTlsVersions registry keys to 1

As per our tests with sample applications, we do not require SystemDefaultTlsVersions for going TLS 1.2. The presence of SchUseStrongCrypto is good enough for any apps which are targeting .NET 4.0 - 4.6.2 to move to TLS 1.2.

The explanation of SystemDefaultTlsVersions in the same documents, only mentions the cases, when 4.7 is installed on the system.
For all other cases, where the machine has 4.5.2 to 4.6.2, but with apps targeting .NET 4.0 - 4.6.2, the presence of SchUseStrongCrypto is the only entry, we require.
Our understanding is also mentioned here - https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/manage-ssl-protocols-in-ad-fs#enabling-strong-authentication-for-net-applications

Can you please confirm the correct one?

Regards,
Sunil Bhaskar

[davidsh]

Can you please confirm the correct one?

The difference between SchUseStrongCrypto and SystemDefaultTlsVersions is subtle. Both of them will indeed add Tls1.1 and Tls1.2 to the set of possible protocols. And doing so implies that the strongest protocol (in this case Tls1.2) would be offered first to a server. Assuming the server supported Tls1.2, the end result would be Tls1.2.

The difference between those two registry entries is as follows. SchUseStrongCrypto will always drop Ssl3.0 as well as any cipher suites from Tls1.0 et. al. that are considered insecure such as RC4. SchUseStrongCrypto will also set the default ServicePointManager.SecurityProtocol property to use "Tls1.0 | Tls 1.1 | Tls1.2" as the default. However, note that this list is fixed.

Using SystemDefaultTlsVersions, on the other hand, causes the same ServicePointManager.SecurityProtocol property to use a default of SecurityProtocolType.SystemDefault. That means that the operating system will select the set of TLS protocols for the default set. And this default set will change over time depending on the OS version. For example, as the OS version moves forward in the future, TLS 1.3 will be added and other protocols will be removed.

See the matrix of OS versions TLS protocols here:
https://support.microsoft.com/en-us/help/3154518/support-for-tls-system-default-versions-included-in-the-net-framework

The guidance given in our documentation is that for new code the recommendation is to use patterns such as SystemDefaultTlsVersions to let the OS make the best decision. For new .NET Framework applications targeting 4.7 and later, these registry keys are not needed and the equivalent "SystemDefault" values are used.

[coolzsunil]

@davidsh The move to use SystemDefaultTlsVersions is not comprehensive. An application has a single config file. And if we set the application config to use System default, it will fail on Windows 7 and Windows 2008R2, where TLS 1.0 is the default protocol.
This makes it difficult to support multiple operating system using a single config file.

Also, do you know whether the support for SystemDefaultTlsVersions is there in frameworks 4.0 - 4.6.2. I do not see any documentation which points to a Windows update, which added support for these.

[davidsh]

Also, do you know whether the support for SystemDefaultTlsVersions is there in frameworks 4.0 - 4.6.2. I do not see any documentation which points to a Windows update, which added support for these.

SystemDefaultTlsVersions is only supported in .NET 4.7 and above.

[marcroussy]

I have a scenario with a Windows 7 machine with 4.7.1 installed and a WPF application that targets 4.7.1. The app isn't setting the SystemDefaultTlsVersions, and therefore should be using the OS default (which should be TLS 1.0, since 1.1 and 1.2 aren't enabled by default on Win7).

The endpoint I'm calling from the WPF app has TLS1, 1.1, and 1.2 enabled.

I'm getting a connection error in the WPF app unless I enable TLS 1.2 in Windows 7. Is this the expected behaviour for WPF apps running 4.7.1?