Add notes to not-recommended algorithm classes (#4538)

tdykstra · web-flow · commit 0624f6af21d5 · 2020-07-23T06:50:36.000-07:00
diff --git a/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml b/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml
@@ -49,8 +49,9 @@
 ## Remarks  
  This algorithm supports a key length of 64 bits.  
   
-   
-  
+> [!IMPORTANT]
+> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the <xref:System.Security.Cryptography.Aes> class instead of the <xref:System.Security.Cryptography.DES> class. Use <xref:System.Security.Cryptography.DES> only for compatibility with legacy applications and data.
+
 ## Examples  
  The following code example uses <xref:System.Security.Cryptography.DESCryptoServiceProvider> (an implementation of <xref:System.Security.Cryptography.DES>) with the specified key (<xref:System.Security.Cryptography.SymmetricAlgorithm.Key%2A>) and initialization vector (<xref:System.Security.Cryptography.SymmetricAlgorithm.IV%2A>) to encrypt a file specified by `inName`. It then outputs the encrypted result to the file specified by `outName`.  
   
diff --git a/xml/System.Security.Cryptography/DSA.xml b/xml/System.Security.Cryptography/DSA.xml
@@ -48,7 +48,7 @@
  To use a public-key system to digitally sign a message, the sender first applies a hash function to the message to create a message digest. The sender then encrypts the message digest with the sender's private key to create the sender's personal signature. Upon receiving the message and signature, the receiver decrypts the signature using the sender's public key to recover the message digest and hashes the message using the same hash algorithm that the sender used. If the message digest that the receiver computes exactly matches the message digest received from the sender, the receiver can assume that the message was not altered while in transit. Note that a signature can be verified by anyone, because the sender's public key is common knowledge.  
   
 > [!IMPORTANT]
-> Newer asymmetric algorithms are available. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
   
  Two different versions of the DSA algorithm exist.
  The original form, described in FIPS 186-2, requires the use of SHA-1 as the hash algorithm and supports key lengths from 512 bits to 1024 bits in increments of 64 bits.
diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml
@@ -90,8 +90,11 @@
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
- Valid key sizes range from 512 to 3,072 bits, in increments of 64. We recommend that a minimum size of 2,048 bits be used for all keys.  
+Valid key sizes range from 512 to 3,072 bits, in increments of 64. We recommend that a minimum size of 2,048 bits be used for all keys.  
   
+> [!IMPORTANT]
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
+
  ]]></format>
         </remarks>
         <exception cref="T:System.Security.Cryptography.CryptographicException">
diff --git a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml
@@ -57,7 +57,7 @@
  To use a public-key system to digitally sign a message, the sender first applies a hash function to the message to create a message digest. The sender then encrypts the message digest with the sender's private key to create the sender's personal signature. Upon receiving the message and signature, the receiver decrypts the signature using the sender's public key to recover the message digest and hashes the message using the same hash algorithm that the sender used. If the message digest that the receiver computes exactly matches the message digest received from the sender, the receiver can be sure that the message was not altered while in transit. Note that a signature can be verified by anyone, because the sender's public key is common knowledge.  
   
 > [!NOTE]
->  Newer asymmetric algorithms are available. Consider using the <xref:System.Security.Cryptography.RSACryptoServiceProvider> class instead of the <xref:System.Security.Cryptography.DSACryptoServiceProvider> class. Use <xref:System.Security.Cryptography.DSACryptoServiceProvider> only for compatibility with legacy applications and data.  
+>  The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSACryptoServiceProvider> class instead of the <xref:System.Security.Cryptography.DSACryptoServiceProvider> class. Use <xref:System.Security.Cryptography.DSACryptoServiceProvider> only for compatibility with legacy applications and data.  
   
  This algorithm supports key lengths from 512 bits to 1024 bits in increments of 64 bits.  
   
diff --git a/xml/System.Security.Cryptography/DSAOpenSsl.xml b/xml/System.Security.Cryptography/DSAOpenSsl.xml
@@ -27,7 +27,7 @@
 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.DSA.Create%2A?displayProperty=nameWithType> factory methods instead of a specific derived implementation.
 
 > [!IMPORTANT]
-> Newer asymmetric algorithms are available. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
 
 DSAOpenSSL provides the FIPS 186-3 version of DSA.
 
diff --git a/xml/System.Security.Cryptography/DSAParameters.xml b/xml/System.Security.Cryptography/DSAParameters.xml
@@ -44,7 +44,16 @@
   </Attributes>
   <Docs>
     <summary>Contains the typical parameters for the <see cref="T:System.Security.Cryptography.DSA" /> algorithm.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+  
+> [!IMPORTANT]
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
+  
+ ]]></format>
+    </remarks>
     <related type="Article" href="/dotnet/standard/security/cryptographic-services">Cryptographic Services</related>
   </Docs>
   <Members>
diff --git a/xml/System.Security.Cryptography/DSASignatureDeformatter.xml b/xml/System.Security.Cryptography/DSASignatureDeformatter.xml
@@ -42,6 +42,11 @@
     <remarks>
       <format type="text/markdown"><![CDATA[  
   
+## Remarks  
+  
+> [!IMPORTANT]
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
+  
 ## Examples  
  [!code-cpp[System.Security.Cryptography.DSASignatureDeformatter#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.DSASignatureDeformatter/CPP/sample.cpp#1)]
  [!code-csharp[System.Security.Cryptography.DSASignatureDeformatter#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Cryptography.DSASignatureDeformatter/CS/sample.cs#1)]
diff --git a/xml/System.Security.Cryptography/DSASignatureFormat.xml b/xml/System.Security.Cryptography/DSASignatureFormat.xml
@@ -14,7 +14,16 @@
   </Base>
   <Docs>
     <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+  
+> [!IMPORTANT]
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
+  
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="IeeeP1363FixedFieldConcatenation">
diff --git a/xml/System.Security.Cryptography/DSASignatureFormatter.xml b/xml/System.Security.Cryptography/DSASignatureFormatter.xml
@@ -41,6 +41,11 @@
     <summary>Creates a Digital Signature Algorithm (<see cref="T:System.Security.Cryptography.DSA" />) signature.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[  
+
+## Remarks  
+  
+> [!IMPORTANT]
+> The creators of the DSA algorithm have withdrawn their support for it. Consider using the <xref:System.Security.Cryptography.RSA> class or the <xref:System.Security.Cryptography.ECDsa> class instead of the <xref:System.Security.Cryptography.DSA> class. Use <xref:System.Security.Cryptography.DSA> only for compatibility with legacy applications and data.  
   
 ## Examples  
  [!code-cpp[System.Security.Cryptography.DSASignatureFormatter#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.DSASignatureFormatter/CPP/sample.cpp#1)]
diff --git a/xml/System.Security.Cryptography/Rijndael.xml b/xml/System.Security.Cryptography/Rijndael.xml
@@ -47,11 +47,10 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
- This algorithm supports key lengths of 128, 192, or 256 bits; defaulting to 256 bits. This algorithm supports block sizes of 128, 192, or 256 bits; defaulting to 128 bits (<xref:System.Security.Cryptography.Aes>-compatible).  
-  
- The <xref:System.Security.Cryptography.Rijndael> class is the predecessor of the <xref:System.Security.Cryptography.Aes> algorithm. You should use the <xref:System.Security.Cryptography.Aes> algorithm instead of <xref:System.Security.Cryptography.Rijndael>. For more information, see the entry [The Differences Between Rijndael and AES](https://docs.microsoft.com/archive/blogs/shawnfa/the-differences-between-rijndael-and-aes) in the .NET Security blog.  
-  
-   
+ This algorithm supports key lengths of 128, 192, or 256 bits; defaulting to 256 bits. This algorithm supports block sizes of 128, 192, or 256 bits; defaulting to 128 bits (<xref:System.Security.Cryptography.Aes>-compatible).
+
+> [!IMPORTANT]
+> The <xref:System.Security.Cryptography.Rijndael> class is the predecessor of the <xref:System.Security.Cryptography.Aes> algorithm. You should use the <xref:System.Security.Cryptography.Aes> algorithm instead of <xref:System.Security.Cryptography.Rijndael>. For more information, see the entry [The Differences Between Rijndael and AES](https://docs.microsoft.com/archive/blogs/shawnfa/the-differences-between-rijndael-and-aes) in the .NET Security blog.  
   
 ## Examples  
  The following code example uses the <xref:System.Security.Cryptography.Rijndael> class to encrypt and then decrypt data.  
diff --git a/xml/System.Security.Cryptography/RijndaelManaged.xml b/xml/System.Security.Cryptography/RijndaelManaged.xml
@@ -49,9 +49,8 @@
 ## Remarks 
  This algorithm supports key lengths of 128, 192, or 256 bits; defaulting to 256 bits. In .NET Framework, this algorithm supports block sizes of 128, 192, or 256 bits; defaulting to 128 bits (<xref:System.Security.Cryptography.Aes>-compatible). In .NET Core, it is the same as AES and supports only a 128-bit block size. 
   
- The <xref:System.Security.Cryptography.Rijndael> algorithm is the predecessor of <xref:System.Security.Cryptography.Aes>. You should use the <xref:System.Security.Cryptography.Aes> class instead of <xref:System.Security.Cryptography.RijndaelManaged>. For more information, see the entry [The Differences Between Rijndael and AES](https://go.microsoft.com/fwlink/?LinkId=200932) in the .NET Security blog.  
-  
-   
+> [!IMPORTANT]
+> The <xref:System.Security.Cryptography.Rijndael> class is the predecessor of the <xref:System.Security.Cryptography.Aes> algorithm. You should use the <xref:System.Security.Cryptography.Aes> algorithm instead of <xref:System.Security.Cryptography.Rijndael>. For more information, see the entry [The Differences Between Rijndael and AES](https://docs.microsoft.com/archive/blogs/shawnfa/the-differences-between-rijndael-and-aes) in the .NET Security blog.  
   
 ## Examples  
  The following example demonstrates how to encrypt and decrypt sample data using the `RijndaelManaged` class.  
diff --git a/xml/System.Security.Cryptography/RijndaelManagedTransform.xml b/xml/System.Security.Cryptography/RijndaelManagedTransform.xml
@@ -34,9 +34,11 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
-  
-> [!NOTE]
->  Using this class is not recommended. A better practice is to use <xref:System.Security.Cryptography.RijndaelManaged> with a <xref:System.Security.Cryptography.CryptoStream> object. The <xref:System.Security.Cryptography.CryptoStream> object handles the padding issues that can occur when using <xref:System.Security.Cryptography.RijndaelManagedTransform> directly. For an example, see the <xref:System.Security.Cryptography.RijndaelManaged> class.  
+
+> [!IMPORTANT]
+> The <xref:System.Security.Cryptography.Rijndael> class is the predecessor of the <xref:System.Security.Cryptography.Aes> algorithm. You should use the <xref:System.Security.Cryptography.Aes> algorithm instead of <xref:System.Security.Cryptography.Rijndael>. For more information, see the entry [The Differences Between Rijndael and AES](https://docs.microsoft.com/archive/blogs/shawnfa/the-differences-between-rijndael-and-aes) in the .NET Security blog.  
+>
+> Using this class is not recommended. If you use the `Rijndael` algorithm, a better practice is to use <xref:System.Security.Cryptography.RijndaelManaged> with a <xref:System.Security.Cryptography.CryptoStream> object. The <xref:System.Security.Cryptography.CryptoStream> object handles the padding issues that can occur when using <xref:System.Security.Cryptography.RijndaelManagedTransform> directly. For an example, see the <xref:System.Security.Cryptography.RijndaelManaged> class.  
   
  Both the <xref:System.Security.Cryptography.RijndaelManaged.CreateEncryptor%2A> and <xref:System.Security.Cryptography.RijndaelManaged.CreateDecryptor%2A> methods return an instance of the <xref:System.Security.Cryptography.RijndaelManagedTransform> class that is initialized with the key information of the current <xref:System.Security.Cryptography.RijndaelManaged> object.  To encrypt or decrypt data using the Rijndael algorithm, pass the <xref:System.Security.Cryptography.RijndaelManagedTransform> object returned by these methods to a <xref:System.Security.Cryptography.CryptoStream> object.  
   
diff --git a/xml/System.Security.Cryptography/TripleDESCng.xml b/xml/System.Security.Cryptography/TripleDESCng.xml
@@ -29,7 +29,16 @@
   <Interfaces />
   <Docs>
     <summary>Provides a Cryptography Next Generation (CNG) implementation of the Triple Data Encryption Standard (3DES) algorithm.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+  
+## Remarks  
+  
+> [!IMPORTANT]
+> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the <xref:System.Security.Cryptography.Aes> class and its derived classes instead of the <xref:System.Security.Cryptography.TripleDES> class. Use <xref:System.Security.Cryptography.TripleDES> only for compatibility with legacy applications and data.  
+  
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <MemberGroup MemberName=".ctor">
