issues/44500

Author: Cam Soper

docs/core/compatibility/10.0.md

@@ -2,7 +2,7 @@
 title: Breaking changes in .NET 10
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET 10.
-ms.date: 12/19/2024
+ms.date: 01/30/2025
 no-loc: [Blazor, Razor, Kestrel]
 ---
 # Breaking changes in .NET 10
@@ -20,3 +20,9 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | Title                                                                                    | Type of change      | Introduced version |
 |------------------------------------------------------------------------------------------|---------------------|--------------------|
 | [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md)  | Source incompatible | Preview 1          |
+
+## Cryptography
+
+| Title                                                                                                | Type of change      | Introduced version |
+|------------------------------------------------------------------------------------------------------|---------------------|--------------------|
+| [Rfc2898DeriveBytes constructors are obsolete](cryptography/10.0/rfc2898derivebytes-constructors.md) | Source incompatible | Preview 1          |

docs/core/compatibility/cryptography/10.0/rfc2898derivebytes-constructors.md

@@ -0,0 +1,53 @@
+---
+title: "Breaking change: Rfc2898DeriveBytes constructors are obsolete"
+description: Learn about the .NET 10 breaking change in core .NET libraries where Rfc2898DeriveBytes constructors are obsolete.
+ms.date: 10/10/2023
+---
+# Rfc2898DeriveBytes constructors are obsolete
+
+Starting in .NET 10, all of the constructors on `Rfc2898DeriveBytes` are obsolete.
+
+## Previous behavior
+
+The `Rfc2898DeriveBytes` had constructors that were not obsolete, or obsolete under a different diagnostic ID.
+
+## New behavior
+
+The `Rfc2898DeriveBytes` constructors are obsolete with SYSLIB0060 diagnostic ID and message:
+
+> The constructors on Rfc2898DeriveBytes are obsolete. Use the static Pbkdf2 method instead.
+
+## Version introduced
+
+.NET 10 Preview 1
+
+## Type of breaking change
+
+This change is a [source incompatible](../../categories.md#source-incompatible) change.
+
+## Reason for change
+
+The instance-based implementation of PBKDF2, which `Rfc2898DeriveBytes` provides, offers a non-standard usage by "streaming" bytes back by allowing successive calls to `GetBytes`. This is not the intended use of PBKDF2, the algorithm should be used as a one-shot. The one-shot functionality exists as the static method [`Rfc2898DeriveBytes.Pbkdf2`](https://learn.microsoft.com/dotnet/api/system.security.cryptography.rfc2898derivebytes.pbkdf2) and should be used instead of instantiating `Rfc2898DeriveBytes`.
+
+## Recommended action
+
+Change instances of `Rfc2898DeriveBytes` and calls to `GetBytes` to use the `Pkbdf2` one-shot static method instead.
+
+For example, change:
+
+```csharp
+using System.Security.Cryptography;
+
+Rfc2898DeriveBytes kdf = new Rfc2898DeriveBytes(password, salt, iterations, hashAlgorithm);
+byte[] derivedKey = kdf.GetBytes(64);
+```
+
+to
+
+```csharp
+byte[] derivedKey = Rfc2898DeriveBytes.Pbkdf2(password, salt, iterations, hashAlgorithm, 64);
+```
+
+## Affected APIs
+
+- <xref:System.Security.Cryptography.Rfc2898DeriveBytes.#ctor>

docs/core/compatibility/toc.yml

@@ -12,6 +12,10 @@ items:
             items:
               - name: API obsoletions with non-default diagnostic IDs
                 href: core-libraries/10.0/obsolete-apis.md
+          - name: Cryptography
+            items:
+              - name: RRfc2898DeriveBytes constructors are obsolete
+                href: cryptography/10.0/rfc2898derivebytes-constructors.md
       - name: .NET 9
         items:
           - name: Overview
@@ -1546,6 +1550,10 @@ items:
             href: corefx.md
       - name: Cryptography
         items:
+          - name: .NET 10
+            items:
+              - name: Rfc2898DeriveBytes constructors are obsolete
+                href: cryptography/10.0/rfc2898derivedbytes-constructors.md
           - name: .NET 9
             items:
               - name: SafeEvpPKeyHandle.DuplicateHandle up-refs the handle