diff --git a/crypto/src/pqc/crypto/cmce/CmceKeyGenerationParameters.cs b/crypto/src/pqc/crypto/cmce/CmceKeyGenerationParameters.cs index 1bac7419f..8b3f75d5e 100644 --- a/crypto/src/pqc/crypto/cmce/CmceKeyGenerationParameters.cs +++ b/crypto/src/pqc/crypto/cmce/CmceKeyGenerationParameters.cs @@ -3,17 +3,24 @@ namespace Org.BouncyCastle.Pqc.Crypto.Cmce { + /// + /// Key generation parameters for Classic McEliece, binding a randomness source to a parameter set. + /// public sealed class CmceKeyGenerationParameters : KeyGenerationParameters { private CmceParameters parameters; + /// Creates key generation parameters for the given Classic McEliece parameter set. + /// The randomness source for key generation. + /// The Classic McEliece parameter set to generate keys for. public CmceKeyGenerationParameters(SecureRandom random, CmceParameters CmceParams) : base(random, 256) { this.parameters = CmceParams; } + /// The Classic McEliece parameter set keys will be generated for. public CmceParameters Parameters => parameters; } } diff --git a/crypto/src/pqc/crypto/cmce/CmceKeyParameters.cs b/crypto/src/pqc/crypto/cmce/CmceKeyParameters.cs index e66fb66d1..65c35e7bb 100644 --- a/crypto/src/pqc/crypto/cmce/CmceKeyParameters.cs +++ b/crypto/src/pqc/crypto/cmce/CmceKeyParameters.cs @@ -2,6 +2,7 @@ namespace Org.BouncyCastle.Pqc.Crypto.Cmce { + /// Base class for Classic McEliece public and private keys, carrying the parameter set. public abstract class CmceKeyParameters : AsymmetricKeyParameter { @@ -13,6 +14,7 @@ internal CmceKeyParameters(bool isPrivate, CmceParameters parameters) this.parameters = parameters; } + /// The Classic McEliece parameter set this key belongs to. public CmceParameters Parameters => parameters; } } diff --git a/crypto/src/pqc/crypto/cmce/CmceParameters.cs b/crypto/src/pqc/crypto/cmce/CmceParameters.cs index be8f54177..c876dd24e 100644 --- a/crypto/src/pqc/crypto/cmce/CmceParameters.cs +++ b/crypto/src/pqc/crypto/cmce/CmceParameters.cs @@ -4,6 +4,10 @@ namespace Org.BouncyCastle.Pqc.Crypto.Cmce { + /// + /// Classic McEliece code-based KEM parameter sets. The f variants use the semi-systematic ("fast") + /// matrix-reduction form, which speeds up key generation without changing the key format. + /// public sealed class CmceParameters : ICipherParameters { @@ -13,33 +17,43 @@ public sealed class CmceParameters private static readonly int[] poly6960 = new int[] {8, 0}; private static readonly int[] poly8192 = new int[] {7, 2, 1, 0}; + /// mceliece348864 parameter set (128-bit security). public static readonly CmceParameters mceliece348864r3 = new CmceParameters("mceliece348864", 12, 3488, 64, poly3488, false, 128); + /// mceliece348864f parameter set (128-bit security, fast key generation). public static readonly CmceParameters mceliece348864fr3 = new CmceParameters("mceliece348864f", 12, 3488, 64, poly3488, true, 128); + /// mceliece460896 parameter set (192-bit security). public static readonly CmceParameters mceliece460896r3 = new CmceParameters("mceliece460896", 13, 4608, 96, poly4608, false, 192); + /// mceliece460896f parameter set (192-bit security, fast key generation). public static readonly CmceParameters mceliece460896fr3 = new CmceParameters("mceliece460896f", 13, 4608, 96, poly4608, true, 192); + /// mceliece6688128 parameter set (256-bit security). public static readonly CmceParameters mceliece6688128r3 = new CmceParameters("mceliece6688128", 13, 6688, 128, poly6688, false, 256); + /// mceliece6688128f parameter set (256-bit security, fast key generation). public static readonly CmceParameters mceliece6688128fr3 = new CmceParameters("mceliece6688128f", 13, 6688, 128, poly6688, true, 256); + /// mceliece6960119 parameter set (256-bit security). public static readonly CmceParameters mceliece6960119r3 = new CmceParameters("mceliece6960119", 13, 6960, 119, poly6960, false, 256); + /// mceliece6960119f parameter set (256-bit security, fast key generation). public static readonly CmceParameters mceliece6960119fr3 = new CmceParameters("mceliece6960119f", 13, 6960, 119, poly6960, true, 256); + /// mceliece8192128 parameter set (256-bit security). public static readonly CmceParameters mceliece8192128r3 = new CmceParameters("mceliece8192128", 13, 8192, 128, poly8192, false, 256); + /// mceliece8192128f parameter set (256-bit security, fast key generation). public static readonly CmceParameters mceliece8192128fr3 = new CmceParameters("mceliece8192128f", 13, 8192, 128, poly8192, true, 256); @@ -75,18 +89,25 @@ private CmceParameters(string name, int m, int n, int t, int[] p, bool usePivots } } + /// The name of this parameter set. public string Name => name; + /// The field extension degree m (GF(2^m)). public int M => m; + /// The code length n. public int N => n; + /// The number of errors / Goppa polynomial degree t. public int T => t; + /// The semi-systematic parameter mu (non-zero only for the fast variants). public int Mu => usePivots ? 32 : 0; + /// The semi-systematic parameter nu (non-zero only for the fast variants). public int Nu => usePivots ? 64 : 0; + /// The default session key size, in bits. public int DefaultKeySize => defaultKeySize; internal ICmceEngine Engine => engine; diff --git a/crypto/src/pqc/crypto/cmce/CmcePrivateKeyParameters.cs b/crypto/src/pqc/crypto/cmce/CmcePrivateKeyParameters.cs index d9f2fd6e7..b69f510cd 100644 --- a/crypto/src/pqc/crypto/cmce/CmcePrivateKeyParameters.cs +++ b/crypto/src/pqc/crypto/cmce/CmcePrivateKeyParameters.cs @@ -4,22 +4,34 @@ namespace Org.BouncyCastle.Pqc.Crypto.Cmce { + /// A Classic McEliece private (decapsulation) key, represented by its raw byte encoding. public sealed class CmcePrivateKeyParameters : CmceKeyParameters { internal readonly byte[] privateKey; + /// Returns a copy of the raw private key bytes. public byte[] GetPrivateKey() { return Arrays.Clone(privateKey); } + /// Creates a Classic McEliece private key from its raw encoding. + /// The Classic McEliece parameter set this key belongs to. + /// The raw private key bytes; a defensive copy is taken. public CmcePrivateKeyParameters(CmceParameters parameters, byte[] privateKey) : base(true, parameters) { this.privateKey = Arrays.Clone(privateKey); } + /// Creates a Classic McEliece private key from its component fields. + /// The Classic McEliece parameter set this key belongs to. + /// The delta component. + /// The C component. + /// The Goppa polynomial component. + /// The field-ordering component. + /// The s component. public CmcePrivateKeyParameters(CmceParameters parameters, byte[] delta, byte[] C, byte[] g, byte[] alpha, byte[] s) : base(true, parameters) @@ -39,8 +51,10 @@ public CmcePrivateKeyParameters(CmceParameters parameters, byte[] delta, byte[] } + /// Reconstructs the matching public key from this private key. public byte[] ReconstructPublicKey() => Parameters.Engine.GeneratePublicKeyFromPrivateKey(privateKey); + /// Returns a copy of the raw private key encoding. public byte[] GetEncoded() { return Arrays.Clone(privateKey); diff --git a/crypto/src/pqc/crypto/cmce/CmcePublicKeyParameters.cs b/crypto/src/pqc/crypto/cmce/CmcePublicKeyParameters.cs index f70c6ff03..e45c255f5 100644 --- a/crypto/src/pqc/crypto/cmce/CmcePublicKeyParameters.cs +++ b/crypto/src/pqc/crypto/cmce/CmcePublicKeyParameters.cs @@ -2,22 +2,28 @@ namespace Org.BouncyCastle.Pqc.Crypto.Cmce { + /// A Classic McEliece public (encapsulation) key, represented by its raw byte encoding. public sealed class CmcePublicKeyParameters : CmceKeyParameters { internal readonly byte[] publicKey; + /// Creates a Classic McEliece public key from its raw encoding. + /// The Classic McEliece parameter set this key belongs to. + /// The raw public key bytes; a defensive copy is taken. public CmcePublicKeyParameters(CmceParameters parameters, byte[] publicKey) : base(false, parameters) { this.publicKey = Arrays.Clone(publicKey); } + /// Returns a copy of the raw public key bytes. public byte[] GetPublicKey() - { + { return Arrays.Clone(publicKey); } + /// Returns a copy of the raw public key encoding. public byte[] GetEncoded() { return GetPublicKey();