Update DuplicateHandle remarks for .NET 9 (dotnet#10203)

Author: gewarren

xml/System.Security.Cryptography/ECDsaOpenSsl.xml

@@ -44,12 +44,11 @@
   <Docs>
     <summary>Provides an implementation of the Elliptic Curve Digital Signature Algorithm (ECDSA) backed by OpenSSL.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
-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 <xref:System.Security.Cryptography.ECDsa.Create%2A?displayProperty=nameWithType> factory methods instead of a specific derived implementation.
-  
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
+This class should only be used directly when doing platform interop with the system OpenSSL library. When platform interop isn't needed, you should use the <xref:System.Security.Cryptography.ECDsa.Create%2A?displayProperty=nameWithType> factory methods instead of a specific derived implementation.
+
  ]]></format>
     </remarks>
   </Docs>
@@ -99,15 +98,14 @@ When platform interop is not needed, you should use the <xref:System.Security.Cr
       <Docs>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.ECDsaOpenSsl" /> class.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 This constructor does not generate a new public/private keypair immediately.
-This constructor sets the <xref:System.Security.Cryptography.ECDsaOpenSsl.KeySize> property to 521 and when a key is needed the saved size is used to identify the target curve.
-If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.ImportParameters%2A> method, or other key import method, the key size from this constructor has no meaning.
- 
-  
+This constructor sets the <xref:System.Security.Cryptography.ECDsaOpenSsl.KeySize> property to 521 and when a key is needed, the saved size is used to identify the target curve.
+If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.ImportParameters%2A> method or another key import method, the key size from this constructor has no meaning.
+
  ]]></format>
         </remarks>
         <altmember cref="M:System.Security.Cryptography.ECDsa.Create" />
@@ -162,15 +160,14 @@ If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.Impor
         <param name="keySize">The size of the key. Valid key sizes are 256, 384, and 521 bits.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.ECDsaOpenSsl" /> class with a specified target key size.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 This constructor does not generate a new public/private keypair immediately.
-This constructor sets the <xref:System.Security.Cryptography.ECDsaOpenSsl.KeySize> property to the provided value and when a key is needed the saved size is used to identify the target curve.
-If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.ImportParameters%2A> method, or other key import method, the key size from this constructor has no meaning.
- 
-  
+This constructor sets the <xref:System.Security.Cryptography.ECDsaOpenSsl.KeySize> property to the provided value and when a key is needed, the saved size is used to identify the target curve.
+If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.ImportParameters%2A> method or another key import method, the key size from this constructor has no meaning.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">
@@ -227,12 +224,11 @@ If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.Impor
         <param name="handle">The OpenSSL <c>EC_KEY*</c> value to use as the key.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.ECDsaOpenSsl" /> class from an existing OpenSSL key represented as an <c>EC_KEY*</c>.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 > [!IMPORTANT]
-> OpenSSL supports multiple library versions being loaded within the same process.
-> Before calling this constructor verify your pointer value came from the same version of OpenSSL that this class uses, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion> for more information.
+> OpenSSL supports multiple library versions being loaded within the same process. Before calling this constructor, verify that your pointer value came from the same version of OpenSSL that this class uses. For more information, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
 
  ]]></format>
         </remarks>
@@ -348,13 +344,14 @@ If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.Impor
         <param name="pkeyHandle">The OpenSSL <c>EVP_PKEY*</c> value to use as the key, represented as a <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" />.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.ECDsaOpenSsl" /> class from an existing OpenSSL key represented as an <c>EVP_PKEY*</c>.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+In .NET 9 and later versions, external modifications of `pkeyHandle` also affect the handle stored in the instance that this constructor creates.
+
 > [!IMPORTANT]
-> OpenSSL supports multiple library versions being loaded within the same process.
-> Before calling this constructor, verify your pointer value came from the same version of OpenSSL that this class uses.
-> For more information, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
+> OpenSSL supports multiple library versions being loaded within the same process. Before calling this constructor, verify that your pointer value came from the same version of OpenSSL that this class uses. For more information, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
 
  ]]></format>
         </remarks>
@@ -425,11 +422,10 @@ If a key is loaded via the <xref:System.Security.Cryptography.ECDsaOpenSsl.Impor
         <summary>Gets a <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" /> representation of the cryptographic key.</summary>
         <returns>A <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" /> representation of the cryptographic key.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
+          <format type="text/markdown"><![CDATA[
+
 ## Remarks
-Each call to this method produces a new <xref:System.Security.Cryptography.SafeEvpPKeyHandle> object with its own lifetime.
-The objects returned by this method can safely be used even after this <xref:System.Security.Cryptography.ECDsaOpenSsl> instance has been disposed.
+Each call to this method produces a new <xref:System.Security.Cryptography.SafeEvpPKeyHandle> object with its own lifetime. The objects returned by this method can safely be used even after this <xref:System.Security.Cryptography.ECDsaOpenSsl> instance has been disposed. However, modifying operations (that is, direct calls to modifying OpenSSL APIs) on the new handle operate on the same underlying object. The new instance this method returns is simply an additional reference.
 
 ]]></format>
         </remarks>
@@ -623,11 +619,11 @@ The objects returned by this method can safely be used even after this <xref:Sys
         <param name="parameters">The curve parameters.</param>
         <summary>Replaces the current key for this instance with one using the specified key parameters.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- If `parameters` contains only <xref:System.Security.Cryptography.ECParameters.Q>, only a public key is imported. If `parameters` also contains <xref:System.Security.Cryptography.ECParameters.D>, a full key pair is imported. The <xref:System.Security.Cryptography.ECParameters.Curve> field specifies the type of the curve to import.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ If `parameters` contains only <xref:System.Security.Cryptography.ECParameters.Q>, only a public key is imported. If `parameters` also contains <xref:System.Security.Cryptography.ECParameters.D>, a full key pair is imported. The <xref:System.Security.Cryptography.ECParameters.Curve> field specifies the type of the curve to import.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">
@@ -658,9 +654,9 @@ The objects returned by this method can safely be used even after this <xref:Sys
         <summary>Gets or sets the size, in bits, of the key modulus used by the asymmetric algorithm.</summary>
         <value>The size, in bits, of the key modulus used by the asymmetric algorithm.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 Setting this property to its current value has no visible effect.
 Setting this property to a new legal value discards the current key, but defers creation of a new key until one is needed.
@@ -698,9 +694,9 @@ Because key sizes do not uniquely identify elliptic curves, the use of the prope
         <summary>Gets the key sizes, in bits, that are supported by the <see cref="P:System.Security.Cryptography.ECDsaCng.KeySize" /> property setter.</summary>
         <value>An array that contains the key sizes supported by the <see cref="P:System.Security.Cryptography.ECDsaCng.KeySize" /> property setter.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 In Elliptic Curve Cryptography (ECC) the key size is not the only input into the key generation process,
 it is derived from the curve parameters for a specific elliptic curve.

xml/System.Security.Cryptography/RSAOpenSsl.xml

@@ -44,12 +44,12 @@
   <Docs>
     <summary>Provides an implementation of the RSA algorithm backed by OpenSSL.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+      <format type="text/markdown"><![CDATA[
+
+## Remarks
 > [!NOTE]
-> The <xref:System.Security.Cryptography.RSAOpenSsl> class is an implementation of the RSA algorithm using OpenSSL. It isn't available on Windows and is only available on other operating systems when OpenSSL is installed. For applications which aren't doing OpenSSL-specific interop, you're encouraged to use <xref:System.Security.Cryptography.RSA.Create%2A?displayProperty=nameWithType> instead of referencing this type directly.
-  
+> The <xref:System.Security.Cryptography.RSAOpenSsl> class is an implementation of the RSA algorithm using OpenSSL. It isn't available on Windows and is only available on other operating systems when OpenSSL is installed. For applications that aren't doing OpenSSL-specific interop, it's recommended to use <xref:System.Security.Cryptography.RSA.Create%2A?displayProperty=nameWithType> instead of referencing this type directly.
+
  ]]></format>
     </remarks>
   </Docs>
@@ -99,14 +99,14 @@
       <Docs>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.RSAOpenSsl" /> class with a random 2048-bit key pair.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 This constructor does not generate a new public/private keypair immediately.
-This constructor sets the <xref:System.Security.Cryptography.RSAOpenSsl.KeySize> property to 2048 and when a key is needed one is generated using the property value.
-If a key is loaded via the <xref:System.Security.Cryptography.RSAOpenSsl.ImportParameters%2A> method, or other key import method, the key size from this constructor has no meaning.
-  
+This constructor sets the <xref:System.Security.Cryptography.RSAOpenSsl.KeySize> property to 2048 and when a key is needed, one is generated using the property value.
+If a key is loaded via the <xref:System.Security.Cryptography.RSAOpenSsl.ImportParameters%2A> method or another key import method, the key size from this constructor has no meaning.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -161,13 +161,13 @@ If a key is loaded via the <xref:System.Security.Cryptography.RSAOpenSsl.ImportP
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.RSAOpenSsl" /> class with a randomly generated key of the specified size.</summary>
         <remarks>To be added.</remarks>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 This constructor does not generate a new public/private keypair immediately.
-This constructor sets the <xref:System.Security.Cryptography.RSAOpenSsl.KeySize> property to `keySize` and when a key is needed one is generated using the property value.
-If a key is loaded via the <xref:System.Security.Cryptography.RSAOpenSsl.ImportParameters%2A> method, or other key import method, the key size from this constructor has no meaning.
-  
+This constructor sets the <xref:System.Security.Cryptography.RSAOpenSsl.KeySize> property to `keySize` and when a key is needed, one is generated using the property value.
+If a key is loaded via the <xref:System.Security.Cryptography.RSAOpenSsl.ImportParameters%2A> method or another key import method, the key size from this constructor has no meaning.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">
@@ -223,14 +223,13 @@ If a key is loaded via the <xref:System.Security.Cryptography.RSAOpenSsl.ImportP
         <param name="handle">The OpenSSL <c>RSA*</c> value to use as the key.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.RSAOpenSsl" /> class from an existing OpenSSL key represented as an <c>RSA*</c>.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 > [!IMPORTANT]
 > OpenSSL supports multiple library versions being loaded within the same process.
-> Before calling this constructor, verify your pointer value came from the same version of OpenSSL that this class uses. 
-> For more information, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
+> Before calling this constructor, verify that your pointer value came from the same version of OpenSSL that this class uses. For more information, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
 
  ]]></format>
         </remarks>
@@ -289,9 +288,9 @@ If a key is loaded via the <xref:System.Security.Cryptography.RSAOpenSsl.ImportP
         <param name="parameters">The parameters for the key.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.RSAOpenSsl" /> class using specified key parameters.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 This constructor is equivalent to using the default constructor and calling <xref:System.Security.Cryptography.RSAOpenSsl.ImportParameters%2A>.
 
  ]]></format>
@@ -349,14 +348,15 @@ This constructor is equivalent to using the default constructor and calling <xre
         <param name="pkeyHandle">The OpenSSL <c>EVP_PKEY*</c> value to use as the key, represented as a <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" />.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.RSAOpenSsl" /> class from an existing OpenSSL key represented as an <c>EVP_PKEY*</c>.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+In .NET 9 and later versions, external modifications of `pkeyHandle` also affect the handle stored in the instance that this constructor creates.
 
 > [!IMPORTANT]
 > OpenSSL supports multiple library versions being loaded within the same process.
-> Before calling this constructor, verify your pointer value came from the same version of OpenSSL that this class uses.
-> For more information, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
+> Before calling this constructor, verify that your pointer value came from the same version of OpenSSL that this class uses. For more information, see <xref:System.Security.Cryptography.SafeEvpPKeyHandle.OpenSslVersion>.
 
  ]]></format>
         </remarks>
@@ -409,7 +409,7 @@ The length of <paramref name="data" /> is not equal to the number of bytes for <
 
 -or-
 
-This instance represents only a public key. 
+This instance represents only a public key.
 
 -or-
 
@@ -475,12 +475,11 @@ The decryption operation failed.</exception>
         <summary>Gets a <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" /> representation of the cryptographic key.</summary>
         <returns>A <see cref="T:System.Security.Cryptography.SafeEvpPKeyHandle" /> representation of the cryptographic key.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
-Each call to this method produces a new <xref:System.Security.Cryptography.SafeEvpPKeyHandle> object with its own lifetime.
-The objects returned by this method can safely be used even after this <xref:System.Security.Cryptography.RSAOpenSsl> instance has been disposed.
+Each call to this method produces a new <xref:System.Security.Cryptography.SafeEvpPKeyHandle> object with its own lifetime. The objects returned by this method can safely be used even after this <xref:System.Security.Cryptography.RSAOpenSsl> instance has been disposed. However, modifying operations (that is, direct calls to modifying OpenSSL APIs) on the new handle operate on the same underlying object. The new instance this method returns is simply an additional reference.
 
 ]]></format>
         </remarks>
@@ -692,9 +691,9 @@ The encryption operation failed.</exception>
         <summary>Gets or sets the size, in bits, of the key modulus used by the asymmetric algorithm.</summary>
         <value>The size, in bits, of the key modulus used by the asymmetric algorithm.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
 
 Setting this property to its current value has no visible effect.
 Setting this property to a new legal value discards the current key, but defers creation of a new key until one is needed.