You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Transport Layer Security (TLS) best practices with the .NET Framework #4675
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?
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.
@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?
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.
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 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.
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.
@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.
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.
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?
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?
Yes, unfortunately.
If your app is targeting .NET 4.7.x, then effectively you are using 'SystemDefaultTlsVersions' regardless of you setting the registry key. The behavior default is ON when targeting .NET 4.7.x.
On Windows 7 / Windows Server 2008 R2, the default set of TLS protocols in the OS doesn't include TLS 1.1 nor 1.2. So, the highest you will get then is TLS 1.0.
But since your service only allows TLS 1.1 and TLS 1.2, you will thus be unable to connect with your client.
The workaround in this case (if you need to run on Windows 7 / Windows Server 2008 R2) would be manually configure the TLS versions using ServicePointManager properties. And also make sure that the applicable Windows updates are used on Windows 7 to enable TLS 1.1 and 1.2.
There is difference between "supported" and "make work" @upsampled. As @jhudsoncedaron mentioned there is some support for TLS 1.3 in earlier Windows version but that has different levels of completeness and correctness. As far as I know you would be on your own if you hit troubles with Tls 1.3 on Server 2016. So I would be hesitant to put it up as best practice.
I managed to "make it work" (TLS 1.3 on something Windows from 2019) as well but it later broke by accident because support was incomplete and things stopped working (without me knowing) because it tried to use TLS 1.3 with unsupported ciphers (which are all fine in the supported versions). Cost me days to analyze.
So I second @wfurt , just hold on to 1.2 or use a supported windows version.
Is there any chance to force use net framework 4.8 app (hosted on win10) to use tls13 during wcf calls to third-party? I turned on tls13 support in windows, but each request throws "The request was aborted: Could not create SSL/TLS secure channel"
Is there any chance to force use net framework 4.8 app (hosted on win10) to use tls13 during wcf calls to third-party? I turned on tls13 support in windows, but each request throws "The request was aborted: Could not create SSL/TLS secure channel"
I understand that 'support' and 'get working' are not the same. Same for 'TLS 1.3 Draft' and 'TLS 1.3' (though they are seemingly compatible). I think it is more accurate to replace Not Supported with Draft Support for dotnet/windows combinations that are in this grey area.
@jhudsoncedaron agreed, I am mainly pointing to it to show TLS 1.3 connections are possible (though maybe not supported) when documentation suggest otherwise.
I understand that 'support' and 'get working' are not the same. Same for 'TLS 1.3 Draft' and 'TLS 1.3' (though they are seemingly compatible). I think it is more accurate to replace Not Supported with Draft Support for dotnet/windows combinations that are in this grey area.
@upsampled I don't agree here. While Microsoft had some support from Windows 10 1903 ("for testing purposes only, not production environment."), this information has been removed almost everywhere. We should not rely on any draft support, if there is an incomplete implementation that probably doesn't work in some cases. This causes to much pain for everyone involved.
Windows Server 2022 and newer (including Windows 11) support TLS 1.3
built-in. Previous builds of Windows 10 had broken TLS 1.3
implementations that could be enabled via registry.
If we were to follow the recommended best practice for specifying protocol versions by not specifying protocol versions and let the OS take care of things, would it be possible to have a method/property to invoke that would list the protocol versions that are currently supported?
is more discoverable when doing a code review. If I come back to my app which has been running quietly and uninterrupted on a server in some forgotten closet for the past 5 years, I wouldn't want to have go digging through registry keys and all manner of outdated and sometimes contradictory blog posts to figure out which protocols it's running.
Activity
RamanBut-Husaim commentedon Apr 13, 2018
@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.
Do I understand correctly that it covers the case with basic http binding that uses certificate for authentication on the transport level?
Thanks.
mconnew commentedon Apr 13, 2018
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 commentedon Apr 14, 2018
@mconnew Understood. Thanks a lot for the quick reply!
bjorncoltof commentedon May 25, 2018
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 commentedon May 25, 2018
@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 commentedon May 25, 2018
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:
blowdart commentedon May 25, 2018
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.
anvikshaka commentedon Jun 29, 2018
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 commentedon Jul 4, 2018
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.SecurityProtocolproperty 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.
anvikshaka commentedon Jul 5, 2018
@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 commentedon Jul 5, 2018
SystemDefaultTlsVersions is only supported in .NET 4.7 and above.
marcroussy commentedon Aug 14, 2018
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?
davidsh commentedon Aug 14, 2018
Yes, unfortunately.
If your app is targeting .NET 4.7.x, then effectively you are using 'SystemDefaultTlsVersions' regardless of you setting the registry key. The behavior default is ON when targeting .NET 4.7.x.
On Windows 7 / Windows Server 2008 R2, the default set of TLS protocols in the OS doesn't include TLS 1.1 nor 1.2. So, the highest you will get then is TLS 1.0.
But since your service only allows TLS 1.1 and TLS 1.2, you will thus be unable to connect with your client.
The workaround in this case (if you need to run on Windows 7 / Windows Server 2008 R2) would be manually configure the TLS versions using ServicePointManager properties. And also make sure that the applicable Windows updates are used on Windows 7 to enable TLS 1.1 and 1.2.
144 remaining items
wfurt commentedon May 12, 2023
There is difference between "supported" and "make work" @upsampled. As @jhudsoncedaron mentioned there is some support for TLS 1.3 in earlier Windows version but that has different levels of completeness and correctness. As far as I know you would be on your own if you hit troubles with Tls 1.3 on Server 2016. So I would be hesitant to put it up as best practice.
upsampled commentedon May 12, 2023
@wfurt I think documenting this is the first step to any discussion on the matter.
Is there anywhere I can read more about this?
simonthum commentedon May 19, 2023
I managed to "make it work" (TLS 1.3 on something Windows from 2019) as well but it later broke by accident because support was incomplete and things stopped working (without me knowing) because it tried to use TLS 1.3 with unsupported ciphers (which are all fine in the supported versions). Cost me days to analyze.
So I second @wfurt , just hold on to 1.2 or use a supported windows version.
krabobobr commentedon Sep 29, 2023
Is there any chance to force use net framework 4.8 app (hosted on win10) to use tls13 during wcf calls to third-party? I turned on tls13 support in windows, but each request throws "The request was aborted: Could not create SSL/TLS secure channel"
kapsiR commentedon Sep 29, 2023
According to the documentation, the Schannel provider doesn't support it.
The latest commit is pretty clear:
upsampled commentedon Oct 2, 2023
@kapsiR it is not clear, as @krabobobr you can get likely get TLS 1.3 working with the following.
I understand that 'support' and 'get working' are not the same. Same for 'TLS 1.3 Draft' and 'TLS 1.3' (though they are seemingly compatible). I think it is more accurate to replace
Not SupportedwithDraft Supportfor dotnet/windows combinations that are in this grey area.jhudsoncedaron commentedon Oct 2, 2023
@upsampled : That code sample is messed up. What you should do is check the Enum with reflection for the values you want.
This is the equivalent dynamically detecting .NET Framework version and enabling support in your application when the host has it.
upsampled commentedon Oct 2, 2023
@jhudsoncedaron agreed, I am mainly pointing to it to show TLS 1.3 connections are possible (though maybe not supported) when documentation suggest otherwise.
kapsiR commentedon Oct 2, 2023
@upsampled I don't agree here. While Microsoft had some support from Windows 10 1903 ("for testing purposes only, not production environment."), this information has been removed almost everywhere. We should not rely on any draft support, if there is an incomplete implementation that probably doesn't work in some cases. This causes to much pain for everyone involved.
Even
curlhas a check for that because of the broken implementations in previous versions:davidkeaveny commentedon Oct 31, 2024
If we were to follow the recommended best practice for specifying protocol versions by not specifying protocol versions and let the OS take care of things, would it be possible to have a method/property to invoke that would list the protocol versions that are currently supported?
The recommendation is to use
but something like
is more discoverable when doing a code review. If I come back to my app which has been running quietly and uninterrupted on a server in some forgotten closet for the past 5 years, I wouldn't want to have go digging through registry keys and all manner of outdated and sometimes contradictory blog posts to figure out which protocols it's running.
BillWagner commentedon Mar 2, 2026
Closing as a stale discussion