docs: add XML documentation for AES, AEAD modes and Dilithium

This commit adds XML documentation to the core symmetric suite and the Dilithium signer. Critical security warnings regarding Nonce reuse were added to GCM and ChaCha20Poly1305.

Author: KonradSop

crypto/src/crypto/IBlockCipher.cs

@@ -2,7 +2,9 @@
 
 namespace Org.BouncyCastle.Crypto
 {
-	/// <remarks>Base interface for a symmetric key block cipher.</remarks>
+    /// <summary>
+    /// Base interface for a symmetric key block cipher.
+    /// </summary>
     public interface IBlockCipher
     {
 		/// <summary>The name of the algorithm this cipher implements.</summary>
@@ -13,6 +15,9 @@ public interface IBlockCipher
 		/// <param name="parameters">The key or other data required by the cipher.</param>
 		void Init(bool forEncryption, ICipherParameters parameters);
 
+		/// <summary>
+		/// Return the block size for this cipher (in bytes).
+		/// </summary>
 		/// <returns>The block size for this cipher, in bytes.</returns>
 		int GetBlockSize();
 

crypto/src/crypto/engines/AesEngine.cs

@@ -6,30 +6,25 @@
 
 namespace Org.BouncyCastle.Crypto.Engines
 {
-    /**
-    * an implementation of the AES (Rijndael), from FIPS-197.
-    * <p>
-    * For further details see: <a href="http://csrc.nist.gov/encryption/aes/">http://csrc.nist.gov/encryption/aes/</a>.
-    *
-    * This implementation is based on optimizations from Dr. Brian Gladman's paper and C code at
-    * <a href="http://fp.gladman.plus.com/cryptography_technology/rijndael/">http://fp.gladman.plus.com/cryptography_technology/rijndael/</a>
-    *
-    * There are three levels of tradeoff of speed vs memory
-    * Because java has no preprocessor, they are written as three separate classes from which to choose
-    *
-    * The fastest uses 8Kbytes of static tables to precompute round calculations, 4 256 word tables for encryption
-    * and 4 for decryption.
-    *
-    * The middle performance version uses only one 256 word table for each, for a total of 2Kbytes,
-    * adding 12 rotate operations per round to compute the values contained in the other tables from
-    * the contents of the first.
-    *
-    * The slowest version uses no static tables at all and computes the values in each round.
-    * </p>
-    * <p>
-    * This file contains the middle performance version with 2Kbytes of static tables for round precomputation.
-    * </p>
-    */
+    /// <summary>An implementation of the AES (Rijndael), from FIPS-197.</summary>
+    /// <remarks>
+    /// For further details see: <a href="http://csrc.nist.gov/encryption/aes/">http://csrc.nist.gov/encryption/aes/</a>.
+    /// <para>
+    /// This implementation is based on optimizations from Dr. Brian Gladman's paper and C code at
+    /// <a href="http://fp.gladman.plus.com/cryptography_technology/rijndael/">http://fp.gladman.plus.com/cryptography_technology/rijndael/</a>
+    /// </para>
+    /// <para>
+    /// There are three levels of tradeoff of speed vs memory:
+    /// </para>
+    /// <list type="bullet">
+    /// <item>The fastest uses 8Kbytes of static tables to precompute round calculations.</item>
+    /// <item>The middle performance version uses only one 256 word table for each, for a total of 2Kbytes, adding 12 rotate operations per round.</item>
+    /// <item>The slowest version uses no static tables at all and computes the values in each round.</item>
+    /// </list>
+    /// <para>
+    /// This file contains the middle performance version with 2Kbytes of static tables for round precomputation.
+    /// </para>
+    /// </remarks>
     public sealed class AesEngine
         : IBlockCipher
     {
@@ -437,21 +432,15 @@ private uint[][] GenerateWorkingKey(KeyParameter keyParameter, bool forEncryptio
 
         private const int BLOCK_SIZE = 16;
 
-        /**
-        * default constructor - 128 bit block size.
-        */
+        /// <summary>Default constructor - 128 bit block size.</summary>
         public AesEngine()
         {
         }
 
-        /**
-        * initialise an AES cipher.
-        *
-        * @param forEncryption whether or not we are for encryption.
-        * @param parameters the parameters required to set up the cipher.
-        * @exception ArgumentException if the parameters argument is
-        * inappropriate.
-        */
+        /// <summary>Initialise an AES cipher.</summary>
+        /// <param name="forEncryption">Whether or not we are using it for encryption.</param>
+        /// <param name="parameters">The parameters required to set up the cipher.</param>
+        /// <exception cref="ArgumentException">If the parameters argument is inappropriate.</exception>
         public void Init(bool forEncryption, ICipherParameters parameters)
         {
             if (!(parameters is KeyParameter keyParameter))
@@ -464,16 +453,27 @@ public void Init(bool forEncryption, ICipherParameters parameters)
             this.s = Arrays.Clone(forEncryption ? S : Si);
         }
 
+        /// <summary>The name of the algorithm this engine implements.</summary>
         public string AlgorithmName
         {
             get { return "AES"; }
         }
 
+        /// <summary>Return the block size for this cipher (in bytes).</summary>
+        /// <returns>16 (fixed block size for AES).</returns>
         public int GetBlockSize()
         {
             return BLOCK_SIZE;
         }
 
+        /// <summary>Process a single block of data.</summary>
+        /// <param name="input">The input buffer containing the data to be processed.</param>
+        /// <param name="inOff">The offset into the input buffer.</param>
+        /// <param name="output">The output buffer to store the result.</param>
+        /// <param name="outOff">The offset into the output buffer.</param>
+        /// <returns>The number of bytes processed and produced.</returns>
+        /// <exception cref="DataLengthException">If the input buffer is too small, or the output buffer is too small.</exception>
+        /// <exception cref="InvalidOperationException">If the cipher isn't initialised.</exception>
         public int ProcessBlock(byte[] input, int inOff, byte[] output, int outOff)
         {
             if (WorkingKey == null)

crypto/src/crypto/modes/CbcBlockCipher.cs

@@ -5,9 +5,7 @@
 
 namespace Org.BouncyCastle.Crypto.Modes
 {
-    /**
-    * implements Cipher-Block-Chaining (CBC) mode on top of a simple cipher.
-    */
+    /// <summary>Implements Cipher-Block-Chaining (CBC) mode on top of a simple cipher.</summary>
     public sealed class CbcBlockCipher
 		: IBlockCipherMode
     {
@@ -16,11 +14,8 @@ public sealed class CbcBlockCipher
         private IBlockCipher	cipher;
         private bool			encrypting;
 
-        /**
-        * Basic constructor.
-        *
-        * @param cipher the block cipher to be used as the basis of chaining.
-        */
+        /// <summary>Basic constructor.</summary>
+        /// <param name="cipher">The block cipher to be used as the basis of chaining.</param>
         public CbcBlockCipher(
             IBlockCipher cipher)
         {
@@ -32,23 +27,15 @@ public CbcBlockCipher(
             this.cbcNextV = new byte[blockSize];
         }
 
-        /**
-        * return the underlying block cipher that we are wrapping.
-        *
-        * @return the underlying block cipher that we are wrapping.
-        */
+        /// <summary>Return the underlying block cipher that we are wrapping.</summary>
+        /// <returns>The underlying block cipher that we are wrapping.</returns>
         public IBlockCipher UnderlyingCipher => cipher;
 
-        /**
-        * Initialise the cipher and, possibly, the initialisation vector (IV).
-        * If an IV isn't passed as part of the parameter, the IV will be all zeros.
-        *
-        * @param forEncryption if true the cipher is initialised for
-        *  encryption, if false for decryption.
-        * @param param the key and other data required by the cipher.
-        * @exception ArgumentException if the parameters argument is
-        * inappropriate.
-        */
+        /// <summary>Initialise the cipher and, possibly, the initialisation vector (IV).</summary>
+        /// <remarks>If an IV isn't passed as part of the parameter, the IV will be all zeros.</remarks>
+        /// <param name="forEncryption">If true the cipher is initialised for encryption, if false for decryption.</param>
+        /// <param name="parameters">The key and other data required by the cipher.</param>
+        /// <exception cref="ArgumentException">If the parameters argument is inappropriate.</exception>
         public void Init(bool forEncryption, ICipherParameters parameters)
         {
             bool oldEncrypting = this.encrypting;
@@ -82,26 +69,21 @@ public void Init(bool forEncryption, ICipherParameters parameters)
             }
         }
 
-		/**
-        * return the algorithm name and mode.
-        *
-        * @return the name of the underlying algorithm followed by "/CBC".
-        */
+        /// <summary>Return the algorithm name and mode.</summary>
+        /// <returns>The name of the underlying algorithm followed by "/CBC".</returns>
         public string AlgorithmName
         {
             get { return cipher.AlgorithmName + "/CBC"; }
         }
 
+        /// <summary>Indicates whether this cipher can handle partial blocks.</summary>
 		public bool IsPartialBlockOkay
 		{
 			get { return false; }
 		}
 
-		/**
-        * return the block size of the underlying cipher.
-        *
-        * @return the block size of the underlying cipher.
-        */
+        /// <summary>Return the block size of the underlying cipher.</summary>
+        /// <returns>The block size in bytes.</returns>
         public int GetBlockSize()
         {
             return cipher.GetBlockSize();
@@ -129,10 +111,7 @@ public int ProcessBlock(ReadOnlySpan<byte> input, Span<byte> output)
         }
 #endif
 
-        /**
-        * reset the chaining vector back to the IV and reset the underlying
-        * cipher.
-        */
+        /// <summary>Reset the chaining vector back to the IV and reset the underlying cipher.</summary>
         public void Reset()
         {
             Array.Copy(IV, 0, cbcV, 0, IV.Length);