[API Proposal]: Obsolete all Rfc2898DeriveBytes constructors

[vcsjones]

Background and motivation

Rfc2898DeriveBytes implements RFC 2898 (PBKDF2) and offers two ways to use it: create an instance or use static one-shots.

The instance based implementation provides the ability to "stream" bytes back from the KDF. Successive calls to GetBytes do not reset the in-progress operation.

This streaming behavior was never an intended use case of RFC 2898 (or its successor RFC 8018). Further, none of the underlying platforms implement PBKDF2 in a way that supports streaming. So the streaming implementation will always need to be managed on top of HMAC.

Since streaming is the only real reason to instantiate the class instead of using the one-shots, I propose obsoleting the constructors with the recommendation that the one-shot be used.

A slight complication from this is that the class is not sealed. A quick code search however indicates that few folks are regularly deriving from this class.

Since this class already has obsolete constructors, I propose re-obsoleting the current ones under a different SYSLIB since the new obsoletion is "stronger". This will also cause people that suppressed the obsoletion to re-evaluate the suppression.

API Proposal

public partial class Rfc2898DeriveBytes : DeriveBytes
{
-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(byte[] password, byte[] salt, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(byte[] password, byte[] salt, int iterations, HashAlgorithmName hashAlgorithm);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt, int iterations, HashAlgorithmName hashAlgorithm);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize, int iterations, HashAlgorithmName hashAlgorithm);

API Usage

Alternative Designs

No response

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/area-system-security, @bartonjs, @vcsjones
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Rfc2898DeriveBytes implements RFC 2898 (PBKDF2) and offers two ways to use it: create an instance or use static one-shots.

The instance based implementation provides the ability to "stream" bytes back from the KDF. Successive calls to GetBytes do not reset the in-progress operation.

This streaming behavior was never an intended use case of RFC 2898 (or its successor RFC 8018). Further, none of the underlying platforms implement PBKDF2 in a way that supports streaming. So the streaming implementation will always need to be managed on top of HMAC.

Since streaming is the only real reason to instantiate the class instead of using the one-shots, I propose obsoleting the constructors with the recommendation that the one-shot be used.

A slight complication from this is that the class is not sealed. A quick code search however indicates that few folks are regularly deriving from this class.

Since this class already has obsolete constructors, I propose re-obsoleting the current ones under a different SYSLIB since the new obsoletion is "stronger". This will also cause people that suppressed the obsoletion to re-evaluate the suppression.

API Proposal

public partial class Rfc2898DeriveBytes : DeriveBytes
{
-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(byte[] password, byte[] salt, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(byte[] password, byte[] salt, int iterations, HashAlgorithmName hashAlgorithm);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt, int iterations, HashAlgorithmName hashAlgorithm);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize, int iterations, HashAlgorithmName hashAlgorithm);

API Usage

Alternative Designs

No response

Risks

No response

Author:	vcsjones
Assignees:	-
Labels:	api-suggestion, area-System.Security
Milestone:	-

[terrajobst]

Video

• Looks good as proposed

namespace System.Security.Cryptography;

public partial class Rfc2898DeriveBytes : DeriveBytes
{
-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(byte[] password, byte[] salt, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(byte[] password, byte[] salt, int iterations, HashAlgorithmName hashAlgorithm);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, byte[] salt, int iterations, HashAlgorithmName hashAlgorithm);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize);

-       [Obsolete(Obsoletions.Rfc2898OutdatedCtorMessage, DiagnosticId = Obsoletions.Rfc2898OutdatedCtorDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize, int iterations);

+       [Obsolete("Creating instances of Rfc2898DeriveBytes is obsolete. Use the static Pbkdf2 method instead.", DiagnosticId = "SYSLIBXXXX", UrlFormat = Obsoletions.SharedUrlFormat)]
        public Rfc2898DeriveBytes(string password, int saltSize, int iterations, HashAlgorithmName hashAlgorithm);
}