Skip to content

Commit 7c0e725

Browse files
authored
Update TLS Best Practices (#41543)
Minor changes to wording.
1 parent 60451f5 commit 7c0e725

File tree

1 file changed

+9
-11
lines changed
  • docs/framework/network-programming

1 file changed

+9
-11
lines changed

docs/framework/network-programming/tls.md

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -53,28 +53,26 @@ For more information see [TLS protocol version support in Schannel](/windows/win
5353

5454
## Recommendations
5555

56-
- For TLS 1.3, target .NET Framework 4.8 or later. ([here](#audit-your-code-and-make-code-changes) is how to check what is your `target framework`.)
57-
- Do not specify the TLS version explicitly. (i.e. don't use the method overloads of SslStream that take an explicit SslProtocols parameter.)
56+
- For TLS 1.3, target .NET Framework 4.8 or later. Check [Audit your code](#audit-your-code-and-make-code-changes) section how to verify your `target framework`.
57+
- Do not specify the TLS version explicitly, i.e. don't use the method overloads of `SslStream` that take an explicit `SslProtocols` parameter.
5858
- That way your code will let the OS decide on the TLS version.
5959
- If you must set <xref:System.Net.ServicePointManager.SecurityProtocol?displayProperty=nameWithType>, then set it to <xref:System.Net.SecurityProtocolType.SystemDefault?displayProperty=nameWithType>. That will also use OS default.
60-
- 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.
60+
- 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.
6161
- Perform a thorough code audit to verify you're not specifying a TLS or SSL version explicitly.
6262

6363
> [!WARNING]
64-
> Do not use `SslProtocols.Default`. (because it sets TLS version to SSL3 and TLS1.0 which is obsoleted.)
64+
> Do not use `SslProtocols.Default`, because it sets TLS version to SSL3 and TLS 1.0 which are obsoleted.
6565
6666
When your app lets the OS choose the TLS version:
6767

68-
- It automatically takes advantage of new protocols added in the future.
69-
- The OS blocks protocols that are discovered not to be secure.
70-
71-
The section [Audit your code and make code changes](#audit-your-code-and-make-code-changes) covers auditing and updating your code.
68+
- It automatically takes advantage of new TLS protocols added in the future.
69+
- The OS blocks protocols that are discovered not to be secure (e.g. SSL3 and TLS 1.0).
7270

7371
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.
7472

75-
If you can't avoid specifying a protocol version explicitly, we strongly recommend that you specify TLS1.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](https://www.microsoft.com/download/details.aspx?id=55266) white paper.
73+
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](https://www.microsoft.com/download/details.aspx?id=55266) white paper.
7674

77-
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.
75+
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.
7876

7977
You can ask questions about this document in the GitHub issue [Transport Layer Security (TLS) best practices with the .NET Framework](https://github.com/dotnet/docs/issues/4675).
8078

@@ -88,7 +86,7 @@ Use the following sections to verify you're not using a specific TLS or SSL vers
8886

8987
## If you must explicitly set a Security Protocol
9088

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

9391
- For .NET Framework 3.5: TLS 1.2
9492
- For .NET Framework 4.6.2 or later: TLS 1.3

0 commit comments

Comments
 (0)