API updates for .NET 6 breaking changes (#7262)

Author: gewarren

xml/System.Security.Cryptography/AesCng.xml

@@ -108,11 +108,11 @@
         <param name="keyName">The name of the key.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.AesCng" /> class with the specified key name, which represents an existing persisted AES key.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This constructor uses a default <xref:System.Security.Cryptography.CngKeyOpenOptions> value of <xref:System.Security.Cryptography.CngKeyOpenOptions.None> and <xref:System.Security.Cryptography.CngProvider.MicrosoftSoftwareKeyStorageProvider%2A> as the default key storage provider (KSP) to open the key.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ This constructor uses a default <xref:System.Security.Cryptography.CngKeyOpenOptions> value of <xref:System.Security.Cryptography.CngKeyOpenOptions.None> and <xref:System.Security.Cryptography.CngProvider.MicrosoftSoftwareKeyStorageProvider%2A> as the default key storage provider (KSP) to open the key.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
@@ -158,18 +158,18 @@
         <param name="provider">The KSP that contains the key.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.AesCng" /> class with the specified key name, which represents an existing persisted AES key, and the specified key storage provider (KSP).</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- A default <xref:System.Security.Cryptography.CngKeyOpenOptions> value of <xref:System.Security.Cryptography.CngKeyOpenOptions.None> is used to open the key.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ A default <xref:System.Security.Cryptography.CngKeyOpenOptions> value of <xref:System.Security.Cryptography.CngKeyOpenOptions.None> is used to open the key.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
-          <paramref name="keyName" /> is <see langword="null" />.  
-  
- -or-  
-  
+          <paramref name="keyName" /> is <see langword="null" />.
+
+ -or-
+
  <paramref name="provider" /> is <see langword="null" />.</exception>
         <exception cref="T:System.PlatformNotSupportedException">Cryptography Next Generation (CNG) is not supported on this system.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">All other errors.</exception>
@@ -215,10 +215,10 @@
         <summary>Initializes a new instance of the <see cref="T:System.Security.Cryptography.AesCng" /> class with the specified key name, which represents an existing persisted AES key,  the specified key storage provider (KSP) and key open options.</summary>
         <remarks>To be added.</remarks>
         <exception cref="T:System.ArgumentNullException">
-          <paramref name="keyName" /> is <see langword="null" />.  
-  
- -or-  
-  
+          <paramref name="keyName" /> is <see langword="null" />.
+
+ -or-
+
  <paramref name="provider" /> is <see langword="null" />.</exception>
         <exception cref="T:System.PlatformNotSupportedException">Cryptography Next Generation (CNG) is not supported on this system.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">All other errors.</exception>
@@ -269,13 +269,15 @@
         <summary>Creates a symmetric AES decryptor object with the current key and initialization vector (<see cref="P:System.Security.Cryptography.SymmetricAlgorithm.IV" />).</summary>
         <returns>A symmetric AES decryptor object.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This method decrypts an encrypted message created using the <xref:System.Security.Cryptography.AesCng.CreateEncryptor> overload with the same signature.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This method decrypts an encrypted message created using the <xref:System.Security.Cryptography.AesCng.CreateEncryptor> overload with the same signature.
+
  ]]></format>
         </remarks>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">.NET 6 and later: CFB128 mode is selected and the key is persisted.</exception>
       </Docs>
     </Member>
     <Member MemberName="CreateDecryptor">
@@ -319,29 +321,29 @@
         <summary>Creates a symmetric AES decryptor object with the specified key and initialization vector (IV).</summary>
         <returns>A symmetric AES decryptor object.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This method decrypts an encrypted message created using the <xref:System.Security.Cryptography.AesCng.CreateEncryptor%28System.Byte%5B%5D%2CSystem.Byte%5B%5D%29> overload with the same signature.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ This method decrypts an encrypted message created using the <xref:System.Security.Cryptography.AesCng.CreateEncryptor%28System.Byte%5B%5D%2CSystem.Byte%5B%5D%29> overload with the same signature.
+
 > [!NOTE]
->  If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property and then call the  parameterless <xref:System.Security.Cryptography.AesCng.CreateDecryptor> overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter.  
-  
+>  If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property and then call the  parameterless <xref:System.Security.Cryptography.AesCng.CreateDecryptor> overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="rgbKey" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentException">
-          <paramref name="rgbKey" /> is not a valid size for this algorithm.  
-  
- -or-  
-  
+          <paramref name="rgbKey" /> is not a valid size for this algorithm.
+
+ -or-
+
  <paramref name="rgbIV" /> size does not match the block size for this algorithm.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">
-          <paramref name="rgbKey" /> is a known weak key for this algorithm and cannot be used.  
-  
- -or-  
-  
+          <paramref name="rgbKey" /> is a known weak key for this algorithm and cannot be used.
+
+ -or-
+
  <paramref name="rgbIV" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
@@ -389,13 +391,15 @@
         <summary>Creates a symmetric AES encryptor object using the current key and initialization vector (<see cref="P:System.Security.Cryptography.SymmetricAlgorithm.IV" />).</summary>
         <returns>A symmetric AES encryptor object.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- Use this method to encrypt a message and then use the <xref:System.Security.Cryptography.AesCng.CreateDecryptor%2A> overload with the same signature to decrypt the  result of this method.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+Use this method to encrypt a message and then use the <xref:System.Security.Cryptography.AesCng.CreateDecryptor%2A> overload with the same signature to decrypt the  result of this method.
+
  ]]></format>
         </remarks>
+        <exception cref="T:System.Security.Cryptography.CryptographicException">.NET 6 and later: CFB128 mode is selected and the key is persisted.</exception>
       </Docs>
     </Member>
     <Member MemberName="CreateEncryptor">
@@ -439,29 +443,29 @@
         <summary>Creates a symmetric AES encryptor object with the specified key and initialization vector (IV).</summary>
         <returns>A symmetric AES encryptor object.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- Use this method to encrypt a message and then use the <xref:System.Security.Cryptography.AesCng.CreateDecryptor%2A> overload with the same signature to decrypt the  result of this method.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ Use this method to encrypt a message and then use the <xref:System.Security.Cryptography.AesCng.CreateDecryptor%2A> overload with the same signature to decrypt the  result of this method.
+
 > [!NOTE]
->  If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property and then call the  parameterless <xref:System.Security.Cryptography.AesCng.CreateEncryptor> overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter.  
-  
+>  If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the <xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A> property and then call the  parameterless <xref:System.Security.Cryptography.AesCng.CreateEncryptor> overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="rgbKey" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentException">
-          <paramref name="rgbKey" /> is not a valid size for this algorithm.  
-  
- -or-  
-  
+          <paramref name="rgbKey" /> is not a valid size for this algorithm.
+
+ -or-
+
  <paramref name="rgbIV" /> size does not match the block size for this algorithm.</exception>
         <exception cref="T:System.Security.Cryptography.CryptographicException">
-          <paramref name="rgbKey" /> is a known weak key for this algorithm and cannot be used.  
-  
- -or-  
-  
+          <paramref name="rgbKey" /> is a known weak key for this algorithm and cannot be used.
+
+ -or-
+
  <paramref name="rgbIV" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
@@ -611,13 +615,13 @@
         <summary>Gets or sets the key for the <see cref="T:System.Security.Cryptography.AesCng" /> algorithm.</summary>
         <value>The key for the <see cref="T:System.Security.Cryptography.AesCng" /> algorithm.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key, when you read the value of the <xref:System.Security.Cryptography.AesCng.Key%2A> property, an attempt to export the key will be made. In this case, if the key is not exportable, a <xref:System.Security.Cryptography.CryptographicException> will be thrown.  
-  
- In addition to that, if you set the value of the <xref:System.Security.Cryptography.AesCng.Key%2A> property,  the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of <xref:System.Security.Cryptography.AesCng> class needs to be created.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key, when you read the value of the <xref:System.Security.Cryptography.AesCng.Key%2A> property, an attempt to export the key will be made. In this case, if the key is not exportable, a <xref:System.Security.Cryptography.CryptographicException> will be thrown.
+
+ In addition to that, if you set the value of the <xref:System.Security.Cryptography.AesCng.Key%2A> property,  the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of <xref:System.Security.Cryptography.AesCng> class needs to be created.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -656,13 +660,13 @@
         <summary>Gets or sets the size, in bits, of the secret key used by the <see cref="T:System.Security.Cryptography.AesCng" /> algorithm.</summary>
         <value>The size, in bits, of the secret key used by the <see cref="T:System.Security.Cryptography.AesCng" /> algorithm.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks 
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
  For AES, the legal key sizes are 128, 192, and 256 bits.
 
- If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key and you set the value of the <xref:System.Security.Cryptography.AesCng.KeySize%2A> property,  the persisted key will no longer be used and an ephemeral key will be used instead. If you need to use the persisted key again, a new instance of <xref:System.Security.Cryptography.AesCng> class needs to be created.  
-  
+ If you've created the <xref:System.Security.Cryptography.AesCng> object using an existing persisted key and you set the value of the <xref:System.Security.Cryptography.AesCng.KeySize%2A> property,  the persisted key will no longer be used and an ephemeral key will be used instead. If you need to use the persisted key again, a new instance of <xref:System.Security.Cryptography.AesCng> class needs to be created.
+
  ]]></format>
         </remarks>
       </Docs>