Skip to content

docs: add XML documentation for modern-curve parameters (Batch 7)#677

Open
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/modern-curves-docs
Open

docs: add XML documentation for modern-curve parameters (Batch 7)#677
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/modern-curves-docs

Conversation

@KonradSop
Copy link
Copy Markdown
Contributor

Description

Adds XML documentation to the public/private/key-generation parameter classes for the RFC 8032 EdDSA curves (Ed25519, Ed448) and RFC 7748 X-DH curves (X25519, X448). These are user-facing entry points for modern signing and key-agreement workflows that previously carried no API documentation.

  • Ed25519 / Ed448 public-key params — class summary citing RFC 8032; per-constructor exception contracts (length validation, EOF on stream read, point-decode failures); Encode/GetEncoded summaries; Verify documenting the pure / context / prehash variant selector and the conditions each places on ctx and msgLen.
  • Ed25519 / Ed448 private-key params — class summary noting the lazy public-key cache; constructor exceptions; Encode/GetEncoded; GeneratePublicKey; Sign mirroring the Verify documentation.
  • X25519 / X448 public-key params — class summary citing RFC 7748 and noting that point validation is deferred to scalar multiplication; constructor exceptions; Encode/GetEncoded.
  • X25519 / X448 private-key params — class summary noting clamped scalar; GeneratePublicKey; GenerateSecret documenting the InvalidOperationException raised on degenerate (all-zero) secrets.
  • Key-generation parameters — class and constructor summaries citing the relevant RFC and noting the fixed strength.

Key Accomplishments

  • Discoverability: First-time IDE tooltips for the modern curves now identify the RFC, key/seed/scalar size, and signature size.
  • Accurate exception contracts: <exception> tags only added where the method body actually throws — the EdDSA Verify/Sign algorithm-selector exceptions, X-DH agreement failure, length-validation guards, and stream-EOF guards.
  • Consistent style: Class summaries follow the Batch 5 PQC-params pattern (RFC reference, what is wrapped, validation strategy). Span-overload entries cross-reference the byte-array overload via <see cref=...>.

Verification

  • Build Status: dotnet build crypto/src/BouncyCastle.Crypto.csproj -c Release — succeeded on net6.0, netstandard2.0, net461 with no new warnings.
  • Scope: Documentation-only; no behavioural or signature changes.

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 public/private/key-generation parameter classes for the
RFC 8032 EdDSA and RFC 7748 X-DH curves: Ed25519, Ed448, X25519, X448.
Adds class-level summaries citing the relevant RFC and per-method
<summary>, <param>, <returns>, and <exception> tags for the public API
(constructors, encoders, key derivation, sign/verify, agreement). No
behavioural 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