Use "When overridden" on AsymmetricAlgorithm virtual+throws (#2861)

Author: bartonjs

xml/System.Security.Cryptography/AsymmetricAlgorithm.xml

@@ -661,7 +661,7 @@
         <param name="passwordBytes">The bytes to use as a password when decrypting the key material.</param>
         <param name="source">The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding.</param>
         <param name="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramref name="source"/>. This parameter is treated as uninitialized.</param>
-        <summary>Imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a byte-based password, replacing the keys for this object.</summary>
+        <summary>When overridden in a derived class, imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a byte-based password, replacing the keys for this object.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -671,6 +671,9 @@
 
  This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
  If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
+
+ Because algorithm-specific support is required to interpret the contents of this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.ImportEncryptedPkcs8PrivateKey%2A> throws a <xref:System.NotImplementedException> by default.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
@@ -695,6 +698,7 @@ The contents of <paramref name="source"/> represent the key in a format that is
 
 The algorithm-specific key import failed.
 </exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
       </Docs>
     </Member>
     <Member MemberName="ImportEncryptedPkcs8PrivateKey">
@@ -727,7 +731,7 @@ The algorithm-specific key import failed.
         <param name="password">The password to use for decrypting the key material.</param>
         <param name="source">The bytes of a PKCS#8 EncryptedPrivateKeyInfo structure in the ASN.1-BER encoding.</param>
         <param name="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramref name="source"/>. This parameter is treated as uninitialized.</param>
-        <summary>Imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a char-based password, replacing the keys for this object.</summary>
+        <summary>When overridden in a derived class, imports the public/private keypair from a PKCS#8 EncryptedPrivateKeyInfo structure after decrypting with a char-based password, replacing the keys for this object.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
@@ -736,6 +740,9 @@ The algorithm-specific key import failed.
 
  This method only supports the binary (BER/CER/DER) encoding of EncryptedPrivateKeyInfo.
  If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
+
+ Because algorithm-specific support is required to interpret the contents of this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.ImportEncryptedPkcs8PrivateKey%2A> throws a <xref:System.NotImplementedException> by default.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The password is incorrect.
@@ -756,6 +763,7 @@ The contents of <paramref name="source"/> represent the key in a format that is
 
 The algorithm-specific key import failed.
 </exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
       </Docs>
     </Member>
     <Member MemberName="ImportPkcs8PrivateKey">
@@ -786,13 +794,16 @@ The algorithm-specific key import failed.
       <Docs>
         <param name="source">The bytes of a PKCS#8 PrivateKeyInfo structure in the ASN.1-BER encoding.</param>
         <param name="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramref name="source"/>. This parameter is treated as uninitialized.</param>
-        <summary>Imports the public/private keypair from a PKCS#8 PrivateKeyInfo structure after decryption, replacing the keys for this object.</summary>
+        <summary>When overriden in a derived class, imports the public/private keypair from a PKCS#8 PrivateKeyInfo structure after decryption, replacing the keys for this object.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
  This method only supports the binary (BER/CER/DER) encoding of PrivateKeyInfo.
  If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
+
+ Because algorithm-specific support is required to interpret the contents of this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.ImportPkcs8PrivateKey%2A> throws a <xref:System.NotImplementedException> by default.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The contents of <paramref name="source"/> do not represent an ASN.1-BER-encoded PKCS#8 PrivateKeyInfo structure.
@@ -809,6 +820,7 @@ The contents of <paramref name="source"/> represent the key in a format that is
 
 The algorithm-specific key import failed.
 </exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
       </Docs>
     </Member>
     <Member MemberName="ImportSubjectPublicKeyInfo">
@@ -839,13 +851,15 @@ The algorithm-specific key import failed.
       <Docs>
         <param name="source">The bytes of an X.509 SubjectPublicKeyInfo structure in the ASN.1-DER encoding.</param>
         <param name="bytesRead">When this method returns, contains a value that indicates the number of bytes read from <paramref name="source"/>. This parameter is treated as uninitialized.</param>
-        <summary>Imports the public key from an X.509 SubjectPublicKeyInfo structure after decryption, replacing the keys for this object.</summary>
+        <summary>When overriden in a derived class, imports the public key from an X.509 SubjectPublicKeyInfo structure after decryption, replacing the keys for this object.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
  This method only supports the binary (DER) encoding of SubjectPublicKeyInfo.
  If the value is Base64-encoded or in the PEM text format, the caller must Base64-decode the contents before calling this method.
+
+ Because algorithm-specific support is required to interpret the contents of this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.ImportSubjectPublicKeyInfo%2A> throws a <xref:System.NotImplementedException> by default.
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The contents of <paramref name="source"/> do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure.
@@ -862,6 +876,7 @@ The contents of <paramref name="source"/> represent the key in a format that is
 
 The algorithm-specific key import failed.
 </exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
       </Docs>
     </Member>
     <Member MemberName="KeyExchangeAlgorithm">
@@ -1270,7 +1285,7 @@ This member is an explicit interface member implementation. It can be used only
         <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
         <param name="destination">The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data.</param>
         <param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
-        <summary>Attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a byte-based password.</summary>
+        <summary>When overridden in a derived class, attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a byte-based password.</summary>
         <returns><see langword="true"/> if <paramref name="destination"/> is big enough to receive the output; otherwise, <see langword="false"/>.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
@@ -1279,6 +1294,8 @@ This member is an explicit interface member implementation. It can be used only
  The password bytes are passed directly into the Key Derivation Function (KDF) used by the algorithm indicated by `pbeParameters`.
  This enables compatibility with other systems which use a text encoding other than UTF-8 when processing passwords with PBKDF2 (Password-Based Key Derivation Function 2).
 
+ Because algorithm-specific support is required to produce this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.TryExportEncryptedPkcs8PrivateKey%2A> throws a <xref:System.NotImplementedException> by default.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.
@@ -1287,6 +1304,7 @@ This member is an explicit interface member implementation. It can be used only
 
 <paramref name="pbeParameters"/> indicates that <see cref="F:System.Security.Cryptography.PbeEncryptionAlgorithm.TripleDes3KeyPkcs12"/> should be used, which requires <see cref="T:System.Char"/>-based passwords.
 </exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
         <altmember cref="Overload:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey" />
       </Docs>
     </Member>
@@ -1321,17 +1339,20 @@ This member is an explicit interface member implementation. It can be used only
         <param name="pbeParameters">The password-based encryption (PBE) parameters to use when encrypting the key material.</param>
         <param name="destination">The byte span to receive the PKCS#8 EncryptedPrivateKeyInfo data.</param>
         <param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
-        <summary>Attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a char-based password.</summary>
+        <summary>When overriden in a derived class, attempts to export the current key in the PKCS#8 EncryptedPrivateKeyInfo format into a provided buffer, using a char-based password.</summary>
         <returns><see langword="true"/> if <paramref name="destination"/> is big enough to receive the output; otherwise, <see langword="false"/>.</returns>
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
  When `pbeParameters` indicates an algorithm that uses PBKDF2 (Password-Based Key Derivation Function 2), the password is converted to bytes via the UTF-8 encoding.
 
+ Because algorithm-specific support is required to produce this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.TryExportEncryptedPkcs8PrivateKey%2A> throws a <xref:System.NotImplementedException> by default.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
         <altmember cref="Overload:System.Security.Cryptography.AsymmetricAlgorithm.ExportEncryptedPkcs8PrivateKey" />
       </Docs>
     </Member>
@@ -1363,10 +1384,18 @@ This member is an explicit interface member implementation. It can be used only
       <Docs>
         <param name="destination">The byte span to receive the PKCS#8 PrivateKeyInfo data.</param>
         <param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
-        <summary>Attempts to export the current key in the PKCS#8 PrivateKeyInfo format into a provided buffer.</summary>
+        <summary>When overridden in a derived class, attempts to export the current key in the PKCS#8 PrivateKeyInfo format into a provided buffer.</summary>
         <returns><see langword="true"/> if <paramref name="destination"/> is big enough to receive the output; otherwise, <see langword="false"/>.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ Because algorithm-specific support is required to produce this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.TryExportPkcs8PrivateKey%2A> throws a <xref:System.NotImplementedException> by default.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
         <altmember cref="Overload:System.Security.Cryptography.AsymmetricAlgorithm.ExportPkcs8PrivateKey" />
       </Docs>
     </Member>
@@ -1398,10 +1427,18 @@ This member is an explicit interface member implementation. It can be used only
       <Docs>
         <param name="destination">The byte span to receive the X.509 SubjectPublicKeyInfo data.</param>
         <param name="bytesWritten">When this method returns, contains a value that indicates the number of bytes written to <paramref name="destination"/>. This parameter is treated as uninitialized.</param>
-        <summary>Attempts to export the current key in the X.509 SubjectPublicKeyInfo format into a provided buffer.</summary>
+        <summary>When overridden in a derived class, attempts to export the current key in the X.509 SubjectPublicKeyInfo format into a provided buffer.</summary>
         <returns><see langword="true"/> if <paramref name="destination"/> is big enough to receive the output; otherwise, <see langword="false"/>.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+ Because algorithm-specific support is required to produce this data format, <xref:System.Security.Cryptography.AsymmetricAlgorithm.TryExportSubjectPublicKeyInfo%2A> throws a <xref:System.NotImplementedException> by default.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">The key could not be exported.</exception>
+        <exception cref="T:System.NotImplementedException">A derived type has not overriden this member.</exception>
         <altmember cref="Overload:System.Security.Cryptography.AsymmetricAlgorithm.ExportSubjectPublicKeyInfo" />
       </Docs>
     </Member>