docs: add XML documentation for HQC key parameters (Batch 13b-2)

crypto/src/pqc/crypto/hqc/HqcKeyGenerationParameters.cs

@@ -5,18 +5,24 @@
 
 namespace Org.BouncyCastle.Pqc.Crypto.Hqc
 {
+    /// <summary>Key generation parameters for HQC, binding a randomness source to an HQC parameter set.</summary>
     public class HqcKeyGenerationParameters
         : KeyGenerationParameters
     {
         private readonly HqcParameters m_parameters;
 
+        /// <summary>Creates key generation parameters for the given HQC parameter set.</summary>
+        /// <param name="random">The randomness source for key generation.</param>
+        /// <param name="param">The HQC parameter set to generate keys for.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="param"/> is null.</exception>
         // TODO[api] Rename to 'parameters'
         public HqcKeyGenerationParameters(SecureRandom random, HqcParameters param)
             : base(random, 256)
         {
             m_parameters = param ?? throw new ArgumentNullException(nameof(param));
         }
 
+        /// <summary>The HQC parameter set keys will be generated for.</summary>
         public HqcParameters Parameters => m_parameters;
     }
 }

crypto/src/pqc/crypto/hqc/HqcKeyParameters.cs

@@ -2,6 +2,7 @@
 
 namespace Org.BouncyCastle.Pqc.Crypto.Hqc
 {
+    /// <summary>Base class for HQC public and private keys, carrying the associated parameter set.</summary>
     public abstract class HqcKeyParameters
         : AsymmetricKeyParameter
     {
@@ -13,6 +14,7 @@ internal HqcKeyParameters(bool isPrivate, HqcParameters parameters)
             m_parameters = parameters;
         }
 
+        /// <summary>The HQC parameter set this key belongs to.</summary>
         public HqcParameters Parameters => m_parameters;
     }
 }

crypto/src/pqc/crypto/hqc/HqcParameters.cs

@@ -2,20 +2,21 @@
 
 namespace Org.BouncyCastle.Pqc.Crypto.Hqc
 {
+    /// <summary>HQC code-based KEM parameter sets (HQC-128, HQC-192, HQC-256).</summary>
     public sealed class HqcParameters
         : ICipherParameters
     {
         // TODO[api] Rename parameters instances and remove most properties
 
-        // 128 bits security
+        /// <summary>HQC parameter set targeting 128-bit security.</summary>
         public static readonly HqcParameters hqc128 = new HqcParameters("HQC-128", 17669, 46, 384, 16, 15, 66, 75, 4, 243079, 2241, 2321,
             new[]{ 89, 69, 153, 116, 176, 117, 111, 75, 73, 233, 242, 233, 65, 210, 21, 139, 103, 173, 67, 118, 105, 210, 174, 110, 74, 69, 228, 82, 255, 181, 1 });
 
-        // 192 bits security
+        /// <summary>HQC parameter set targeting 192-bit security.</summary>
         public static readonly HqcParameters hqc192 = new HqcParameters("HQC-192", 35851, 56, 640, 24, 16, 100, 114, 5, 119800, 4514, 4602,
             new[]{ 45, 216, 239, 24, 253, 104, 27, 40, 107, 50, 163, 210, 227, 134, 224, 158, 119, 13, 158, 1, 238, 164, 82, 43, 15, 232, 246, 142, 50, 189, 29, 232, 1 });
 
-        // 256 bits security
+        /// <summary>HQC parameter set targeting 256-bit security.</summary>
         public static readonly HqcParameters hqc256 = new HqcParameters("HQC-256", 57637, 90, 640, 32, 29, 131, 149, 5, 74517, 7237, 7333,
             new[]{ 49, 167, 49, 39, 200, 121, 124, 91, 240, 63, 148, 71, 150, 123, 87, 101, 32, 215, 159, 71, 201, 115, 97, 210, 186, 183, 141, 217, 123, 12, 31, 243, 180, 219, 152, 239, 99, 141, 4, 246, 191, 144, 8, 232, 47, 27, 141, 178, 130, 64, 124, 47, 39, 188, 216, 48, 199, 187, 1 });
 
@@ -54,18 +55,25 @@ private HqcParameters(string name, int n, int n1, int n2, int k, int delta, int
 
         internal HqcEngine Engine => m_engine;
 
+        /// <summary>The length, in bytes, of an HQC ciphertext (encapsulation).</summary>
         public int EncapsulationLength => m_engine.CipherTextBytes;
 
+        /// <summary>The session (shared) key size, in bits.</summary>
         public int SessionKeySize => 32 * 8;
 
+        /// <summary>The name of this parameter set.</summary>
         public string Name => m_name;
 
+        /// <summary>The length, in bytes, of an HQC public key.</summary>
         public int PublicKeyBytes => m_publicKeyBytes;
 
+        /// <summary>The length, in bytes, of an HQC private key.</summary>
         public int SecretKeyBytes => m_secretKeyBytes;
 
+        /// <summary>The length, in bytes, of the shared secret.</summary>
         public int SecretLength => HqcEngine.SharedSecretBytes;
 
+        /// <inheritdoc/>
         public override string ToString() => Name;
     }
 }

crypto/src/pqc/crypto/hqc/HqcPrivateKeyParameters.cs

@@ -4,24 +4,31 @@
 
 namespace Org.BouncyCastle.Pqc.Crypto.Hqc
 {
+    /// <summary>An HQC private (decapsulation) key, represented by its raw byte encoding.</summary>
     public sealed class HqcPrivateKeyParameters
         : HqcKeyParameters
     {
         private readonly byte[] m_sk;
 
+        /// <summary>Creates an HQC private key from its raw encoding.</summary>
+        /// <param name="param">The HQC parameter set this key belongs to.</param>
+        /// <param name="sk">The raw private key bytes; a defensive copy is taken.</param>
         // TODO[api] Rename to 'parameters'
         public HqcPrivateKeyParameters(HqcParameters param, byte[] sk)
             : base(isPrivate: true, param)
         {
             m_sk = Arrays.CopyBuffer(sk);
         }
 
+        /// <summary>Returns a copy of the raw private key encoding.</summary>
         public byte[] GetEncoded() => GetPrivateKey();
 
+        /// <summary>Returns a copy of the raw private key bytes.</summary>
         public byte[] GetPrivateKey() => Arrays.CopyBuffer(m_sk);
 
         internal byte[] InternalPrivateKey => m_sk;
 
+        /// <summary>Obsolete. Use <see cref="GetPrivateKey"/> instead.</summary>
         [Obsolete("Use 'GetPrivateKey' instead")]
         public byte[] PrivateKey => GetPrivateKey();
     }

crypto/src/pqc/crypto/hqc/HqcPublicKeyParameters.cs

@@ -4,24 +4,31 @@
 
 namespace Org.BouncyCastle.Pqc.Crypto.Hqc
 {
+    /// <summary>An HQC public (encapsulation) key, represented by its raw byte encoding.</summary>
     public sealed class HqcPublicKeyParameters
         : HqcKeyParameters
     {
         private readonly byte[] m_pk;
 
+        /// <summary>Creates an HQC public key from its raw encoding.</summary>
+        /// <param name="param">The HQC parameter set this key belongs to.</param>
+        /// <param name="pk">The raw public key bytes; a defensive copy is taken.</param>
         // TODO[api] Rename to 'parameters'
         public HqcPublicKeyParameters(HqcParameters param, byte[] pk)
             : base(isPrivate: false, param)
         {
             m_pk = Arrays.CopyBuffer(pk);
         }
 
+        /// <summary>Returns a copy of the raw public key encoding.</summary>
         public byte[] GetEncoded() => GetPublicKey();
 
+        /// <summary>Returns a copy of the raw public key bytes.</summary>
         public byte[] GetPublicKey() => Arrays.CopyBuffer(m_pk);
 
         internal byte[] InternalPublicKey => m_pk;
 
+        /// <summary>Obsolete. Use <see cref="GetPublicKey"/> instead.</summary>
         [Obsolete("Use 'GetPublicKey' instead")]
         public byte[] PublicKey => GetPublicKey();
     }