docs: add XML documentation for modern asymmetric key-pair generators (Batch 10)

crypto/src/crypto/generators/Ed25519KeyPairGenerator.cs

@@ -5,16 +5,22 @@
 
 namespace Org.BouncyCastle.Crypto.Generators
 {
+    /// <summary>
+    /// Key-pair generator for Ed25519 (RFC 8032). Only the <see cref="SecureRandom"/> from the supplied
+    /// <see cref="KeyGenerationParameters"/> is used; the 32-byte seed is drawn directly from it.
+    /// </summary>
     public class Ed25519KeyPairGenerator
         : IAsymmetricCipherKeyPairGenerator
     {
         private SecureRandom random;
 
+        /// <summary>Capture the <see cref="SecureRandom"/> that will source the seed.</summary>
         public virtual void Init(KeyGenerationParameters parameters)
         {
             this.random = parameters.Random;
         }
 
+        /// <summary>Generate a fresh Ed25519 key pair.</summary>
         public virtual AsymmetricCipherKeyPair GenerateKeyPair()
         {
             Ed25519PrivateKeyParameters privateKey = new Ed25519PrivateKeyParameters(random);

crypto/src/crypto/generators/Ed448KeyPairGenerator.cs

@@ -5,16 +5,22 @@
 
 namespace Org.BouncyCastle.Crypto.Generators
 {
+    /// <summary>
+    /// Key-pair generator for Ed448 (RFC 8032). Only the <see cref="SecureRandom"/> from the supplied
+    /// <see cref="KeyGenerationParameters"/> is used; the 57-byte seed is drawn directly from it.
+    /// </summary>
     public class Ed448KeyPairGenerator
         : IAsymmetricCipherKeyPairGenerator
     {
         private SecureRandom random;
 
+        /// <summary>Capture the <see cref="SecureRandom"/> that will source the seed.</summary>
         public virtual void Init(KeyGenerationParameters parameters)
         {
             this.random = parameters.Random;
         }
 
+        /// <summary>Generate a fresh Ed448 key pair.</summary>
         public virtual AsymmetricCipherKeyPair GenerateKeyPair()
         {
             Ed448PrivateKeyParameters privateKey = new Ed448PrivateKeyParameters(random);

crypto/src/crypto/generators/MLDsaKeyPairGenerator.cs

@@ -1,20 +1,37 @@
-using Org.BouncyCastle.Crypto.Parameters;
+using System;
+
+using Org.BouncyCastle.Crypto.Parameters;
 using Org.BouncyCastle.Security;
 
 namespace Org.BouncyCastle.Crypto.Generators
 {
+    /// <summary>
+    /// Key-pair generator for ML-DSA (FIPS 204). Driven by an <see cref="MLDsaKeyGenerationParameters"/>
+    /// init payload; produces an <see cref="AsymmetricCipherKeyPair"/> bound to the chosen parameter set.
+    /// </summary>
     public sealed class MLDsaKeyPairGenerator
         : IAsymmetricCipherKeyPairGenerator
     {
         private SecureRandom m_random;
         private MLDsaParameters m_parameters;
 
+        /// <summary>
+        /// Initialise with an <see cref="MLDsaKeyGenerationParameters"/> instance; the <see cref="SecureRandom"/>
+        /// and parameter set are taken from it.
+        /// </summary>
+        /// <exception cref="InvalidCastException">If <paramref name="parameters"/> is not an
+        /// <see cref="MLDsaKeyGenerationParameters"/>.</exception>
         public void Init(KeyGenerationParameters parameters)
         {
             m_random = parameters.Random;
             m_parameters = ((MLDsaKeyGenerationParameters)parameters).Parameters;
         }
 
+        /// <summary>
+        /// Generate a fresh ML-DSA key pair. The private key is returned with
+        /// <see cref="MLDsaPrivateKeyParameters.Format.SeedAndEncoding"/> so the resulting key carries both
+        /// the 32-byte seed and the expanded encoding.
+        /// </summary>
         public AsymmetricCipherKeyPair GenerateKeyPair()
         {
             var engine = m_parameters.ParameterSet.GetEngine(m_random);

crypto/src/crypto/generators/MLKemKeyPairGenerator.cs

@@ -1,20 +1,37 @@
+using System;
+
 using Org.BouncyCastle.Crypto.Parameters;
 using Org.BouncyCastle.Security;
 
 namespace Org.BouncyCastle.Crypto.Generators
 {
+    /// <summary>
+    /// Key-pair generator for ML-KEM (FIPS 203). Driven by an <see cref="MLKemKeyGenerationParameters"/>
+    /// init payload; produces an <see cref="AsymmetricCipherKeyPair"/> bound to the chosen parameter set.
+    /// </summary>
     public class MLKemKeyPairGenerator
         : IAsymmetricCipherKeyPairGenerator
     {
         private SecureRandom m_random;
         private MLKemParameters m_parameters;
 
+        /// <summary>
+        /// Initialise with an <see cref="MLKemKeyGenerationParameters"/> instance; the <see cref="SecureRandom"/>
+        /// and parameter set are taken from it.
+        /// </summary>
+        /// <exception cref="InvalidCastException">If <paramref name="parameters"/> is not an
+        /// <see cref="MLKemKeyGenerationParameters"/>.</exception>
         public void Init(KeyGenerationParameters parameters)
         {
             m_random = parameters.Random;
             m_parameters = ((MLKemKeyGenerationParameters)parameters).Parameters;
         }
 
+        /// <summary>
+        /// Generate a fresh ML-KEM key pair. The private key is returned with
+        /// <see cref="MLKemPrivateKeyParameters.Format.SeedAndEncoding"/> so the resulting key carries both
+        /// the 64-byte seed and the expanded encoding.
+        /// </summary>
         public AsymmetricCipherKeyPair GenerateKeyPair()
         {
             m_parameters.ParameterSet.Engine.GenerateKemKeyPair(m_random, out byte[] seed, out byte[] encoding);

crypto/src/crypto/generators/SlhDsaKeyPairGenerator.cs

@@ -1,21 +1,37 @@
-using Org.BouncyCastle.Crypto.Parameters;
+using System;
+
+using Org.BouncyCastle.Crypto.Parameters;
 using Org.BouncyCastle.Crypto.Signers.SlhDsa;
 using Org.BouncyCastle.Security;
 
 namespace Org.BouncyCastle.Crypto.Generators
 {
+    /// <summary>
+    /// Key-pair generator for SLH-DSA (FIPS 205). Driven by an <see cref="SlhDsaKeyGenerationParameters"/>
+    /// init payload; produces an <see cref="AsymmetricCipherKeyPair"/> bound to the chosen parameter set.
+    /// </summary>
     public sealed class SlhDsaKeyPairGenerator
         : IAsymmetricCipherKeyPairGenerator
     {
         private SecureRandom m_random;
         private SlhDsaParameters m_parameters;
 
+        /// <summary>
+        /// Initialise with an <see cref="SlhDsaKeyGenerationParameters"/> instance; the <see cref="SecureRandom"/>
+        /// and parameter set are taken from it.
+        /// </summary>
+        /// <exception cref="InvalidCastException">If <paramref name="parameters"/> is not an
+        /// <see cref="SlhDsaKeyGenerationParameters"/>.</exception>
         public void Init(KeyGenerationParameters parameters)
         {
             m_random = parameters.Random;
             m_parameters = ((SlhDsaKeyGenerationParameters)parameters).Parameters;
         }
 
+        /// <summary>
+        /// Generate a fresh SLH-DSA key pair by drawing the three <c>n</c>-byte seeds
+        /// (<c>SK.seed</c>, <c>SK.prf</c>, <c>PK.seed</c>) and computing the hypertree root.
+        /// </summary>
         public AsymmetricCipherKeyPair GenerateKeyPair()
         {
             var engine = m_parameters.ParameterSet.GetEngine();

crypto/src/crypto/generators/X25519KeyPairGenerator.cs

@@ -5,16 +5,22 @@
 
 namespace Org.BouncyCastle.Crypto.Generators
 {
+    /// <summary>
+    /// Key-pair generator for X25519 (RFC 7748). Only the <see cref="SecureRandom"/> from the supplied
+    /// <see cref="KeyGenerationParameters"/> is used; the 32-byte clamped scalar is drawn directly from it.
+    /// </summary>
     public class X25519KeyPairGenerator
         : IAsymmetricCipherKeyPairGenerator
     {
         private SecureRandom random;
 
+        /// <summary>Capture the <see cref="SecureRandom"/> that will source the scalar.</summary>
         public virtual void Init(KeyGenerationParameters parameters)
         {
             this.random = parameters.Random;
         }
 
+        /// <summary>Generate a fresh X25519 key pair.</summary>
         public virtual AsymmetricCipherKeyPair GenerateKeyPair()
         {
             X25519PrivateKeyParameters privateKey = new X25519PrivateKeyParameters(random);

crypto/src/crypto/generators/X448KeyPairGenerator.cs

@@ -5,16 +5,22 @@
 
 namespace Org.BouncyCastle.Crypto.Generators
 {
+    /// <summary>
+    /// Key-pair generator for X448 (RFC 7748). Only the <see cref="SecureRandom"/> from the supplied
+    /// <see cref="KeyGenerationParameters"/> is used; the 56-byte clamped scalar is drawn directly from it.
+    /// </summary>
     public class X448KeyPairGenerator
         : IAsymmetricCipherKeyPairGenerator
     {
         private SecureRandom random;
 
+        /// <summary>Capture the <see cref="SecureRandom"/> that will source the scalar.</summary>
         public virtual void Init(KeyGenerationParameters parameters)
         {
             this.random = parameters.Random;
         }
 
+        /// <summary>Generate a fresh X448 key pair.</summary>
         public virtual AsymmetricCipherKeyPair GenerateKeyPair()
         {
             X448PrivateKeyParameters privateKey = new X448PrivateKeyParameters(random);