Skip to content

Commit d4b46d6

Browse files
dotpauldotpaul
committed
More docs
1 parent 8220f11 commit d4b46d6

File tree

5 files changed

+321
-1
lines changed

5 files changed

+321
-1
lines changed

‎docs/code-quality/ca5361.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,9 @@ Setting `Switch.System.Net.DontEnableSchUseStrongCrypto` to `true` weakens the c
3333

3434
## How to fix violations
3535

36-
- If your application targets .NET Framework v4.6 or later, you can remove the <xref:System.AppContext.SetSwitch%2A?displayProperty=nameWithType> method call.
36+
- If your application targets .NET Framework v4.6 or later, you can either remove the <xref:System.AppContext.SetSwitch%2A?displayProperty=nameWithType> method call, or set the switch's value to `false`.
3737
- If your application targets .NET Framework earlier than v4.6, and runs on .NET Framework v4.6 or later, set the switch's value to `false`.
38+
- Otherwise, refer to [Transport Layer Security (TLS) best practices with the .NET Framework](/dotnet/framework/network-programming/tls) for mitigations.
3839

3940
## When to suppress warnings
4041

‎docs/code-quality/ca5364.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: "CA5364: Do Not Use Deprecated Security Protocols"
3+
ms.date: 07/10/2019
4+
ms.topic: reference
5+
author: dotpaul
6+
ms.author: paulming
7+
manager: jillfra
8+
dev_langs:
9+
- CSharp
10+
- VB
11+
ms.workload:
12+
- "multiple"
13+
f1_keywords:
14+
- "CA5364"
15+
- "DoNotUseDeprecatedSecurityProtocols"
16+
---
17+
# CA5364: Do Not Use Deprecated Security Protocols
18+
19+
|||
20+
|-|-|
21+
|TypeName|DoNotUseDeprecatedSecurityProtocols|
22+
|CheckId|CA5364|
23+
|Category|Microsoft.Security|
24+
|Breaking Change|Non Breaking|
25+
26+
## Cause
27+
28+
- A deprecated <xref:System.Net.SecurityProtocolType?displayProperty=nameWithType> value was referenced.
29+
- An integer value representing a deprecated value was assigned to a <xref:System.Net.SecurityProtocolType> variable.
30+
31+
Deprecated values are:
32+
- Ssl3
33+
- Tls
34+
- Tls10
35+
- Tls11
36+
37+
## Rule description
38+
39+
Transport Layer Security (TLS) secures communication between computers, most commonly with Hypertext Transfer Protocol Secure (HTTPS). Older protocol versions of TLS are less secure than TLS 1.2 and TLS 1.3, and are more at risk of vulnerabilities being discovered in the future. You should avoid older protocol versions to minimize risk. For guidance on identifying and removing deprecated protocol versions, see [Solving the TLS 1.0 Problem, 2nd Edition](/security/solving-tls1-problem).
40+
41+
## How to fix violations
42+
43+
Don't use deprecated TLS protocol versions.
44+
45+
## When to suppress warnings
46+
47+
- It's safe to suppress this warning if the reference to the deprecated protocol version isn't being used to enable a deprecated version.
48+
- You can suppress this warning if you need to connect to a legacy service, which can't be upgraded to use secure TLS configurations.
49+
50+
## Pseudo-code examples
51+
52+
### Violation
53+
54+
```csharp
55+
using System;
56+
using System.Net;
57+
58+
public class ExampleClass
59+
{
60+
public void ExampleMethod()
61+
{
62+
// CA5364 violation
63+
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12;
64+
}
65+
}
66+
```
67+
68+
```vb
69+
Imports System
70+
Imports System.Net
71+
72+
Public Class TestClass
73+
Public Sub ExampleMethod()
74+
' CA5364 violation
75+
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls11 Or SecurityProtocolType.Tls12
76+
End Sub
77+
End Class
78+
```
79+
80+
### Solution
81+
82+
```csharp
83+
using System;
84+
using System.Net;
85+
86+
public class TestClass
87+
{
88+
public void TestMethod()
89+
{
90+
// Let the operating system decide what TLS protocol version to use.
91+
// See https://docs.microsoft.com/dotnet/framework/network-programming/tls
92+
}
93+
}
94+
```
95+
96+
```vb
97+
Imports System
98+
Imports System.Net
99+
100+
Public Class TestClass
101+
Public Sub ExampleMethod()
102+
' Let the operating system decide what TLS protocol version to use.
103+
' See https://docs.microsoft.com/dotnet/framework/network-programming/tls
104+
End Sub
105+
End Class
106+
```
107+
108+
## Related rules
109+
110+
[CA5386: Avoid hardcoding SecurityProtocolType value](ca5386.md)

‎docs/code-quality/ca5378.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: "CA5378: Do not disable ServicePointManagerSecurityProtocols"
3+
ms.date: 07/10/2019
4+
ms.topic: reference
5+
author: dotpaul
6+
ms.author: paulming
7+
manager: jillfra
8+
dev_langs:
9+
- CSharp
10+
- VB
11+
ms.workload:
12+
- "multiple"
13+
f1_keywords:
14+
- "CA5378"
15+
- "DoNotSetSwitch"
16+
---
17+
# CA5378: Do not disable ServicePointManagerSecurityProtocols
18+
19+
|||
20+
|-|-|
21+
|TypeName|DoNotSetSwitch|
22+
|CheckId|CA5378|
23+
|Category|Microsoft.Security|
24+
|Breaking Change|Non Breaking|
25+
26+
## Cause
27+
28+
A <xref:System.AppContext.SetSwitch%2A?displayProperty=nameWithType> method call sets `Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols` to `true`.
29+
30+
## Rule description
31+
32+
Setting `Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols` to `true` limits Windows Communication Framework's (WCF) Transport Layer Security (TLS) connections to using TLS 1.0. That version of TLS will be deprecated. For more information, see [Transport Layer Security (TLS) best practices with the .NET Framework](/dotnet/framework/network-programming/tls#switchsystemservicemodeldisableusingservicepointmanagersecurityprotocols).
33+
34+
## How to fix violations
35+
36+
- If your application targets .NET Framework v4.7 or later, you can either remove the <xref:System.AppContext.SetSwitch%2A?displayProperty=nameWithType> method call, or set the switch's value to `false`.
37+
- If your application targets .NET Framework v4.6.2 or earlier, and runs on .NET Framework v4.7 or later, set the switch's value to `false`.
38+
- Otherwise, refer to [Transport Layer Security (TLS) best practices with the .NET Framework](/dotnet/framework/network-programming/tls) for mitigations.
39+
40+
## When to suppress warnings
41+
42+
You can suppress this warning if you need to connect to a legacy service, which can't be upgraded to use secure TLS configurations.
43+
44+
## Pseudo-code examples
45+
46+
### Violation
47+
48+
```csharp
49+
using System;
50+
51+
public class ExampleClass
52+
{
53+
public void ExampleMethod()
54+
{
55+
// CA5378 violation
56+
AppContext.SetSwitch("Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols", true);
57+
}
58+
}
59+
```
60+
61+
```vb
62+
Imports System
63+
64+
Public Class ExampleClass
65+
Public Sub ExampleMethod()
66+
' CA5378 violation
67+
AppContext.SetSwitch("Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols", true)
68+
End Sub
69+
End Class
70+
```
71+
72+
### Solution
73+
74+
```csharp
75+
using System;
76+
77+
public class ExampleClass
78+
{
79+
public void ExampleMethod()
80+
{
81+
AppContext.SetSwitch("Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols", false);
82+
}
83+
}
84+
```
85+
86+
```vb
87+
Imports System
88+
89+
Public Class ExampleClass
90+
Public Sub ExampleMethod()
91+
AppContext.SetSwitch("Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols", false)
92+
End Sub
93+
End Class
94+
```

‎docs/code-quality/ca5386.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
title: "CA5386: Avoid hardcoding SecurityProtocolType value"
3+
ms.date: 07/10/2019
4+
ms.topic: reference
5+
author: dotpaul
6+
ms.author: paulming
7+
manager: jillfra
8+
dev_langs:
9+
- CSharp
10+
- VB
11+
ms.workload:
12+
- "multiple"
13+
f1_keywords:
14+
- "CA5386"
15+
- "DoNotUseDeprecatedSecurityProtocols"
16+
---
17+
# CA5386: Avoid hardcoding SecurityProtocolType value
18+
19+
|||
20+
|-|-|
21+
|TypeName|DoNotUseDeprecatedSecurityProtocols|
22+
|CheckId|CA5386|
23+
|Category|Microsoft.Security|
24+
|Breaking Change|Non Breaking|
25+
26+
## Cause
27+
28+
- A safe but hardcoded <xref:System.Net.SecurityProtocolType?displayProperty=nameWithType> value was referenced.
29+
- An integer value representing a safe protocol version was assigned to a <xref:System.Net.SecurityProtocolType> variable.
30+
31+
Safe values are:
32+
- Tls12
33+
- Tls13
34+
35+
## Rule description
36+
37+
Transport Layer Security (TLS) secures communication between computers, most commonly with Hypertext Transfer Protocol Secure (HTTPS). Protocol versions TLS 1.0 and TLS 1.1 are deprecated, while TLS 1.2 and TLS 1.3 are current. In the future, newer protocol versions of TLS may be deployed, and then TLS 1.2 or TLS 1.3 may be deprecated if security flaws are discovered. To ensure that your application remains secure, avoid hardcoding a protocol version and target at least .NET Framework v4.7.1. For more details, see [Transport Layer Security (TLS) best practices with the .NET Framework](/dotnet/framework/network-programming/tls).
38+
39+
## How to fix violations
40+
41+
Don't use hardcode TLS protocol versions.
42+
43+
## When to suppress warnings
44+
45+
You can suppress this warning if you need to connect to a legacy service, which can't be upgraded to use secure TLS configurations.
46+
47+
## Pseudo-code examples
48+
49+
### Violation
50+
51+
```csharp
52+
using System;
53+
using System.Net;
54+
55+
public class ExampleClass
56+
{
57+
public void ExampleMethod()
58+
{
59+
// CA5386 violation
60+
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
61+
}
62+
}
63+
```
64+
65+
```vb
66+
Imports System
67+
Imports System.Net
68+
69+
Public Class TestClass
70+
Public Sub ExampleMethod()
71+
' CA5386 violation
72+
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
73+
End Sub
74+
End Class
75+
```
76+
77+
### Solution
78+
79+
```csharp
80+
using System;
81+
using System.Net;
82+
83+
public class TestClass
84+
{
85+
public void TestMethod()
86+
{
87+
// Let the operating system decide what TLS protocol version to use.
88+
// See https://docs.microsoft.com/dotnet/framework/network-programming/tls
89+
}
90+
}
91+
```
92+
93+
```vb
94+
Imports System
95+
Imports System.Net
96+
97+
Public Class TestClass
98+
Public Sub ExampleMethod()
99+
' Let the operating system decide what TLS protocol version to use.
100+
' See https://docs.microsoft.com/dotnet/framework/network-programming/tls
101+
End Sub
102+
End Class
103+
```
104+
105+
## Related rules
106+
107+
[CA5364: Do Not Use Deprecated Security Protocols](ca5364.md)

‎docs/code-quality/toc.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -690,6 +690,14 @@
690690
href: ca3077-insecure-processing-in-api-design-xml-document-and-xml-text-reader.md
691691
- name: "CA3147: Mark verb handlers with ValidateAntiForgeryToken"
692692
href: ca3147-mark-verb-handlers-with-validateantiforgerytoken.md
693+
- name: "CA5361: Do Not Disable SChannel Use of Strong Crypto"
694+
href: ca5361.md
695+
- name: "CA5364: Do Not Use Deprecated Security Protocols"
696+
href: ca5364.md
697+
- name: "CA5378: Do not disable ServicePointManagerSecurityProtocols"
698+
href: ca5378.md
699+
- name: "CA5386: Avoid hardcoding SecurityProtocolType value"
700+
href: ca5386.md
693701
- name: Usage warnings
694702
items:
695703
- name: Overview

0 commit comments

Comments
 (0)