diff --git a/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs b/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs
index c51c25770e2..f2ac07e4d9b 100644
--- a/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs
+++ b/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs
@@ -115,7 +115,7 @@ static void DemonstrateCodeDirectives(string providerName, string sourceFileName
}
// This example uses the SHA1 and MD5 algorithms.
- // Due to collision problems with SHA1 and MD5, Microsoft recommends SHA256 or better.
+ // Due to collision problems with SHA1 and MD5, Microsoft recommends using a NIST-approved hash function.
private static Guid s_hashMD5 = new(0x406ea660, 0x64cf, 0x4c82, 0xb6, 0xf0, 0x42, 0xd4, 0x81, 0x72, 0xa7, 0x99);
private static Guid s_hashSHA1 = new(0xff1816ec, 0xaa5e, 0x4d10, 0x87, 0xf7, 0x6f, 0x49, 0x63, 0x83, 0x34, 0x60);
diff --git a/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs b/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs
index 43b8cda38d0..a8a5b810ac2 100644
--- a/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs
+++ b/snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs
@@ -20,7 +20,7 @@ static void Main(string[] args)
// Create a new SHA1 provider.
//
// This example uses the SHA1 algorithm.
- // Due to collision problems with SHA1, Microsoft recommends SHA256 or better.
+ // Due to collision problems with SHA1, Microsoft recommends using a NIST-approved hash function.
SHA1CryptoServiceProvider SHA1alg =
(SHA1CryptoServiceProvider)CryptoConfig.CreateFromName("SHA1");
//
@@ -41,14 +41,14 @@ static void Main(string[] args)
// (OID) from the string name of the SHA1 algorithm.
//
// This example uses the SHA1 algorithm.
- // Due to collision problems with SHA1, Microsoft recommends SHA256 or better.
+ // Due to collision problems with SHA1, Microsoft recommends using a NIST-approved hash function.
string sha1Oid = CryptoConfig.MapNameToOID("SHA1");
//
// Encode the specified object identifier.
//
// This example uses the SHA1 algorithm.
- // Due to collision problems with SHA1, Microsoft recommends SHA256 or better.
+ // Due to collision problems with SHA1, Microsoft recommends using a NIST-approved hash function.
byte[] encodedMessage = CryptoConfig.EncodeOID(sha1Oid);
//
diff --git a/snippets/csharp/System.Security.Cryptography/DES/Create/fileexample.cs b/snippets/csharp/System.Security.Cryptography/DES/Create/fileexample.cs
index 63f30a3a7a0..53745d658ca 100644
--- a/snippets/csharp/System.Security.Cryptography/DES/Create/fileexample.cs
+++ b/snippets/csharp/System.Security.Cryptography/DES/Create/fileexample.cs
@@ -1,4 +1,6 @@
//
+// WARNING: DES has a 56-bit key and is considered insecure.
+// For new applications, use a NIST-approved symmetric encryption algorithm instead.
using System;
using System.IO;
using System.Security.Cryptography;
diff --git a/snippets/csharp/System.Security.Cryptography/DES/Create/memoryexample.cs b/snippets/csharp/System.Security.Cryptography/DES/Create/memoryexample.cs
index f96389304dd..7689573c5c2 100644
--- a/snippets/csharp/System.Security.Cryptography/DES/Create/memoryexample.cs
+++ b/snippets/csharp/System.Security.Cryptography/DES/Create/memoryexample.cs
@@ -1,4 +1,6 @@
//
+// WARNING: DES has a 56-bit key and is considered insecure.
+// For new applications, use a NIST-approved symmetric encryption algorithm instead.
using System;
using System.Security.Cryptography;
using System.Text;
diff --git a/snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs b/snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs
index c844b4c6991..9afcb676d8f 100644
--- a/snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs
+++ b/snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs
@@ -3,6 +3,8 @@
using System.Windows.Forms;
using System.Security.Cryptography;
+// WARNING: DES has a 56-bit key and is considered insecure.
+// For new applications, use a NIST-approved symmetric encryption algorithm instead.
public class Form1: Form
{
//
diff --git a/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs b/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs
index 429ac597a62..291e17859c5 100644
--- a/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs
+++ b/snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs
@@ -32,7 +32,7 @@ public static void Main(String[] args)
// Create the key and set it to the Key property
// of the TripleDESCryptoServiceProvider object.
// This example uses the SHA1 algorithm.
- // Due to collision problems with SHA1, Microsoft recommends SHA256 or better.
+ // Due to collision problems with SHA1, Microsoft recommends using a NIST-approved hash function.
tdes.Key = pdb.CryptDeriveKey("TripleDES", "SHA1", 192, tdes.IV);
//
diff --git a/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.cs b/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.cs
index 4c5be74c296..73c079c8fab 100644
--- a/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.cs
+++ b/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.cs
@@ -1,6 +1,6 @@
//
// This example uses the SHA1 algorithm.
-// Due to collision problems with SHA1, Microsoft recommends SHA256 or better.
+// Due to collision problems with SHA1, Microsoft recommends using a NIST-approved hash function.
using System;
using System.Text;
using System.Security.Cryptography;
diff --git a/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs b/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs
index 386607219f2..ad35eed74e1 100644
--- a/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs
+++ b/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs
@@ -35,7 +35,10 @@ public static void Main(string[] passwordargs)
//data1 can be a string or contents of a file.
string data1 = "Some test data";
//
- //The legacy default iteration count is 1000 so the two methods use the same iteration count.
+ // SECURITY NOTE: The iteration count should be as high as your
+ // performance requirements allow. NIST SP 800-132 recommends selecting
+ // the highest iteration count tolerable for your system, with a minimum
+ // of 600,000 iterations. The low value here is for illustration only.
int myIterations = 1000;
//
//
diff --git a/snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs b/snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs
index 6025f6204c9..d9a6e3f8bbb 100644
--- a/snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs
+++ b/snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs
@@ -39,6 +39,8 @@ static void String_Fragment()
static void Settings_Resolver()
{
string UserName = "username";
+ // In production code, do not hardcode credentials in source code.
+ // Instead, retrieve them from a secure store such as Azure Key Vault.
string SecurelyStoredPassword = "psswd";
string Domain= "domain";
diff --git a/snippets/csharp/System.Xml/XmlResolver/Overview/Xslt_Load_v2.cs b/snippets/csharp/System.Xml/XmlResolver/Overview/Xslt_Load_v2.cs
index c40b92defd4..fb2fc949aa4 100644
--- a/snippets/csharp/System.Xml/XmlResolver/Overview/Xslt_Load_v2.cs
+++ b/snippets/csharp/System.Xml/XmlResolver/Overview/Xslt_Load_v2.cs
@@ -60,6 +60,8 @@ static void XslCompiledTransform_Load3() {
static void XslCompiledTransform_Load4() {
string UserName = "username";
+ // In production code, do not hardcode credentials in source code.
+ // Instead, retrieve them from a secure store such as Azure Key Vault.
string SecurelyStoredPassword = "psswd";
string Domain= "domain";
@@ -118,6 +120,8 @@ static void XslCompiledTransform_Load7() {
static void XslCompiledTransform_Load8() {
string UserName = "username";
+ // In production code, do not hardcode credentials in source code.
+ // Instead, retrieve them from a secure store such as Azure Key Vault.
string SecurelyStoredPassword = "psswd";
string Domain= "domain";
@@ -176,6 +180,8 @@ static void XslCompiledTransform_Debug() {
static void Cache() {
string UserName = "username";
+ // In production code, do not hardcode credentials in source code.
+ // Instead, retrieve them from a secure store such as Azure Key Vault.
string SecurelyStoredPassword = "psswd";
string Domain= "domain";
diff --git a/snippets/csharp/System.Xml/XmlUrlResolver/Overview/XmlResolver_Samples.cs b/snippets/csharp/System.Xml/XmlUrlResolver/Overview/XmlResolver_Samples.cs
index d68f3488c33..f95aec361ec 100644
--- a/snippets/csharp/System.Xml/XmlUrlResolver/Overview/XmlResolver_Samples.cs
+++ b/snippets/csharp/System.Xml/XmlUrlResolver/Overview/XmlResolver_Samples.cs
@@ -33,6 +33,8 @@ static void XmlUrlResolver_Credentials2()
{
string UserName = "username";
+ // In production code, do not hardcode credentials in source code.
+ // Instead, retrieve them from a secure store such as Azure Key Vault.
string SecurelyStoredPassword = "psswd";
string Domain= "domain";
diff --git a/snippets/visualbasic/System.Security.Cryptography/DES/Create/fileexample.vb b/snippets/visualbasic/System.Security.Cryptography/DES/Create/fileexample.vb
index e1446d2a3ae..97fbd57f554 100644
--- a/snippets/visualbasic/System.Security.Cryptography/DES/Create/fileexample.vb
+++ b/snippets/visualbasic/System.Security.Cryptography/DES/Create/fileexample.vb
@@ -1,4 +1,6 @@
'
+' WARNING: DES has a 56-bit key and is considered insecure.
+' For new applications, use a NIST-approved symmetric encryption algorithm instead.
Imports System.IO
Imports System.Security.Cryptography
Imports System.Text
diff --git a/snippets/visualbasic/System.Security.Cryptography/DES/Create/memoryexample.vb b/snippets/visualbasic/System.Security.Cryptography/DES/Create/memoryexample.vb
index b59d10d576e..ecd32599660 100644
--- a/snippets/visualbasic/System.Security.Cryptography/DES/Create/memoryexample.vb
+++ b/snippets/visualbasic/System.Security.Cryptography/DES/Create/memoryexample.vb
@@ -1,4 +1,6 @@
'
+' WARNING: DES has a 56-bit key and is considered insecure.
+' For new applications, use a NIST-approved symmetric encryption algorithm instead.
Imports System.Security.Cryptography
Imports System.Text
Imports System.IO
diff --git a/xml/System.CodeDom/CodeChecksumPragma.xml b/xml/System.CodeDom/CodeChecksumPragma.xml
index 068643f83a3..1552d6c85ec 100644
--- a/xml/System.CodeDom/CodeChecksumPragma.xml
+++ b/xml/System.CodeDom/CodeChecksumPragma.xml
@@ -188,7 +188,7 @@ Algorithms are provided for the MD5 and SHA-1 hashes. The GUID value to use for
The calculation of the checksum is language-specific. That is, the language vendor can use any of the hashing algorithms known to the debugger to calculate the checksum. The use of a GUID for this property provides hash algorithm extensibility.
- Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1 and MD5, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
The following code example shows the setting of the property. This code example is part of a larger example provided for the class.
diff --git a/xml/System.Configuration.Assemblies/AssemblyHashAlgorithm.xml b/xml/System.Configuration.Assemblies/AssemblyHashAlgorithm.xml
index 2fc26cf1fc1..3297478c42a 100644
--- a/xml/System.Configuration.Assemblies/AssemblyHashAlgorithm.xml
+++ b/xml/System.Configuration.Assemblies/AssemblyHashAlgorithm.xml
@@ -132,7 +132,7 @@
0
- A mask indicating that there is no hash algorithm. If you specify for a multi-module assembly, the common language runtime defaults to the SHA-1 algorithm, since multi-module assemblies need to generate a hash. Due to collision problems with SHA-1, Microsoft recommends SHA-256.
+ A mask indicating that there is no hash algorithm. If you specify for a multi-module assembly, the common language runtime defaults to the SHA-1 algorithm, since multi-module assemblies need to generate a hash. Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml b/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml
index 11f99c69133..682d3c19c4c 100644
--- a/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml
+++ b/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml
@@ -264,7 +264,7 @@ This property specifies where the signer's X.509 certificate will be stored when
The property is typically used to reset the property back to default after a temporary change.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -339,7 +339,7 @@ This property specifies where the signer's X.509 certificate will be stored when
The property is typically not changed from its default. This property must be changed only if a signature that uses a different known and accessible is encountered. When finished with the signature that uses a different hash algorithm, call to reset the property back to default.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
diff --git a/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml b/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml
index 32fd82f21ec..5aa6601595e 100644
--- a/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml
+++ b/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml
@@ -118,7 +118,7 @@
## Remarks
To specify P-SHA1 as the cryptographic algorithm, use the field.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
diff --git a/xml/System.Net.Http.Headers/HttpContentHeaders.xml b/xml/System.Net.Http.Headers/HttpContentHeaders.xml
index b89f5dae508..a78b486d258 100644
--- a/xml/System.Net.Http.Headers/HttpContentHeaders.xml
+++ b/xml/System.Net.Http.Headers/HttpContentHeaders.xml
@@ -265,7 +265,7 @@
Gets or sets the value of the content header on an HTTP response.
The value of the content header on an HTTP response.
- Due to collision problems with MD5, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Net/HttpRequestHeader.xml b/xml/System.Net/HttpRequestHeader.xml
index f6f61b3b7ac..e30efe8252b 100644
--- a/xml/System.Net/HttpRequestHeader.xml
+++ b/xml/System.Net/HttpRequestHeader.xml
@@ -537,7 +537,7 @@
16
- The Content-MD5 header, which specifies the MD5 digest of the accompanying body data, for the purpose of providing an end-to-end message integrity check. Due to collision problems with MD5, Microsoft recommends a security model based on SHA-256 or better.
+ The Content-MD5 header, which specifies the MD5 digest of the accompanying body data, for the purpose of providing an end-to-end message integrity check. Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Net/HttpResponseHeader.xml b/xml/System.Net/HttpResponseHeader.xml
index 0b66c8972e2..f3a9fc2a9cd 100644
--- a/xml/System.Net/HttpResponseHeader.xml
+++ b/xml/System.Net/HttpResponseHeader.xml
@@ -389,7 +389,7 @@
16
- The Content-MD5 header, which specifies the MD5 digest of the accompanying body data, for the purpose of providing an end-to-end message integrity check. Due to collision problems with MD5, Microsoft recommends a security model based on SHA-256 or better.
+ The Content-MD5 header, which specifies the MD5 digest of the accompanying body data, for the purpose of providing an end-to-end message integrity check. Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Net/SecurityProtocolType.xml b/xml/System.Net/SecurityProtocolType.xml
index 1d90431bd35..1e00ca1f3ac 100644
--- a/xml/System.Net/SecurityProtocolType.xml
+++ b/xml/System.Net/SecurityProtocolType.xml
@@ -198,7 +198,16 @@ The Transport Layer Security (TLS) protocols assume that a connection-oriented p
192
Specifies the Transport Layer Security (TLS) 1.0 security protocol. The TLS 1.0 protocol is defined in IETF RFC 2246.
- To be added.
+
+ [!IMPORTANT]
+> TLS 1.0 has known vulnerabilities and is not recommended. Use , , or instead.
+
+ ]]>
+
@@ -240,8 +249,17 @@ The Transport Layer Security (TLS) protocols assume that a connection-oriented p
768
- Specifies the Transport Layer Security (TLS) 1.1 security protocol. The TLS 1.1 protocol is defined in IETF RFC 4346. On Windows systems, this value is supported starting with Windows 7.
- To be added.
+ Specifies the Transport Layer Security (TLS) 1.1 security protocol. The TLS 1.1 protocol is defined in IETF RFC 4346. On Windows systems, this value is supported starting with Windows 7.
+
+ [!IMPORTANT]
+> TLS 1.1 has known vulnerabilities and is not recommended. Use , , or instead.
+
+ ]]>
+
diff --git a/xml/System.Reflection/AssemblyHashAlgorithm.xml b/xml/System.Reflection/AssemblyHashAlgorithm.xml
index d4403a3b273..e9ad1b01263 100644
--- a/xml/System.Reflection/AssemblyHashAlgorithm.xml
+++ b/xml/System.Reflection/AssemblyHashAlgorithm.xml
@@ -54,7 +54,7 @@
Retrieves the MD5 message-digest algorithm.
- Due to collision problems with MD5, Microsoft recommends SHA-256.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
MD5 was developed by Rivest in 1991. It is basically MD4 with safety-belts and, while it is slightly slower than MD4, it helps provide more security. The algorithm consists of four distinct rounds, which has a slightly different design from that of MD4. Message-digest size, as well as padding requirements, remain the same.
@@ -107,7 +107,7 @@
Retrieves a revision of the Secure Hash Algorithm that corrects an unpublished flaw in SHA.
- Due to collision problems with SHA-1, Microsoft recommends SHA-256.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Security.Authentication/HashAlgorithmType.xml b/xml/System.Security.Authentication/HashAlgorithmType.xml
index 7a7d1bc976d..0cb08f1ddd2 100644
--- a/xml/System.Security.Authentication/HashAlgorithmType.xml
+++ b/xml/System.Security.Authentication/HashAlgorithmType.xml
@@ -97,7 +97,7 @@
The Message Digest 5 (MD5) hashing algorithm.
- Due to collision problems with MD5, Microsoft recommends SHA-256.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
@@ -168,7 +168,7 @@
The Secure Hashing Algorithm (SHA1).
- Due to collision problems with SHA-1, Microsoft recommends SHA-256.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml
index fca5d3554fc..4a1f2e7695f 100644
--- a/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml
+++ b/xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml
@@ -449,7 +449,7 @@
Some choices of hash algorithm can cause failures in or on some operating systems, because these methods depend on system libraries for support.
The hash algorithm used on a fresh installation of Windows 7 when exporting via as a PKCS#12 PFX is with an iteration count of 2000.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better; however, some PFX readers might only support SHA-1.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final). However, some PFX readers might only support SHA-1.
]]>
@@ -500,7 +500,7 @@
Some choices of hash algorithm can cause failures in or on some operating systems, because these methods depend on system libraries for support.
The hash algorithm used on a fresh installation of Windows 7 when exporting via as a PKCS#12 PFX is with an iteration count of 2000.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better; however, some PFX readers might only support SHA-1.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final). However, some PFX readers might only support SHA-1.
]]>
diff --git a/xml/System.Security.Cryptography.Xml/Reference.xml b/xml/System.Security.Cryptography.Xml/Reference.xml
index 17dcd8b1fac..e238b2d4d8f 100644
--- a/xml/System.Security.Cryptography.Xml/Reference.xml
+++ b/xml/System.Security.Cryptography.Xml/Reference.xml
@@ -324,7 +324,7 @@
The digest method is the algorithm used to hash the . The default algorithm is .
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/).
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final). For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/).
]]>
diff --git a/xml/System.Security.Cryptography.Xml/SignedXml.xml b/xml/System.Security.Cryptography.Xml/SignedXml.xml
index 1022478847a..f45affd933a 100644
--- a/xml/System.Security.Cryptography.Xml/SignedXml.xml
+++ b/xml/System.Security.Cryptography.Xml/SignedXml.xml
@@ -2448,7 +2448,7 @@ The X.509 certificate is verified. The
@@ -2585,7 +2585,7 @@ The X.509 certificate is verified. The
@@ -2761,7 +2761,7 @@ The X.509 certificate is verified. The
diff --git a/xml/System.Security.Cryptography/CngAlgorithm.xml b/xml/System.Security.Cryptography/CngAlgorithm.xml
index 81fefe78c38..2e3f259ca1d 100644
--- a/xml/System.Security.Cryptography/CngAlgorithm.xml
+++ b/xml/System.Security.Cryptography/CngAlgorithm.xml
@@ -720,7 +720,7 @@
Gets a new object that specifies the Message Digest 5 (MD5) hash algorithm.
An object that specifies the MD5 algorithm.
- Due to collision problems with MD5, Microsoft recommends a security model based on SHA-256.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
@@ -965,7 +965,7 @@
Gets a new object that specifies the Secure Hash Algorithm 1 (SHA-1) algorithm.
An object that specifies the SHA-1 algorithm.
- Due to collision problems with SHA-1, Microsoft recommends SHA-256.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Security.Cryptography/DES.xml b/xml/System.Security.Cryptography/DES.xml
index 70bb68ebc68..0678b120e38 100644
--- a/xml/System.Security.Cryptography/DES.xml
+++ b/xml/System.Security.Cryptography/DES.xml
@@ -65,8 +65,8 @@
## Remarks
This algorithm supports a key length of 64 bits.
-> [!NOTE]
-> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the class instead of the class. Use only for compatibility with legacy applications and data.
+> [!IMPORTANT]
+> DES is considered insecure because of its 56-bit key size. Consider using a NIST-approved symmetric encryption algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Cryptography/DSA.xml b/xml/System.Security.Cryptography/DSA.xml
index 0220813c5b2..9260e8468f4 100644
--- a/xml/System.Security.Cryptography/DSA.xml
+++ b/xml/System.Security.Cryptography/DSA.xml
@@ -58,7 +58,7 @@
To use a public-key system to digitally sign a message, the sender first applies a hash function to the message to create a message digest. The sender then encrypts the message digest with the sender's private key to create the sender's personal signature. Upon receiving the message and signature, the receiver decrypts the signature using the sender's public key to recover the message digest and hashes the message using the same hash algorithm that the sender used. If the message digest that the receiver computes exactly matches the message digest received from the sender, the receiver can assume that the message was not altered while in transit. Note that a signature can be verified by anyone, because the sender's public key is common knowledge.
> [!IMPORTANT]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
Two different versions of the DSA algorithm exist.
The original form, described in FIPS 186-2, requires the use of SHA-1 as the hash algorithm and supports key lengths from 512 bits to 1024 bits in increments of 64 bits.
diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml
index 6a07a8bfba5..0ea7d0bbed1 100644
--- a/xml/System.Security.Cryptography/DSACng.xml
+++ b/xml/System.Security.Cryptography/DSACng.xml
@@ -137,7 +137,7 @@
Valid key sizes range from 512 to 3,072 bits, in increments of 64. We recommend that a minimum size of 2,048 bits be used for all keys.
> [!IMPORTANT]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml
index da68dc9b6cf..95bd548a017 100644
--- a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml
+++ b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml
@@ -68,8 +68,8 @@
To use a public-key system to digitally sign a message, the sender first applies a hash function to the message to create a message digest. The sender then encrypts the message digest with the sender's private key to create the sender's personal signature. Upon receiving the message and signature, the receiver decrypts the signature using the sender's public key to recover the message digest and hashes the message using the same hash algorithm that the sender used. If the message digest that the receiver computes exactly matches the message digest received from the sender, the receiver can be sure that the message was not altered while in transit. Note that a signature can be verified by anyone, because the sender's public key is common knowledge.
-> [!NOTE]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class instead of the class. Use only for compatibility with legacy applications and data.
+> [!IMPORTANT]
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
This algorithm supports key lengths from 512 bits to 1024 bits in increments of 64 bits.
@@ -1603,7 +1603,7 @@ Setting this property to `true` is equivalent to passing the
diff --git a/xml/System.Security.Cryptography/DSAOpenSsl.xml b/xml/System.Security.Cryptography/DSAOpenSsl.xml
index 61c15b31a02..1668548f80f 100644
--- a/xml/System.Security.Cryptography/DSAOpenSsl.xml
+++ b/xml/System.Security.Cryptography/DSAOpenSsl.xml
@@ -49,7 +49,7 @@
This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop is not needed, you should use the factory methods instead of a specific derived implementation.
> [!IMPORTANT]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
DSAOpenSSL provides the FIPS 186-3 version of DSA.
diff --git a/xml/System.Security.Cryptography/DSAParameters.xml b/xml/System.Security.Cryptography/DSAParameters.xml
index 057faf7713a..4f20713a111 100644
--- a/xml/System.Security.Cryptography/DSAParameters.xml
+++ b/xml/System.Security.Cryptography/DSAParameters.xml
@@ -61,7 +61,7 @@
## Remarks
> [!IMPORTANT]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Cryptography/DSASignatureDeformatter.xml b/xml/System.Security.Cryptography/DSASignatureDeformatter.xml
index 8f6965859b7..cf982582ad6 100644
--- a/xml/System.Security.Cryptography/DSASignatureDeformatter.xml
+++ b/xml/System.Security.Cryptography/DSASignatureDeformatter.xml
@@ -61,7 +61,7 @@
## Remarks
> [!IMPORTANT]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
## Examples
:::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DSASignatureDeformatter/Overview/sample.cs" id="Snippet1":::
diff --git a/xml/System.Security.Cryptography/DSASignatureFormat.xml b/xml/System.Security.Cryptography/DSASignatureFormat.xml
index a7e5dfc58d2..eedcef6d6f6 100644
--- a/xml/System.Security.Cryptography/DSASignatureFormat.xml
+++ b/xml/System.Security.Cryptography/DSASignatureFormat.xml
@@ -35,7 +35,7 @@
## Remarks
> [!IMPORTANT]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Cryptography/DSASignatureFormatter.xml b/xml/System.Security.Cryptography/DSASignatureFormatter.xml
index 6370af25662..e1276140bf6 100644
--- a/xml/System.Security.Cryptography/DSASignatureFormatter.xml
+++ b/xml/System.Security.Cryptography/DSASignatureFormatter.xml
@@ -61,7 +61,7 @@
## Remarks
> [!IMPORTANT]
-> The creators of the DSA algorithm have withdrawn their support for it. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using a NIST-approved digital signature algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
## Examples
:::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DSASignatureFormatter/Overview/sample.cs" id="Snippet1":::
diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml
index 51e1964f2fd..aed38fe7b61 100644
--- a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml
+++ b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml
@@ -1061,7 +1061,7 @@ This instance represents only a public key.
Other custom hash algorithms may also be used.
- Due to collision problems with MD5 and SHA-1, Microsoft recommends . The default algorithm is .
+ Due to collision problems with MD5 and SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final). The default algorithm is .
]]>
diff --git a/xml/System.Security.Cryptography/ECDsaCng.xml b/xml/System.Security.Cryptography/ECDsaCng.xml
index fd04f7f0b98..0da198cf811 100644
--- a/xml/System.Security.Cryptography/ECDsaCng.xml
+++ b/xml/System.Security.Cryptography/ECDsaCng.xml
@@ -685,7 +685,7 @@ If a key is loaded via the . The default algorithm is .
+ Due to collision problems with MD5 and SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final). The default algorithm is .
This property is not used if you are signing or verifying data that is already hashed.
diff --git a/xml/System.Security.Cryptography/HMAC.xml b/xml/System.Security.Cryptography/HMAC.xml
index 232e1a1d567..5e8ad1c7e74 100644
--- a/xml/System.Security.Cryptography/HMAC.xml
+++ b/xml/System.Security.Cryptography/HMAC.xml
@@ -65,7 +65,7 @@
Any change to the data or the hash value results in a mismatch, because knowledge of the secret key is required to change the message and reproduce the correct hash value. Therefore, if the original and computed hash values match, the message is authenticated.
- Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -646,7 +646,7 @@ Derived types must override this method.
Any change to the data or the hash value will result in a mismatch, because knowledge of the secret key is required to change the message and reproduce the correct hash value. Therefore, if the original and computed hash values match, the message is authenticated.
- Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -705,7 +705,7 @@ Derived types must override this method.
Any change to the data or the hash value results in a mismatch, because knowledge of the secret key is required to change the message and reproduce the correct hash value. Therefore, if the original and computed hash values match, the message is authenticated.
- Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
diff --git a/xml/System.Security.Cryptography/HMACMD5.xml b/xml/System.Security.Cryptography/HMACMD5.xml
index 0435cfc55d5..1644f547d5e 100644
--- a/xml/System.Security.Cryptography/HMACMD5.xml
+++ b/xml/System.Security.Cryptography/HMACMD5.xml
@@ -69,7 +69,7 @@
MD5 is a cryptographic hash algorithm developed at RSA Laboratories. accepts keys of any size, and produces a hash sequence that is 128 bits in length.
- Due to collision problems with MD5, Microsoft recommends SHA-256.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -135,7 +135,7 @@
This constructor uses a 64-byte, randomly generated key.
- Due to collision problems with MD5, Microsoft recommends SHA-256.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -199,7 +199,7 @@
This constructor uses a key you provide to create the object.
- Due to collision problems with MD5, Microsoft recommends SHA-256.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
For an example of how to use this constructor, see the class.
diff --git a/xml/System.Security.Cryptography/HMACSHA1.xml b/xml/System.Security.Cryptography/HMACSHA1.xml
index 85082668f24..ce551ae1bfe 100644
--- a/xml/System.Security.Cryptography/HMACSHA1.xml
+++ b/xml/System.Security.Cryptography/HMACSHA1.xml
@@ -72,7 +72,7 @@
accepts keys of any size, and produces a hash sequence that is 160 bits in length.
- Due to collision problems with SHA-1, Microsoft recommends SHA-256.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -132,7 +132,7 @@
This constructor uses a 64-byte, randomly generated key.
- Due to collision problems with SHA-1, Microsoft recommends SHA-256.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -192,7 +192,7 @@
> [!NOTE]
> This constructor creates an unmanaged instance of the algorithm by using the class.
-Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
For an example of how to use this constructor, see the class.
diff --git a/xml/System.Security.Cryptography/HashAlgorithm.xml b/xml/System.Security.Cryptography/HashAlgorithm.xml
index 97364e9cbe6..438b851d2d3 100644
--- a/xml/System.Security.Cryptography/HashAlgorithm.xml
+++ b/xml/System.Security.Cryptography/HashAlgorithm.xml
@@ -71,7 +71,7 @@
The hash is used as a unique value of fixed size representing a large amount of data. Hashes of two sets of data should match if the corresponding data also matches. Small changes to the data result in large unpredictable changes in the hash.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
The following code example computes the hash for an array. This example assumes that there is a predefined byte array `dataArray[]`. is a derived class of .
diff --git a/xml/System.Security.Cryptography/HashAlgorithmName.xml b/xml/System.Security.Cryptography/HashAlgorithmName.xml
index 6b56de1d9b6..023e2d90133 100644
--- a/xml/System.Security.Cryptography/HashAlgorithmName.xml
+++ b/xml/System.Security.Cryptography/HashAlgorithmName.xml
@@ -75,7 +75,7 @@
- Must recognize at least "MD5", "SHA1", "SHA256", "SHA384", and "SHA512".
- Should recognize additional CNG identifiers for any additional hash algorithms that they support.
-Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -366,7 +366,7 @@ Due to collision problems with MD5 and SHA-1, Microsoft recommends a security mo
Gets a hash algorithm name that represents "MD5".
A hash algorithm name that represents "MD5".
- Due to collision problems with MD5, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
@@ -574,7 +574,7 @@ May be `null` or empty to indicate that no hash algorithm is applicable.
Gets a hash algorithm name that represents "SHA1".
A hash algorithm name that represents "SHA1".
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml
index 77143fcb27e..681208c6436 100644
--- a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml
+++ b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml
@@ -66,7 +66,7 @@
Hash functions are commonly used with digital signatures and for data integrity. The class is an example of a keyed hash algorithm.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
The following code example demonstrates how to derive from the class.
diff --git a/xml/System.Security.Cryptography/MD5.xml b/xml/System.Security.Cryptography/MD5.xml
index 5c397719cf0..baaf9524cc1 100644
--- a/xml/System.Security.Cryptography/MD5.xml
+++ b/xml/System.Security.Cryptography/MD5.xml
@@ -62,8 +62,8 @@
The methods of the class return the hash as an array of 16 bytes. Note that some MD5 implementations produce a 32-character, hexadecimal-formatted hash. To interoperate with such implementations, format the return value of the methods as a hexadecimal value.
-> [!NOTE]
-> Due to collision problems with MD5/SHA-1, Microsoft recommends SHA-256 or SHA-512. Consider using the class or the class instead of the class. Use only for compatibility with legacy applications and data.
+> [!IMPORTANT]
+> Due to collision problems with MD5 and SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml b/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml
index b1653bf07cb..349dba4533f 100644
--- a/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml
+++ b/xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml
@@ -119,7 +119,7 @@
## Remarks
This constructor sets to the default hash algorithm name (SHA1).
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -231,7 +231,7 @@
## Remarks
If no hash algorithm is specified, is used by default.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
diff --git a/xml/System.Security.Cryptography/PasswordDeriveBytes.xml b/xml/System.Security.Cryptography/PasswordDeriveBytes.xml
index e391be991f3..4ceab5261a3 100644
--- a/xml/System.Security.Cryptography/PasswordDeriveBytes.xml
+++ b/xml/System.Security.Cryptography/PasswordDeriveBytes.xml
@@ -66,6 +66,9 @@
## Remarks
This class uses an extension of the PBKDF1 algorithm defined in the PKCS#5 v2.0 standard to derive bytes suitable for use as key material from a password. The standard is documented in IETF RRC 2898.
+> [!IMPORTANT]
+> Never use this class for new applications. Use instead. uses the weaker PBKDF1 algorithm, while implements PBKDF2, which is the current recommended standard for password-based key derivation.
+
> [!IMPORTANT]
> Never hard-code a password within your source code. Hard coded passwords can be retrieved from an assembly using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) tool, a hex editor, or by simply opening up the assembly in a text editor like notepad.exe.
diff --git a/xml/System.Security.Cryptography/RC2.xml b/xml/System.Security.Cryptography/RC2.xml
index 65248aee027..6f904fa4184 100644
--- a/xml/System.Security.Cryptography/RC2.xml
+++ b/xml/System.Security.Cryptography/RC2.xml
@@ -64,8 +64,8 @@
## Remarks
-> [!NOTE]
-> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the algorithm and its derived classes instead of the class. Use only for compatibility with legacy applications and data.
+> [!IMPORTANT]
+> RC2 is considered insecure and is not recommended for new applications. Consider using a NIST-approved symmetric encryption algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml
index ad6e17c8e3e..62ffe71500f 100644
--- a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml
+++ b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml
@@ -155,6 +155,9 @@ This constructor creates an method, or any other key import method, before a key is needed then a 1024-bit ephemeral key is created on demand.
+> [!IMPORTANT]
+> A 1024-bit key size is considered insecure. NIST recommends a minimum RSA key size of 2048 bits for new applications. Consider using the constructor with a key size of 2048 or greater, or use instead.
+
## Examples
The following code example uses the class to encrypt a string into an array of bytes and then decrypt the bytes back into a string.
@@ -1906,7 +1909,7 @@ The supported RSA key sizes depend on the available cryptographic service provid
The valid hash algorithms are and . The algorithm identifier can be derived from the hash name by using the method.
- Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
The following code example encrypts some data, creates a hash of the encrypted data, and then signs hash with a digital signature.
@@ -2190,7 +2193,7 @@ Setting this property to `true` is equivalent to passing the and . The algorithm identifier can be derived from the hash name by using the method.
- Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
The following example shows how to use the method to verify a signature. This code example is part of a larger example provided for the method.
diff --git a/xml/System.Security.Cryptography/RSAEncryptionPadding.xml b/xml/System.Security.Cryptography/RSAEncryptionPadding.xml
index 5f66d3b6943..a00e5fa348f 100644
--- a/xml/System.Security.Cryptography/RSAEncryptionPadding.xml
+++ b/xml/System.Security.Cryptography/RSAEncryptionPadding.xml
@@ -435,7 +435,7 @@ If the value of the
Gets an object that represents the Optimal Asymmetric Encryption Padding (OAEP) encryption standard with a SHA-1 hash algorithm.
An object that represents the OAEP encryption standard with a SHA-1 hash algorithm.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
diff --git a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
index c45f64dffa6..bfe5e666710 100644
--- a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
+++ b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
@@ -70,6 +70,9 @@
> [!IMPORTANT]
> Never hard-code a password within your source code. Hard-coded passwords can be retrieved from an assembly by using the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler), by using a hexadecimal editor, or by simply opening up the assembly in a text editor such as Notepad.exe.
+> [!IMPORTANT]
+> The default pseudo-random function (PRF) for this class is HMAC-SHA-1. Due to collision problems with SHA-1, Microsoft recommends using the constructor overloads that accept a parameter, and passing a NIST-approved hash algorithm per [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final). [NIST SP 800-132](https://doi.org/10.6028/NIST.SP.800-132) recommends selecting the highest iteration count that is tolerable for your system, with a minimum of 600,000 iterations.
+
## Examples
The following code example uses the class to create two identical keys for the class. It then encrypts and decrypts some data using the keys.
diff --git a/xml/System.Security.Cryptography/SHA1.xml b/xml/System.Security.Cryptography/SHA1.xml
index cc39600602d..33b880284b2 100644
--- a/xml/System.Security.Cryptography/SHA1.xml
+++ b/xml/System.Security.Cryptography/SHA1.xml
@@ -60,7 +60,7 @@
The hash size for the algorithm is 160 bits.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
diff --git a/xml/System.Security.Cryptography/SHA1Managed.xml b/xml/System.Security.Cryptography/SHA1Managed.xml
index e3176a3710d..9a49187c589 100644
--- a/xml/System.Security.Cryptography/SHA1Managed.xml
+++ b/xml/System.Security.Cryptography/SHA1Managed.xml
@@ -100,7 +100,7 @@
Initializes a new instance of the class.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
This class is not compliant with the FIPS algorithm.
Cryptographic Services
@@ -296,7 +296,7 @@ This method is called by the public
Returns the computed hash value after all data has been written to the object.
The computed hash code.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
Cryptographic Services
@@ -341,7 +341,7 @@ This method is called by the public
Initializes an instance of .
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).
Cryptographic Services
diff --git a/xml/System.Security.Cryptography/TripleDES.xml b/xml/System.Security.Cryptography/TripleDES.xml
index f239e3a4c73..1089a38b051 100644
--- a/xml/System.Security.Cryptography/TripleDES.xml
+++ b/xml/System.Security.Cryptography/TripleDES.xml
@@ -64,8 +64,8 @@
## Remarks
uses three successive iterations of the algorithm. It can use either two or three 56-bit keys.
-> [!NOTE]
-> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the class and its derived classes instead of the class. Use only for compatibility with legacy applications and data.
+> [!IMPORTANT]
+> TripleDES is considered deprecated. Consider using a NIST-approved symmetric encryption algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
This algorithm supports key lengths from 128 bits to 192 bits in increments of 64 bits.
diff --git a/xml/System.Security.Cryptography/TripleDESCng.xml b/xml/System.Security.Cryptography/TripleDESCng.xml
index 2eea0fcc390..a489c0c0fde 100644
--- a/xml/System.Security.Cryptography/TripleDESCng.xml
+++ b/xml/System.Security.Cryptography/TripleDESCng.xml
@@ -57,7 +57,7 @@
## Remarks
> [!IMPORTANT]
-> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the class and its derived classes instead of the class. Use only for compatibility with legacy applications and data.
+> Consider using a NIST-approved symmetric encryption algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml b/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml
index d4bff654af5..e3e13bb143d 100644
--- a/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml
+++ b/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml
@@ -70,8 +70,8 @@
## Remarks
`TripleDESCryptoServiceProvider` is obsolete. Use the method instead.
-> [!NOTE]
-> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the class instead of the class. Use only for compatibility with legacy applications and data.
+> [!IMPORTANT]
+> TripleDES is considered deprecated. Consider using a NIST-approved symmetric encryption algorithm (see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on currently approved algorithms). Use only for compatibility with legacy applications and data.
]]>
diff --git a/xml/System.Security.Policy/Hash.xml b/xml/System.Security.Policy/Hash.xml
index 7d86cc8ff67..962ab5646b6 100644
--- a/xml/System.Security.Policy/Hash.xml
+++ b/xml/System.Security.Policy/Hash.xml
@@ -46,7 +46,7 @@
Hash values are a cryptographically secure way to refer to specific assemblies in policy without the use of digital signatures. A secure hash algorithm is designed so that it is computationally infeasible to construct a different assembly with the identical hash value by either an accidental or malicious attempt. By default, evidence from the and hash algorithms is supported, although any hash algorithm can be used through .
- Due to collision problems with MD5 and SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with MD5 and SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -140,7 +140,7 @@
## Remarks
The returned object contains only the property.
- Due to collision problems with MD5, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -189,7 +189,7 @@
## Remarks
The returned object contains only the property.
- Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -390,7 +390,7 @@
## Remarks
The assembly specified in the class constructor provides the bytes for the hash computation.
- Due to collision problems with MD5, Microsoft recommends SHA-256.
+ Due to collision problems with MD5, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
]]>
@@ -436,7 +436,7 @@
## Remarks
The assembly specified in the constructor provides the bytes for the hash computation.
- Due to collision problems with SHA-1, Microsoft recommends SHA-256.
+ Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function. For guidance on approved algorithms, see [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final).
## Examples
The following example computes the hash for `myAssembly` and stores it in `hashcode`.
diff --git a/xml/System.ServiceModel.Security/SecurityKeyEntropyMode.xml b/xml/System.ServiceModel.Security/SecurityKeyEntropyMode.xml
index 4d7ef9e16e1..26858bd5893 100644
--- a/xml/System.ServiceModel.Security/SecurityKeyEntropyMode.xml
+++ b/xml/System.ServiceModel.Security/SecurityKeyEntropyMode.xml
@@ -118,7 +118,7 @@
2
- The client and server both provide entropy that is combined using the P-SHA1 function to derive the key of the issued token. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better.
+ The client and server both provide entropy that is combined using the P-SHA1 function to derive the key of the issued token. Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function (see NIST SP 800-131A Rev. 2 for guidance on approved algorithms).