diff --git a/crypto/src/pqc/crypto/hqc/HqcKeyGenerationParameters.cs b/crypto/src/pqc/crypto/hqc/HqcKeyGenerationParameters.cs index dacc0676e..14e42a9c3 100644 --- a/crypto/src/pqc/crypto/hqc/HqcKeyGenerationParameters.cs +++ b/crypto/src/pqc/crypto/hqc/HqcKeyGenerationParameters.cs @@ -5,11 +5,16 @@ namespace Org.BouncyCastle.Pqc.Crypto.Hqc { + /// Key generation parameters for HQC, binding a randomness source to an HQC parameter set. public class HqcKeyGenerationParameters : KeyGenerationParameters { private readonly HqcParameters m_parameters; + /// Creates key generation parameters for the given HQC parameter set. + /// The randomness source for key generation. + /// The HQC parameter set to generate keys for. + /// If is null. // TODO[api] Rename to 'parameters' public HqcKeyGenerationParameters(SecureRandom random, HqcParameters param) : base(random, 256) @@ -17,6 +22,7 @@ public HqcKeyGenerationParameters(SecureRandom random, HqcParameters param) m_parameters = param ?? throw new ArgumentNullException(nameof(param)); } + /// The HQC parameter set keys will be generated for. public HqcParameters Parameters => m_parameters; } } diff --git a/crypto/src/pqc/crypto/hqc/HqcKeyParameters.cs b/crypto/src/pqc/crypto/hqc/HqcKeyParameters.cs index 29cc99cc0..e055cd5ab 100644 --- a/crypto/src/pqc/crypto/hqc/HqcKeyParameters.cs +++ b/crypto/src/pqc/crypto/hqc/HqcKeyParameters.cs @@ -2,6 +2,7 @@ namespace Org.BouncyCastle.Pqc.Crypto.Hqc { + /// Base class for HQC public and private keys, carrying the associated parameter set. public abstract class HqcKeyParameters : AsymmetricKeyParameter { @@ -13,6 +14,7 @@ internal HqcKeyParameters(bool isPrivate, HqcParameters parameters) m_parameters = parameters; } + /// The HQC parameter set this key belongs to. public HqcParameters Parameters => m_parameters; } } diff --git a/crypto/src/pqc/crypto/hqc/HqcParameters.cs b/crypto/src/pqc/crypto/hqc/HqcParameters.cs index 6a6936434..d33b3784a 100644 --- a/crypto/src/pqc/crypto/hqc/HqcParameters.cs +++ b/crypto/src/pqc/crypto/hqc/HqcParameters.cs @@ -2,20 +2,21 @@ namespace Org.BouncyCastle.Pqc.Crypto.Hqc { + /// HQC code-based KEM parameter sets (HQC-128, HQC-192, HQC-256). public sealed class HqcParameters : ICipherParameters { // TODO[api] Rename parameters instances and remove most properties - // 128 bits security + /// HQC parameter set targeting 128-bit security. 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 + /// HQC parameter set targeting 192-bit security. 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 + /// HQC parameter set targeting 256-bit security. 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; + /// The length, in bytes, of an HQC ciphertext (encapsulation). public int EncapsulationLength => m_engine.CipherTextBytes; + /// The session (shared) key size, in bits. public int SessionKeySize => 32 * 8; + /// The name of this parameter set. public string Name => m_name; + /// The length, in bytes, of an HQC public key. public int PublicKeyBytes => m_publicKeyBytes; + /// The length, in bytes, of an HQC private key. public int SecretKeyBytes => m_secretKeyBytes; + /// The length, in bytes, of the shared secret. public int SecretLength => HqcEngine.SharedSecretBytes; + /// public override string ToString() => Name; } } diff --git a/crypto/src/pqc/crypto/hqc/HqcPrivateKeyParameters.cs b/crypto/src/pqc/crypto/hqc/HqcPrivateKeyParameters.cs index ab8f13957..944c2fb16 100644 --- a/crypto/src/pqc/crypto/hqc/HqcPrivateKeyParameters.cs +++ b/crypto/src/pqc/crypto/hqc/HqcPrivateKeyParameters.cs @@ -4,11 +4,15 @@ namespace Org.BouncyCastle.Pqc.Crypto.Hqc { + /// An HQC private (decapsulation) key, represented by its raw byte encoding. public sealed class HqcPrivateKeyParameters : HqcKeyParameters { private readonly byte[] m_sk; + /// Creates an HQC private key from its raw encoding. + /// The HQC parameter set this key belongs to. + /// The raw private key bytes; a defensive copy is taken. // TODO[api] Rename to 'parameters' public HqcPrivateKeyParameters(HqcParameters param, byte[] sk) : base(isPrivate: true, param) @@ -16,12 +20,15 @@ public HqcPrivateKeyParameters(HqcParameters param, byte[] sk) m_sk = Arrays.CopyBuffer(sk); } + /// Returns a copy of the raw private key encoding. public byte[] GetEncoded() => GetPrivateKey(); + /// Returns a copy of the raw private key bytes. public byte[] GetPrivateKey() => Arrays.CopyBuffer(m_sk); internal byte[] InternalPrivateKey => m_sk; + /// Obsolete. Use instead. [Obsolete("Use 'GetPrivateKey' instead")] public byte[] PrivateKey => GetPrivateKey(); } diff --git a/crypto/src/pqc/crypto/hqc/HqcPublicKeyParameters.cs b/crypto/src/pqc/crypto/hqc/HqcPublicKeyParameters.cs index c25dba953..2ae135a41 100644 --- a/crypto/src/pqc/crypto/hqc/HqcPublicKeyParameters.cs +++ b/crypto/src/pqc/crypto/hqc/HqcPublicKeyParameters.cs @@ -4,11 +4,15 @@ namespace Org.BouncyCastle.Pqc.Crypto.Hqc { + /// An HQC public (encapsulation) key, represented by its raw byte encoding. public sealed class HqcPublicKeyParameters : HqcKeyParameters { private readonly byte[] m_pk; + /// Creates an HQC public key from its raw encoding. + /// The HQC parameter set this key belongs to. + /// The raw public key bytes; a defensive copy is taken. // TODO[api] Rename to 'parameters' public HqcPublicKeyParameters(HqcParameters param, byte[] pk) : base(isPrivate: false, param) @@ -16,12 +20,15 @@ public HqcPublicKeyParameters(HqcParameters param, byte[] pk) m_pk = Arrays.CopyBuffer(pk); } + /// Returns a copy of the raw public key encoding. public byte[] GetEncoded() => GetPublicKey(); + /// Returns a copy of the raw public key bytes. public byte[] GetPublicKey() => Arrays.CopyBuffer(m_pk); internal byte[] InternalPublicKey => m_pk; + /// Obsolete. Use instead. [Obsolete("Use 'GetPublicKey' instead")] public byte[] PublicKey => GetPublicKey(); }