From 57d41c31afd8ade96af61922dcf5e3a0f178f307 Mon Sep 17 00:00:00 2001 From: Konradsop Date: Thu, 14 May 2026 18:51:38 +0200 Subject: [PATCH] docs: add XML documentation for modern asymmetric key-pair generators Document the seven IAsymmetricCipherKeyPairGenerator implementations that pair with the modern asymmetric parameter classes: MLKem, MLDsa, SlhDsa, Ed25519, Ed448, X25519, X448. Adds class-level summaries citing FIPS 203 / FIPS 204 / FIPS 205 / RFC 8032 / RFC 7748 and per-method , , , and tags for the Init and GenerateKeyPair surface. The three PQC generators also pick up a missing 'using System;' so the InvalidCastException cref raised by Init resolves cleanly; no other source changes. --- .../generators/Ed25519KeyPairGenerator.cs | 6 ++++++ .../generators/Ed448KeyPairGenerator.cs | 6 ++++++ .../generators/MLDsaKeyPairGenerator.cs | 19 ++++++++++++++++++- .../generators/MLKemKeyPairGenerator.cs | 17 +++++++++++++++++ .../generators/SlhDsaKeyPairGenerator.cs | 18 +++++++++++++++++- .../generators/X25519KeyPairGenerator.cs | 6 ++++++ .../crypto/generators/X448KeyPairGenerator.cs | 6 ++++++ 7 files changed, 76 insertions(+), 2 deletions(-) diff --git a/crypto/src/crypto/generators/Ed25519KeyPairGenerator.cs b/crypto/src/crypto/generators/Ed25519KeyPairGenerator.cs index 266d111cfb..094a0e1729 100644 --- a/crypto/src/crypto/generators/Ed25519KeyPairGenerator.cs +++ b/crypto/src/crypto/generators/Ed25519KeyPairGenerator.cs @@ -5,16 +5,22 @@ namespace Org.BouncyCastle.Crypto.Generators { + /// + /// Key-pair generator for Ed25519 (RFC 8032). Only the from the supplied + /// is used; the 32-byte seed is drawn directly from it. + /// public class Ed25519KeyPairGenerator : IAsymmetricCipherKeyPairGenerator { private SecureRandom random; + /// Capture the that will source the seed. public virtual void Init(KeyGenerationParameters parameters) { this.random = parameters.Random; } + /// Generate a fresh Ed25519 key pair. public virtual AsymmetricCipherKeyPair GenerateKeyPair() { Ed25519PrivateKeyParameters privateKey = new Ed25519PrivateKeyParameters(random); diff --git a/crypto/src/crypto/generators/Ed448KeyPairGenerator.cs b/crypto/src/crypto/generators/Ed448KeyPairGenerator.cs index 50aee631e4..c4a97e14a1 100644 --- a/crypto/src/crypto/generators/Ed448KeyPairGenerator.cs +++ b/crypto/src/crypto/generators/Ed448KeyPairGenerator.cs @@ -5,16 +5,22 @@ namespace Org.BouncyCastle.Crypto.Generators { + /// + /// Key-pair generator for Ed448 (RFC 8032). Only the from the supplied + /// is used; the 57-byte seed is drawn directly from it. + /// public class Ed448KeyPairGenerator : IAsymmetricCipherKeyPairGenerator { private SecureRandom random; + /// Capture the that will source the seed. public virtual void Init(KeyGenerationParameters parameters) { this.random = parameters.Random; } + /// Generate a fresh Ed448 key pair. public virtual AsymmetricCipherKeyPair GenerateKeyPair() { Ed448PrivateKeyParameters privateKey = new Ed448PrivateKeyParameters(random); diff --git a/crypto/src/crypto/generators/MLDsaKeyPairGenerator.cs b/crypto/src/crypto/generators/MLDsaKeyPairGenerator.cs index 0632b334b1..dbcfbf05ec 100644 --- a/crypto/src/crypto/generators/MLDsaKeyPairGenerator.cs +++ b/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 { + /// + /// Key-pair generator for ML-DSA (FIPS 204). Driven by an + /// init payload; produces an bound to the chosen parameter set. + /// public sealed class MLDsaKeyPairGenerator : IAsymmetricCipherKeyPairGenerator { private SecureRandom m_random; private MLDsaParameters m_parameters; + /// + /// Initialise with an instance; the + /// and parameter set are taken from it. + /// + /// If is not an + /// . public void Init(KeyGenerationParameters parameters) { m_random = parameters.Random; m_parameters = ((MLDsaKeyGenerationParameters)parameters).Parameters; } + /// + /// Generate a fresh ML-DSA key pair. The private key is returned with + /// so the resulting key carries both + /// the 32-byte seed and the expanded encoding. + /// public AsymmetricCipherKeyPair GenerateKeyPair() { var engine = m_parameters.ParameterSet.GetEngine(m_random); diff --git a/crypto/src/crypto/generators/MLKemKeyPairGenerator.cs b/crypto/src/crypto/generators/MLKemKeyPairGenerator.cs index ba96a9ce55..ea9d747a88 100644 --- a/crypto/src/crypto/generators/MLKemKeyPairGenerator.cs +++ b/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 { + /// + /// Key-pair generator for ML-KEM (FIPS 203). Driven by an + /// init payload; produces an bound to the chosen parameter set. + /// public class MLKemKeyPairGenerator : IAsymmetricCipherKeyPairGenerator { private SecureRandom m_random; private MLKemParameters m_parameters; + /// + /// Initialise with an instance; the + /// and parameter set are taken from it. + /// + /// If is not an + /// . public void Init(KeyGenerationParameters parameters) { m_random = parameters.Random; m_parameters = ((MLKemKeyGenerationParameters)parameters).Parameters; } + /// + /// Generate a fresh ML-KEM key pair. The private key is returned with + /// so the resulting key carries both + /// the 64-byte seed and the expanded encoding. + /// public AsymmetricCipherKeyPair GenerateKeyPair() { m_parameters.ParameterSet.Engine.GenerateKemKeyPair(m_random, out byte[] seed, out byte[] encoding); diff --git a/crypto/src/crypto/generators/SlhDsaKeyPairGenerator.cs b/crypto/src/crypto/generators/SlhDsaKeyPairGenerator.cs index 695a870324..e97b827c33 100644 --- a/crypto/src/crypto/generators/SlhDsaKeyPairGenerator.cs +++ b/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 { + /// + /// Key-pair generator for SLH-DSA (FIPS 205). Driven by an + /// init payload; produces an bound to the chosen parameter set. + /// public sealed class SlhDsaKeyPairGenerator : IAsymmetricCipherKeyPairGenerator { private SecureRandom m_random; private SlhDsaParameters m_parameters; + /// + /// Initialise with an instance; the + /// and parameter set are taken from it. + /// + /// If is not an + /// . public void Init(KeyGenerationParameters parameters) { m_random = parameters.Random; m_parameters = ((SlhDsaKeyGenerationParameters)parameters).Parameters; } + /// + /// Generate a fresh SLH-DSA key pair by drawing the three n-byte seeds + /// (SK.seed, SK.prf, PK.seed) and computing the hypertree root. + /// public AsymmetricCipherKeyPair GenerateKeyPair() { var engine = m_parameters.ParameterSet.GetEngine(); diff --git a/crypto/src/crypto/generators/X25519KeyPairGenerator.cs b/crypto/src/crypto/generators/X25519KeyPairGenerator.cs index 94378448bd..11cc4df109 100644 --- a/crypto/src/crypto/generators/X25519KeyPairGenerator.cs +++ b/crypto/src/crypto/generators/X25519KeyPairGenerator.cs @@ -5,16 +5,22 @@ namespace Org.BouncyCastle.Crypto.Generators { + /// + /// Key-pair generator for X25519 (RFC 7748). Only the from the supplied + /// is used; the 32-byte clamped scalar is drawn directly from it. + /// public class X25519KeyPairGenerator : IAsymmetricCipherKeyPairGenerator { private SecureRandom random; + /// Capture the that will source the scalar. public virtual void Init(KeyGenerationParameters parameters) { this.random = parameters.Random; } + /// Generate a fresh X25519 key pair. public virtual AsymmetricCipherKeyPair GenerateKeyPair() { X25519PrivateKeyParameters privateKey = new X25519PrivateKeyParameters(random); diff --git a/crypto/src/crypto/generators/X448KeyPairGenerator.cs b/crypto/src/crypto/generators/X448KeyPairGenerator.cs index 4a203e4f19..a8390f5af4 100644 --- a/crypto/src/crypto/generators/X448KeyPairGenerator.cs +++ b/crypto/src/crypto/generators/X448KeyPairGenerator.cs @@ -5,16 +5,22 @@ namespace Org.BouncyCastle.Crypto.Generators { + /// + /// Key-pair generator for X448 (RFC 7748). Only the from the supplied + /// is used; the 56-byte clamped scalar is drawn directly from it. + /// public class X448KeyPairGenerator : IAsymmetricCipherKeyPairGenerator { private SecureRandom random; + /// Capture the that will source the scalar. public virtual void Init(KeyGenerationParameters parameters) { this.random = parameters.Random; } + /// Generate a fresh X448 key pair. public virtual AsymmetricCipherKeyPair GenerateKeyPair() { X448PrivateKeyParameters privateKey = new X448PrivateKeyParameters(random);