Replace specific crypto algorithm recommendations with NIST-approved references by Copilot · Pull Request #12524 · dotnet/dotnet-api-docs

Copilot · 2026-04-16T11:13:11Z

Security warnings across the docs recommend specific algorithms (AES, SHA-256, RSA, ECDsa) as replacements for deprecated ones. These become stale as standards evolve — e.g., "use Aes (AES-256)" is already not future-proof.

All recommendations now defer to NIST SP 800-131A Rev. 2 instead of naming specific algorithms.

XML docs (~37 files)

Symmetric ciphers (DES, TripleDES, RC2, EncryptedXml): "use AES" → "NIST-approved symmetric encryption algorithm"
Hash functions (~50 instances across SignedXml, Pkcs12Builder, SecurityAlgorithmSuite, HttpHeaders, etc.): "SHA-256 or better" → "NIST-approved hash function"
Digital signatures (DSA family): "use RSA/ECDsa" → "NIST-approved digital signature algorithm"
PBKDF2 (Rfc2898DeriveBytes): "pass SHA-256 or higher" → "pass a NIST-approved hash algorithm"; iteration count updated from 1,000 → 600,000

Snippet code comments (~25 files)

// For new applications, use Aes (AES-256) instead. → // For new applications, use a NIST-approved symmetric encryption algorithm instead.
// Microsoft recommends SHA256 or better. → // Microsoft recommends using a NIST-approved hash function.

Pattern used

Due to collision problems with SHA-1, Microsoft recommends using a NIST-approved hash function.

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).

Factual statements about API defaults (e.g., "The default algorithm is CngAlgorithm.Sha256") and Rijndael→Aes migration guidance are preserved — only recommendations were changed.

…ryptedXml, and ASP.NET examples - Update PBKDF2 minimum iteration count from 1000 to 600,000 per OWASP 2025 - Add OWASP reference link for iteration count guidance - Add security note to Rfc2898DeriveBytes code snippets (C# and VB) - Add note that TripleDES in EncryptedXml example is illustrative only - Clarify SHA1 usage in MachineKeySection and MembershipPasswordFormat examples is for illustration, not recommendation Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/764780ef-fe2f-488d-b3b1-2622af6cb005 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…-bit key warning, hardcoded credentials, SQL injection - Add PBKDF1 weakness warning to PasswordDeriveBytes.xml with recommendation to use Rfc2898DeriveBytes - Add NIST minimum key size warning to RSACryptoServiceProvider.xml for 1024-bit default - Add "do not hardcode credentials" comments to misleading SecurelyStoredPassword snippets (C# and VB) - Add SQL injection warning comment to DataGridView employees.cs example Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/1292907e-994a-4770-9f47-ba31729d934e Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…efault, TLS 1.0/1.1 vulnerabilities, RC4 in MSMQ - DSACryptoServiceProvider.xml: Upgrade to IMPORTANT, warn 512-1024 bit keys are insecure, recommend DSA.Create for 2048+ - Rfc2898DeriveBytes.xml: Add class-level warning about default HMAC-SHA-1 PRF, recommend SHA-256 overloads - SecurityProtocolType.xml: Add known vulnerability warnings to Tls and Tls11 enum field summaries - MsmqTransportSecurityElement.xml and MsmqTransportSecurity.xml: Add RC4 insecurity warning, recommend AES Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/5d6f4eab-cf75-4f5a-86b6-db08ca720b4d Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/75297ead-2a52-4a34-a843-db016131f9f7 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…DES config provider, and WCF hardcoded credentials Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/75297ead-2a52-4a34-a843-db016131f9f7 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…o algorithms and add vulnerability language to SslProtocols TLS 1.0/1.1 Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/452aea0d-c0b7-46fe-9fbe-76242e56ebcb Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…ocs and snippets Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/e5f9f9dc-69ad-43bd-b467-f26bc97ce339 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…oved references Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/25244212-cd49-4dbd-878a-86f746c5cda1 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

… from security warnings Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/d7f4e225-3eb2-4280-b694-49040e1d501c Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

… NIST-approved language Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/c2c03b41-0436-4500-8045-5258ecf761bb Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…age across 34 XML docs Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/6dd58f84-d55d-4ebe-96bd-c0632ea15c42 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

…T-approved language Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/6dd58f84-d55d-4ebe-96bd-c0632ea15c42 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Copilot

Pull request overview

This PR updates .NET API reference documentation and snippet comments to avoid recommending specific cryptographic algorithms, instead steering readers toward NIST guidance (notably NIST SP 800-131A Rev. 2), and refreshes PBKDF2 iteration guidance.

Changes:

Replaces “use AES/SHA-256/RSA/ECDsa” style recommendations with “NIST-approved …” guidance across many XML docs and snippets.
Updates PBKDF2 (Rfc2898DeriveBytes) guidance (including minimum recommended iterations) and adds clearer security notes about defaults.
Adds/updates snippet safety comments (hard-coded credentials, SQL injection, deprecated/weak crypto).

Reviewed changes

Copilot reviewed 115 out of 115 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
xml/System.Workflow.ComponentModel.Compiler/WorkflowMarkupSourceAttribute.xml	Switches MD5 replacement guidance to “NIST-approved hash function.”
xml/System.Web/HttpWorkerRequest.xml	Updates MD5 guidance to “NIST-approved hash function.”
xml/System.Web.Security/SqlMembershipProvider.xml	Updates SHA1 guidance to “NIST-approved hash function.”
xml/System.Web.Security/MembershipPasswordFormat.xml	Updates SHA1 guidance and clarifies illustrative-only usage.
xml/System.Web.Configuration/MachineKeySection.xml	Updates SHA1 example guidance and clarifies illustrative-only usage.
xml/System.Web.Configuration/FormsAuthPasswordFormat.xml	Updates MD5/SHA1 guidance to “NIST-approved hash function.”
xml/System.ServiceModel/MsmqTransportSecurity.xml	Adds RC4 insecurity warning; updates SHA-1 hash guidance to NIST-approved language.
xml/System.ServiceModel/MsmqSecureHashAlgorithm.xml	Updates MD5/SHA-1 guidance to “NIST-approved hash function.”
xml/System.ServiceModel.Security/TripleDesSecurityAlgorithmSuite.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.ServiceModel.Security/SecurityKeyEntropyMode.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.ServiceModel.Security/Basic256SecurityAlgorithmSuite.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.ServiceModel.Security/Basic192SecurityAlgorithmSuite.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.ServiceModel.Security/Basic128SecurityAlgorithmSuite.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.ServiceModel.Configuration/MsmqTransportSecurityElement.xml	Mirrors MSMQ RC4 warning addition in configuration element docs.
xml/System.Security.Policy/Hash.xml	Updates MD5/SHA-1 guidance to “NIST-approved hash function.”
xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml	Replaces AES recommendation with NIST-approved symmetric encryption guidance + NIST link.
xml/System.Security.Cryptography/TripleDESCng.xml	Replaces AES recommendation with NIST-approved symmetric encryption guidance + NIST link.
xml/System.Security.Cryptography/TripleDES.xml	Replaces AES recommendation with NIST-approved symmetric encryption guidance + NIST link.
xml/System.Security.Cryptography/SHA1Managed.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/SHA1CryptoServiceProvider.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/SHA1Cng.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/SHA1.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml	Adds PRF/default guidance and updates minimum iteration recommendation to 600,000 with NIST references.
xml/System.Security.Cryptography/RSAEncryptionPadding.xml	Updates SHA-1 guidance to NIST-approved language (NIST SP reference).
xml/System.Security.Cryptography/RSACryptoServiceProvider.xml	Adds RSA key-size warning and updates hash guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml	Replaces AES recommendation with NIST-approved symmetric encryption guidance + NIST link.
xml/System.Security.Cryptography/RC2.xml	Replaces AES recommendation with NIST-approved symmetric encryption guidance + NIST link.
xml/System.Security.Cryptography/PasswordDeriveBytes.xml	Adds guidance to avoid PBKDF1 for new applications in favor of PBKDF2.
xml/System.Security.Cryptography/PKCS1MaskGenerationMethod.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/MD5CryptoServiceProvider.xml	Replaces specific hash recommendations with NIST-approved guidance + NIST link.
xml/System.Security.Cryptography/MD5.xml	Replaces specific hash recommendations with NIST-approved guidance + NIST link.
xml/System.Security.Cryptography/KeyedHashAlgorithm.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/HashAlgorithmName.xml	Updates MD5/SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/HashAlgorithm.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/HMACSHA1.xml	Updates SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/HMACRIPEMD160.xml	Updates MD4/MD5 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/HMACMD5.xml	Updates MD5 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/HMAC.xml	Updates MD5/SHA-1 guidance to NIST-approved language + NIST link.
xml/System.Security.Cryptography/ECDsaCng.xml	Updates hash guidance to NIST-approved language + NIST link while retaining default algorithm fact.
xml/System.Security.Cryptography/ECDiffieHellmanCng.xml	Updates hash guidance to NIST-approved language + NIST link while retaining default algorithm fact.
xml/System.Security.Cryptography/DSASignatureFormatter.xml	Replaces RSA/ECDsa recommendation with NIST-approved digital signature guidance + NIST link.
xml/System.Security.Cryptography/DSASignatureFormat.xml	Replaces RSA/ECDsa recommendation with NIST-approved digital signature guidance + NIST link.
xml/System.Security.Cryptography/DSASignatureDeformatter.xml	Replaces RSA/ECDsa recommendation with NIST-approved digital signature guidance + NIST link.
xml/System.Security.Cryptography/DSAParameters.xml	Replaces RSA/ECDsa recommendation with NIST-approved digital signature guidance + NIST link.
xml/System.Security.Cryptography/DSAOpenSsl.xml	Replaces RSA/ECDsa recommendation with NIST-approved digital signature guidance + NIST link.
xml/System.Security.Cryptography/DSACryptoServiceProvider.xml	Replaces RSA recommendation with NIST-approved digital signature guidance + NIST link; updates SHA-1 guidance.
xml/System.Security.Cryptography/DSACng.xml	Replaces RSA/ECDsa recommendation with NIST-approved digital signature guidance + NIST link.
xml/System.Security.Cryptography/DSA.xml	Replaces RSA/ECDsa recommendation with NIST-approved digital signature guidance + NIST link.
xml/System.Security.Cryptography/DESCryptoServiceProvider.xml	Replaces AES recommendation with NIST-approved symmetric encryption guidance + NIST link.
xml/System.Security.Cryptography/DES.xml	Strengthens DES deprecation warning and switches to NIST-approved symmetric encryption guidance + NIST link.
xml/System.Security.Cryptography/CngAlgorithm.xml	Updates MD5/SHA-1 guidance to NIST-approved language (NIST SP reference).
xml/System.Security.Cryptography.Xml/SignedXml.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.Security.Cryptography.Xml/Reference.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.Security.Cryptography.Xml/EncryptedXml.xml	Adds “illustrative only” note for TripleDES example and suggests NIST-approved symmetric encryption.
xml/System.Security.Cryptography.Pkcs/Pkcs12Builder.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.Security.Authentication/SslProtocols.xml	Updates TLS 1.0/1.1 summaries to note known vulnerabilities and recommend newer protocols.
xml/System.Security.Authentication/HashAlgorithmType.xml	Updates MD5/SHA-1 guidance to “NIST-approved hash function.”
xml/System.Reflection/AssemblyHashAlgorithm.xml	Updates MD5/SHA-1 guidance to “NIST-approved hash function.”
xml/System.Net/SecurityProtocolType.xml	Updates TLS 1.0/1.1 summaries to note known vulnerabilities and recommend newer protocols.
xml/System.Net/HttpResponseHeader.xml	Updates Content-MD5 guidance to “NIST-approved hash function.”
xml/System.Net/HttpRequestHeader.xml	Updates Content-MD5 guidance to “NIST-approved hash function.”
xml/System.Net.Http.Headers/HttpContentHeaders.xml	Updates Content-MD5 guidance to “NIST-approved hash function.”
xml/System.Messaging/Message.xml	Updates MD5/SHA-1 guidance to “NIST-approved hash function.”
xml/System.Messaging/DefaultPropertiesToSend.xml	Updates MD5 guidance to “NIST-approved hash function.”
xml/System.IdentityModel/RsaSignatureCookieTransform.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.IdentityModel/RsaEncryptionCookieTransform.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.IdentityModel.Tokens/X509AsymmetricSecurityKey.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.IdentityModel.Tokens/SecurityAlgorithms.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.IdentityModel.Tokens/InMemorySymmetricSecurityKey.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.IO.Packaging/PackageDigitalSignatureManager.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.Configuration.Assemblies/AssemblyHashAlgorithm.xml	Updates SHA-1 guidance to “NIST-approved hash function.”
xml/System.CodeDom/CodeChecksumPragma.xml	Updates SHA-1/MD5 guidance to “NIST-approved hash function.”
snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProtectedConfigurationProvider/VB/ProtectedConfigurationProviderLib.vb	Adds TripleDES deprecation warning and NIST-approved guidance.
snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform/VB/Xslt_Transform_v2.vb	Adds guidance not to hardcode credentials and to use a secure store.
snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Load/VB/Xslt_Load_v2.vb	Adds guidance not to hardcode credentials and to use a secure store.
snippets/visualbasic/VS_Snippets_Data/XmlResolver_Samples/VB/XmlResolver_Samples.vb	Adds guidance not to hardcode credentials and to use a secure store.
snippets/visualbasic/VS_Snippets_Data/XmlReader.Create/VB/XmlReader_Create.vb	Adds guidance not to hardcode credentials and to use a secure store.
snippets/visualbasic/VS_Snippets_CFX/samlattribute/vb/source.vb	Updates SHA1 collision guidance to NIST-approved wording.
snippets/visualbasic/VS_Snippets_CFX/s_ueclientcredentials/vb/program.vb	Adds guidance not to hardcode credentials and to use a secure store.
snippets/visualbasic/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.vb	Updates PBKDF2 iteration-count comment to reference NIST SP 800-132 guidance.
snippets/visualbasic/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.vb	Updates SHA1 collision guidance to NIST-approved wording.
snippets/visualbasic/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.vb	Updates SHA1 collision guidance to NIST-approved wording.
snippets/visualbasic/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.vb	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/visualbasic/System.Security.Cryptography/DESCryptoServiceProvider/CreateEncryptor/memoryexample.vb	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/visualbasic/System.Security.Cryptography/DESCryptoServiceProvider/CreateEncryptor/fileexample.vb	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/visualbasic/System.Security.Cryptography/DES/Create/memoryexample.vb	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/visualbasic/System.Security.Cryptography/DES/Create/fileexample.vb	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/visualbasic/System.Security.Cryptography/CryptoConfig/Overview/members.vb	Updates SHA1 collision guidance to NIST-approved wording.
snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb	Updates SHA1 collision guidance to NIST-approved wording.
snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb	Updates SHA1/MD5 collision guidance to NIST-approved wording.
snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProtectedConfigurationProvider/CS/ProtectedConfigurationProviderLib.cs	Adds TripleDES deprecation warning and NIST-approved guidance.
snippets/csharp/VS_Snippets_CFX/windowsclientcredential/cs/source.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/VS_Snippets_CFX/samlattribute/cs/source.cs	Updates SHA1 collision guidance to NIST-approved wording.
snippets/csharp/VS_Snippets_CFX/s_uex509certificatevalidationmode/cs/client.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/VS_Snippets_CFX/s_ueclientcredentials/cs/program.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/VS_Snippets_CFX/s_ue_httpdigestclientcredential/cs/source.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/System.Xml/XmlUrlResolver/Overview/XmlResolver_Samples.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/System.Xml/XmlResolver/Overview/Xslt_Load_v2.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/System.Xml/XmlParserContext/Overview/XmlReader_Create.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/System.Xml.Xsl/XslCompiledTransform/Overview/Xslt_Transform_v2.cs	Adds guidance not to hardcode credentials and to use a secure store.
snippets/csharp/System.Windows.Forms/DataGridView/CellContentClick/employees.cs	Adds SQL injection warning and recommends parameterized queries.
snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs	Updates PBKDF2 iteration-count comment to reference NIST SP 800-132 guidance.
snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/SignHash/class1.cs	Updates SHA1 collision guidance to NIST-approved wording.
snippets/csharp/System.Security.Cryptography/PasswordDeriveBytes/Overview/sample.cs	Updates SHA1 collision guidance to NIST-approved wording.
snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/CreateEncryptor/memoryexample.cs	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/CreateEncryptor/fileexample.cs	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/csharp/System.Security.Cryptography/DES/Create/memoryexample.cs	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/csharp/System.Security.Cryptography/DES/Create/fileexample.cs	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/csharp/System.Security.Cryptography/CryptoConfig/Overview/members.cs	Updates SHA1 collision guidance to NIST-approved wording.
snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs	Adds DES insecurity warning and NIST-approved symmetric encryption guidance.
snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs	Updates SHA1 collision guidance to NIST-approved wording.
snippets/csharp/System.Net/ICertificatePolicy/Overview/source.cs	Adds warning about obsolete API and certificate-validation bypass risks.
snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs	Updates SHA1/MD5 collision guidance to NIST-approved wording.

Copilot · 2026-04-16T11:19:48Z

 The digest method is the algorithm used to hash the <xref:System.Security.Cryptography.Xml.Reference>. The default algorithm is <xref:System.Security.Cryptography.SHA256>.

- 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 more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/).


This updated guidance refers to a “NIST-approved hash function” but doesn’t include a link to NIST SP 800-131A Rev. 2. Adding the link would make the recommendation actionable and consistent with other crypto warnings in this PR.

Copilot · 2026-04-16T11:19:49Z


 The hash algorithm used on a fresh installation of Windows 7 when exporting via <xref:System.Security.Cryptography.X509Certificates.X509Certificate.Export*?displayProperty=nameWithtype> as a PKCS#12 PFX is <xref:System.Security.Cryptography.HashAlgorithmName.SHA1> 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; however, some PFX readers might only support SHA-1.


This sentence switches to “NIST-approved hash function” but doesn’t provide the NIST SP 800-131A Rev. 2 link that the PR description calls out. Consider adding the link so readers can find the current approved set.

Copilot · 2026-04-16T11:19:49Z

 The hash size for the <xref:System.Security.Cryptography.SHA1Managed> 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. See [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on approved algorithms.


Within this file, the top-level remarks say “Microsoft recommends a security model based on a NIST-approved hash function”, but other updated remarks use “Microsoft recommends using a NIST-approved hash function”. Consider standardizing the phrasing (prefer the direct “recommends using …”) to improve readability and consistency.

Copilot · 2026-04-16T11:19:50Z

 For more information, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/2000/09/xmldsig#hmac-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.


This recommendation references a “NIST-approved hash function” but doesn’t link to the referenced NIST guidance. Consider adding the NIST SP 800-131A Rev. 2 link (as done in other updated crypto warnings) so readers can verify currently approved algorithms.

Copilot · 2026-04-16T11:19:50Z

 For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#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.


This recommendation references a “NIST-approved hash function” but doesn’t link to the NIST guidance. Consider adding the NIST SP 800-131A Rev. 2 link so the reader can find the current approved-algorithm list.

Copilot · 2026-04-16T11:19:50Z


 The hash algorithm used on a fresh installation of Windows 7 when exporting via <xref:System.Security.Cryptography.X509Certificates.X509Certificate.Export*?displayProperty=nameWithType> as a PKCS#12 PFX is <xref:System.Security.Cryptography.HashAlgorithmName.SHA1> 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; however, some PFX readers might only support SHA-1.


Same as earlier in this file: consider adding the NIST SP 800-131A Rev. 2 link when recommending a “NIST-approved hash function”, to keep the guidance actionable and consistent.

Copilot · 2026-04-16T11:19:50Z

+> [!IMPORTANT]
+> RC4 is considered insecure and is no longer recommended for new applications. If the message queue infrastructure supports it, prefer using <xref:System.ServiceModel.MsmqEncryptionAlgorithm.Aes> instead.


The new RC4 warning recommends a specific replacement algorithm (Aes). This conflicts with the PR goal of avoiding specific algorithm recommendations and can become stale. Prefer wording like “use a NIST-approved symmetric encryption algorithm” and include the NIST SP 800-131A Rev. 2 link for guidance.

Copilot · 2026-04-16T11:19:51Z

+> [!IMPORTANT]
+> RC4 is considered insecure and is no longer recommended for new applications. If the message queue infrastructure supports it, prefer using <xref:System.ServiceModel.MsmqEncryptionAlgorithm.Aes> instead.


This warning recommends xref:System.ServiceModel.MsmqEncryptionAlgorithm.Aes, which reintroduces a specific algorithm recommendation. To align with the PR intent, replace it with guidance to use a NIST-approved symmetric encryption algorithm (with the NIST SP 800-131A Rev. 2 link).

Copilot · 2026-04-16T11:19:51Z

 For more information, see the [World Wide Web Consortium (W3C) schema](https://www.w3.org/2000/09/xmldsig#rsa-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.


This recommendation references a “NIST-approved hash function” but doesn’t link to the NIST guidance. Consider adding the NIST SP 800-131A Rev. 2 link for completeness and consistency with other warnings.

gewarren · 2026-04-16T17:42:09Z


        // 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.


Should this be:

Suggested change

// Due to collision problems with SHA1 and MD5, Microsoft recommends using a NIST-approved hash function.

// Due to collision problems with SHA1 and MD5, Microsoft recommends using an NIST-approved hash function.

gewarren · 2026-04-16T17:42:48Z

 // This sample demonstrates how to use each member of the CryptoAPITransform
 // class.
+// WARNING: DES has a 56-bit key and is considered insecure.
+// For new applications, use a NIST-approved symmetric encryption algorithm instead.


Suggested change

// For new applications, use a NIST-approved symmetric encryption algorithm instead.

// For new applications, use an NIST-approved symmetric encryption algorithm instead.

gewarren · 2026-04-16T17:48:00Z

+        // WARNING: This example uses string concatenation for simplicity.
+        // In production code, always use parameterized queries to prevent
+        // SQL injection attacks.
        DataGridView2.DataSource = Populate("SELECT * FROM Orders WHERE EmployeeId = " + employeeId);


If it's straightforward to use a parameterized query, I think we should do that, or I can do it in a follow up PR.

gewarren · 2026-04-16T17:48:40Z

 	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";


Maybe we should rename the variable to something like insecurelyStoredPassword?

gewarren · 2026-04-16T17:51:27Z

      <MemberValue>192</MemberValue>
      <Docs>
-        <summary>Specifies the Transport Layer Security (TLS) 1.0 security protocol. The TLS 1.0 protocol is defined in IETF RFC 2246.</summary>
+        <summary>Specifies the Transport Layer Security (TLS) 1.0 security protocol. The TLS 1.0 protocol is defined in IETF RFC 2246. TLS 1.0 has known vulnerabilities and is not recommended. Use <see cref="F:System.Net.SecurityProtocolType.Tls12" />, <see cref="F:System.Net.SecurityProtocolType.Tls13" />, or <see cref="F:System.Net.SecurityProtocolType.SystemDefault" /> instead.</summary>


Is it okay to move this new text to the Remarks instead?

gewarren · 2026-04-16T17:55:48Z

 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. See [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on approved algorithms.


@copilot please change all occurrences of "See NIST SP 800-131A Rev. 2 for guidance on approved algorithms" to "For guidance on approved algorithms, see NIST SP 800-131A Rev. 2".

gewarren · 2026-04-16T17:56:47Z

@@ -77,7 +77,7 @@
 The <xref:System.Security.Cryptography.HashAlgorithm.ComputeHash*> methods of the <xref:System.Security.Cryptography.MD5> 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 <xref:System.Security.Cryptography.HashAlgorithm.ComputeHash*> methods as a hexadecimal value.

 > [!NOTE]


Suggested change

> [!NOTE]

> [!IMPORTANT]

gewarren · 2026-04-16T17:58:23Z

 > 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 <xref:System.Security.Cryptography.HashAlgorithmName> 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.


Suggested change

> 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 <xref:System.Security.Cryptography.HashAlgorithmName> 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.

> 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 <xref:System.Security.Cryptography.HashAlgorithmName> parameter, and passing an 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.

gewarren · 2026-04-16T17:59:08Z

 >  This type implements the <xref:System.IDisposable> interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its <xref:System.IDisposable.Dispose*> method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the <xref:System.IDisposable> interface topic.

-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. See [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on approved algorithms.


Suggested change

Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. See [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on approved algorithms.

Due to collision problems with SHA-1, Microsoft recommends a security model based on an NIST-approved hash function. See [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on approved algorithms.

Not sure if it's generally pronounced "nist" or "n-i-s-t". If the latter, the article should be "an".

I'd say it's 99:1 "nist" over "N-I-S-T". So "NIST SP 800-131A" is "nist s-p eight hundred, one thirty one, a". ChatGPT's take on turning that into IPA is /nɪst ˌɛs ˈpiː ˌeɪt ˈhʌndrəd wʌn ˈθɜrti wʌn eɪ/, which looks sort of right? 😄

Copilot · 2026-04-16T18:02:05Z

@gewarren I've opened a new pull request, #12526, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot AI and others added 12 commits April 15, 2026 10:00

Revert DSACryptoServiceProvider changes (DSA is already not recommended)

3982903

Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/75297ead-2a52-4a34-a843-db016131f9f7 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Replace OWASP references with NIST SP 800-132 in Rfc2898DeriveBytes d…

7408d44

…ocs and snippets Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/e5f9f9dc-69ad-43bd-b467-f26bc97ce339 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Replace specific crypto algorithm recommendations with NIST/FIPS-appr…

24cc5a9

…oved references Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/25244212-cd49-4dbd-878a-86f746c5cda1 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Remove remaining specific algorithm recommendations (AES, RSA, ECDsa)…

4f51ea9

… from security warnings Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/d7f4e225-3eb2-4280-b694-49040e1d501c Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Replace specific Aes/AES-256 recommendations in snippet comments with…

fd2099d

… NIST-approved language Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/c2c03b41-0436-4500-8045-5258ecf761bb Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Replace SHA-256/Aes-specific recommendations with NIST-approved langu…

b0d07c7

…age across 34 XML docs Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/6dd58f84-d55d-4ebe-96bd-c0632ea15c42 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Replace SHA-256-specific recommendations in 12 snippet files with NIS…

8c27d1c

…T-approved language Agent-Logs-Url: https://github.com/dotnet/dotnet-api-docs/sessions/6dd58f84-d55d-4ebe-96bd-c0632ea15c42 Co-authored-by: krwq <660048+krwq@users.noreply.github.com>

Copilot AI assigned Copilot and krwq Apr 16, 2026

Copilot created this pull request from a session on behalf of krwq April 16, 2026 11:13 View session

krwq marked this pull request as ready for review April 16, 2026 11:13

krwq requested review from a team and mconnew as code owners April 16, 2026 11:13

krwq requested review from Copilot and jeffhandley April 16, 2026 11:13

github-actions bot added the area-Meta Concerns something that extends across runtime area boundaries, for example, IDisposable. label Apr 16, 2026

krwq requested review from GrabYourPitchforks, bartonjs and blowdart April 16, 2026 11:14

Copilot started reviewing on behalf of krwq April 16, 2026 11:15 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

gewarren reviewed Apr 16, 2026

View reviewed changes

Copilot AI mentioned this pull request Apr 16, 2026

Standardize NIST guidance sentence order in crypto XML docs #12526

Merged

Standardize NIST guidance sentence order in crypto XML docs (#12526)

5b93c40

		> [!IMPORTANT]
		> RC4 is considered insecure and is no longer recommended for new applications. If the message queue infrastructure supports it, prefer using <xref:System.ServiceModel.MsmqEncryptionAlgorithm.Aes> instead.

	// Due to collision problems with SHA1 and MD5, Microsoft recommends using a NIST-approved hash function.
	// Due to collision problems with SHA1 and MD5, Microsoft recommends using an NIST-approved hash function.

	// For new applications, use a NIST-approved symmetric encryption algorithm instead.
	// For new applications, use an NIST-approved symmetric encryption algorithm instead.

		@@ -77,7 +77,7 @@
		The <xref:System.Security.Cryptography.HashAlgorithm.ComputeHash> methods of the <xref:System.Security.Cryptography.MD5> 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 <xref:System.Security.Cryptography.HashAlgorithm.ComputeHash> methods as a hexadecimal value.

		> [!NOTE]

	Due to collision problems with SHA-1, Microsoft recommends a security model based on a NIST-approved hash function. See [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on approved algorithms.
	Due to collision problems with SHA-1, Microsoft recommends a security model based on an NIST-approved hash function. See [NIST SP 800-131A Rev. 2](https://csrc.nist.gov/pubs/sp/800/131/a/r2/final) for guidance on approved algorithms.

Conversation

Copilot AI commented Apr 16, 2026

XML docs (~37 files)

Snippet code comments (~25 files)

Pattern used

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants