Skip to content

docs: add XML documentation for SLH-DSA parameters (Batch 8)#678

Open
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/slh-dsa-docs
Open

docs: add XML documentation for SLH-DSA parameters (Batch 8)#678
KonradSop wants to merge 1 commit intobcgit:masterfrom
KonradSop:feature/slh-dsa-docs

Conversation

@KonradSop
Copy link
Copy Markdown
Contributor

Adds XML documentation to the SLH-DSA parameter classes under crypto/src/crypto/parameters — the stateless hash-based signature scheme standardised by NIST in FIPS 205. Closes the post-quantum trio that PR #673 began (ML-KEM / ML-DSA), giving each of the three FIPS PQC primitives a consistent documentation surface.

  • SlhDsaParameters — class summary citing FIPS 205 and explaining the pure / HashSLH-DSA split (FIPS 205 §10.2). Per-instance summaries identify each of the 24 parameter constants by NIST security category, fast/small variant and hash family. Public members (IsPreHash, Name, ParameterSet, ToString) documented with their semantic role.
  • SlhDsaParameterSet — class summary describing the FIPS 205 tree-shape parameters. Per-constant summaries record the WOTS+, hypertree and FORS shape (n, h, d, k, a).
  • SlhDsaKeyParameters — abstract base; class summary plus Parameters accessor doc.
  • SlhDsaPublicKeyParameters — class summary explaining the (seed, root) tuple. FromEncoding documents the 2 * n length contract and the ArgumentNullException / ArgumentException it raises. GetEncoded documented.
  • SlhDsaPrivateKeyParameters — class summary explaining the (SK.seed, SK.prf, PK.seed, PK.root) tuple. FromEncoding documents the 4 * n length contract. GetEncoded, GetPublicKey, GetPublicKeyEncoded documented.
  • SlhDsaKeyGenerationParameters — class summary covering the SecureRandom + parameter-set pairing and noting why strength = 0. Both constructors document their exception contracts.

Key Accomplishments

  • Discoverability: First-time IDE tooltips for each of the 24 SLH-DSA parameter constants now identify the NIST category, fast/small variant and hash family without forcing a trip to the FIPS 205 spec.
  • Accurate exception contracts: <exception> tags only added where the method body actually throws — ArgumentNullException / ArgumentException on the FromEncoding and OID-lookup paths.
  • Consistent style: Class summaries follow the Batch 5 ML-KEM / ML-DSA pattern (FIPS reference, what is wrapped, decoding contract). Internal members and pre-existing implementation comments left untouched.

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 and
parameter selectors for SLH-DSA, the stateless hash-based signature
scheme standardised in FIPS 205.

Adds class-level summaries citing FIPS 205 and per-method <summary>,
<param>, <returns>, and <exception> tags for the public API surface
(parameter constants, FromEncoding entry points, GetEncoded /
GetPublicKey / GetPublicKeyEncoded helpers, and the two
SlhDsaKeyGenerationParameters constructors). 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