From 55762c007298131dd921f18df018226dac26336f Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Fri, 25 Apr 2025 07:02:00 -0700
Subject: [PATCH 1/2] clarify key length parameter

---
 .../Rfc2898DeriveBytes.xml                    | 20 ++++++++-----------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
index 3e89eeceacf..e3c5a00b62b 100644
--- a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
+++ b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
@@ -1039,7 +1039,7 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive.</param>
+        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
         <summary>Creates a PBKDF2 derived key from password bytes.</summary>
         <returns>A byte array containing the created PBKDF2 derived key.</returns>
         <remarks>To be added.</remarks>
@@ -1100,7 +1100,7 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive.</param>
+        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
         <summary>Creates a PBKDF2 derived key from password bytes.</summary>
         <returns>A byte array containing the created PBKDF2 derived key.</returns>
         <remarks>To be added.</remarks>
@@ -1207,17 +1207,15 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive.</param>
+        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
         <summary>Creates a PBKDF2 derived key from a password.</summary>
-        <returns>A byte array of length <paramref name="outputLength" /> that is filled with pseudo-random key bytes.</returns>
+        <returns>A byte array of length <paramref name="outputLength" /> that's filled with pseudo-random key bytes.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-The `password` will be converted to bytes using the UTF8 encoding. For
-            other encodings, convert the password string to bytes using the appropriate <xref:System.Text.Encoding>
-            and use <xref:System.Security.Cryptography.Rfc2898DeriveBytes.Pbkdf2(System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.Int32,System.Security.Cryptography.HashAlgorithmName,System.Int32)>.
+The `password` is converted to bytes using the UTF8 encoding. For other encodings, convert the password string to bytes using the appropriate <xref:System.Text.Encoding> and use <xref:System.Security.Cryptography.Rfc2898DeriveBytes.Pbkdf2(System.ReadOnlySpan{System.Byte},System.ReadOnlySpan{System.Byte},System.Int32,System.Security.Cryptography.HashAlgorithmName,System.Int32)>.
 
           ]]></format>
         </remarks>
@@ -1332,17 +1330,15 @@ The `password` will be converted to bytes using the UTF8 encoding. For
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive.</param>
+        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
         <summary>Creates a PBKDF2 derived key from a password.</summary>
-        <returns>A byte array of length <paramref name="outputLength" /> that is filled with pseudo-random key bytes.</returns>
+        <returns>A byte array of length <paramref name="outputLength" /> that's filled with pseudo-random key bytes.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-The `password` will be converted to bytes using the UTF8 encoding. For
-            other encodings, convert the password string to bytes using the appropriate <xref:System.Text.Encoding>
-            and use <xref:System.Security.Cryptography.Rfc2898DeriveBytes.Pbkdf2(System.Byte[],System.Byte[],System.Int32,System.Security.Cryptography.HashAlgorithmName,System.Int32)>.
+The `password` is converted to bytes using the UTF8 encoding. For other encodings, convert the password string to bytes using the appropriate <xref:System.Text.Encoding> and use <xref:System.Security.Cryptography.Rfc2898DeriveBytes.Pbkdf2(System.Byte[],System.Byte[],System.Int32,System.Security.Cryptography.HashAlgorithmName,System.Int32)>.
 
           ]]></format>
         </remarks>

From 7529ddac4f769a35a6a0c1ac6fc1745e1844bdf8 Mon Sep 17 00:00:00 2001
From: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
Date: Fri, 25 Apr 2025 10:20:15 -0700
Subject: [PATCH 2/2] respond to feedback

---
 .../Rfc2898DeriveBytes.xml                           | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
index e3c5a00b62b..60486010b50 100644
--- a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
+++ b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml
@@ -1039,7 +1039,7 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
+        <param name="outputLength">The size of the key to derive, in bytes.</param>
         <summary>Creates a PBKDF2 derived key from password bytes.</summary>
         <returns>A byte array containing the created PBKDF2 derived key.</returns>
         <remarks>To be added.</remarks>
@@ -1100,7 +1100,7 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
+        <param name="outputLength">The size of the key to derive, in bytes.</param>
         <summary>Creates a PBKDF2 derived key from password bytes.</summary>
         <returns>A byte array containing the created PBKDF2 derived key.</returns>
         <remarks>To be added.</remarks>
@@ -1207,9 +1207,9 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
+        <param name="outputLength">The size of the key to derive, in bytes.</param>
         <summary>Creates a PBKDF2 derived key from a password.</summary>
-        <returns>A byte array of length <paramref name="outputLength" /> that's filled with pseudo-random key bytes.</returns>
+        <returns>A byte array of length <paramref name="outputLength" /> that is filled with pseudo-random key bytes.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
@@ -1330,9 +1330,9 @@ The `password` will be converted to bytes using the UTF8 encoding. For
         <param name="salt">The key salt used to derive the key.</param>
         <param name="iterations">The number of iterations for the operation.</param>
         <param name="hashAlgorithm">The hash algorithm to use to derive the key.</param>
-        <param name="outputLength">The size of key to derive (that is, the number of elements in the byte array).</param>
+        <param name="outputLength">The size of the key to derive, in bytes.</param>
         <summary>Creates a PBKDF2 derived key from a password.</summary>
-        <returns>A byte array of length <paramref name="outputLength" /> that's filled with pseudo-random key bytes.</returns>
+        <returns>A byte array of length <paramref name="outputLength" /> that is filled with pseudo-random key bytes.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[