Skip to content

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

Open
KonradSop wants to merge 1 commit into
bcgit:masterfrom
KonradSop:feature/keypair-generators-docs
Open

docs: add XML documentation for modern asymmetric key-pair generators (Batch 10)#681
KonradSop wants to merge 1 commit into
bcgit:masterfrom
KonradSop:feature/keypair-generators-docs

Conversation

@KonradSop
Copy link
Copy Markdown
Contributor

Adds XML documentation to the seven key-pair generators that pair with the parameter classes covered by PRs #673 (Batch 5), #677 (Batch 7), #678 (Batch 8) and #679 (Batch 9):

  • MLKemKeyPairGenerator — class summary citing FIPS 203; Init documents the InvalidCastException raised when the supplied KeyGenerationParameters is not an MLKemKeyGenerationParameters; GenerateKeyPair notes the SeedAndEncoding format used for the produced private key.
  • MLDsaKeyPairGenerator — same shape as ML-KEM, citing FIPS 204.
  • SlhDsaKeyPairGenerator — class summary citing FIPS 205; GenerateKeyPair notes that the three n-byte seeds (SK.seed, SK.prf, PK.seed) are drawn from the SecureRandom and that the hypertree root is computed up front.
  • Ed25519KeyPairGenerator / Ed448KeyPairGenerator — class summaries citing RFC 8032; Init / GenerateKeyPair documented; class summary notes the seed size (32 / 57 bytes).
  • X25519KeyPairGenerator / X448KeyPairGenerator — class summaries citing RFC 7748; Init / GenerateKeyPair documented; class summary notes the clamped scalar size (32 / 56 bytes).

Key Accomplishments

  • Closes the modern-asymmetric documentation surface: with KeyGenerationParameters already documented (Batches 5/7/8/9 and docs: add XML documentation for ML-KEM and ML-DSA parameter gaps (Batch 9) #679), the matching IAsymmetricCipherKeyPairGenerator implementations now carry the same level of XML coverage.
  • Accurate exception contracts: <exception cref="InvalidCastException"/> only added on the three PQC generators whose Init performs the cast; the four EdDSA/X-DH generators only capture SecureRandom so they don't throw.
  • Build hygiene: added the missing using System; to the three PQC generator files so the new InvalidCastException cref resolves cleanly. No other source changes.
  • Consistent style: Class summaries follow the same FIPS / RFC reference pattern used in Batches 5/7/8/9.
  • No overlap with open PRs: scope is disjoint from feature/modern-curves-docs (Batch 7), feature/slh-dsa-docs (Batch 8) and feature/ml-pqc-gaps-docs (Batch 9). The recent 5cdc6f51 Refactor Falcon key parameter classes upstream commit does not touch any of these files.

Verification

  • Build Status: dotnet build crypto/src/BouncyCastle.Crypto.csproj -c Release — succeeded on net6.0, netstandard2.0, net461 with no new warnings (the remaining warnings are pre-existing in unrelated files).
  • Scope: Documentation-only; the only non-doc edits are three using System; directives needed for the InvalidCastException cref.

Checklist before requesting a review

  • I have performed a self-review of my code
  • I have kept the patch limited to only change the parts related to the patch
  • This change requires a documentation update

See also Contributing Guidelines.

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
<summary>, <param>, <returns>, and <exception> 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant