Add comments

paulmillr · Jan 2, 2025 · ca3807a · ca3807a
1 parent bd500f9
commit ca3807a
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 7 deletions.
diff --git a/src/ml-dsa.ts b/src/ml-dsa.ts
@@ -47,6 +47,7 @@ type Param = {
   ETA: number;
   OMEGA: number;
 };
+/** Internal params for different versions of ML-DSA  */
 // prettier-ignore
 export const PARAMS: Record<string, Param> = {
   2: { K: 4, L: 4, D, GAMMA1: 2 ** 17, GAMMA2: GAMMA2_1, TAU: 39, ETA: 2, OMEGA: 80 },
@@ -525,9 +526,10 @@ function getDilithium(opts: DilithiumOpts) {
   };
 }
 
+/** Signer API, containing internal methods */
 export type SignerWithInternal = Signer & { internal: Signer };
 
-// ML-DSA
+/** ML-DSA-44 for 128-bit security level. As per ASD, not recommended after 2030. */
 export const ml_dsa44: SignerWithInternal = /* @__PURE__ */ getDilithium({
   ...PARAMS[2],
   CRH_BYTES: 64,
@@ -537,6 +539,7 @@ export const ml_dsa44: SignerWithInternal = /* @__PURE__ */ getDilithium({
   XOF256,
 });
 
+/** ML-DSA-65 for 192-bit security level. As per ASD, not recommended after 2030. */
 export const ml_dsa65: SignerWithInternal = /* @__PURE__ */ getDilithium({
   ...PARAMS[3],
   CRH_BYTES: 64,
@@ -546,6 +549,7 @@ export const ml_dsa65: SignerWithInternal = /* @__PURE__ */ getDilithium({
   XOF256,
 });
 
+/** ML-DSA-87 for 256-bit security level. As per ASD, OK after 2030. */
 export const ml_dsa87: SignerWithInternal = /* @__PURE__ */ getDilithium({
   ...PARAMS[5],
   CRH_BYTES: 64,

diff --git a/src/ml-kem.ts b/src/ml-kem.ts
@@ -34,6 +34,7 @@ import {
  * @module
  */
 
+/** Key encapsulation mechanism interface */
 export type KEM = {
   publicKeyLen: number;
   msgLen: number;
@@ -65,7 +66,7 @@ const { mod, nttZetas, NTT, bitsCoder } = genCrystals({
   isKyber: true,
 });
 
-// FIPS 203: 7. Parameter Sets
+/** FIPS 203: 7. Parameter Sets */
 type ParameterSet = {
   N: number;
   K: number;
@@ -76,6 +77,7 @@ type ParameterSet = {
   dv: number;
   RBGstrength: number;
 };
+/** Internal params of ML-KEM versions */
 // prettier-ignore
 export const PARAMS: Record<string, ParameterSet> = {
   512: { N, Q, K: 2, ETA1: 3, ETA2: 2, du: 10, dv: 4, RBGstrength: 128 },
@@ -344,17 +346,19 @@ const opts = {
   PRF: shakePRF,
 };
 
-/**
- * FIPS-203 ML-KEM.
- */
+/** ML-KEM-512 for 128-bit security level. As per ASD, not recommended after 2030. */
 export const ml_kem512: KEM = /* @__PURE__ */ createKyber({
   ...opts,
   ...PARAMS[512],
 });
+
+/** ML-KEM-768, for 192-bit security level. As per ASD, not recommended after 2030. */
 export const ml_kem768: KEM = /* @__PURE__ */ createKyber({
   ...opts,
   ...PARAMS[768],
 });
+
+/** ML-KEM-1024 for 256-bit security level. As per ASD, OK after 2030. */
 export const ml_kem1024: KEM = /* @__PURE__ */ createKyber({
   ...opts,
   ...PARAMS[1024],

diff --git a/src/slh-dsa.ts b/src/slh-dsa.ts
@@ -18,6 +18,9 @@ import {
  * StateLess Hash-based Digital Signature Standard (SLH-DSA). A.k.a. Sphincs+.
  * FIPS-205 (spec v3.1) is implemented.
  *
+ * There are many different kinds of SLH, but basically `sha2` / `shake` indicate internal hash,
+ * `128` / `192` / `256` indicate security level, and `s` /`f` indicate trade-off (Small / Fast).
+ *
  * Hashes function similarly to signatures. You hash a private key to get a public key,
  * which can be used to verify the private key. However, this only works once since
  * disclosing the pre-image invalidates the key.
@@ -559,12 +562,17 @@ const genShake =
 
 const SHAKE_SIMPLE = { getContext: genShake() };
 
-// Only simple mode in SLH-DSA
+/** SLH-DSA: 128-bit fast SHAKE version. */
 export const slh_dsa_shake_128f: SphincsSigner = /* @__PURE__ */ gen(PARAMS['128f'], SHAKE_SIMPLE);
+/** SLH-DSA: 128-bit short SHAKE version. */
 export const slh_dsa_shake_128s: SphincsSigner = /* @__PURE__ */ gen(PARAMS['128s'], SHAKE_SIMPLE);
+/** SLH-DSA: 192-bit fast SHAKE version. */
 export const slh_dsa_shake_192f: SphincsSigner = /* @__PURE__ */ gen(PARAMS['192f'], SHAKE_SIMPLE);
+/** SLH-DSA: 192-bit short SHAKE version. */
 export const slh_dsa_shake_192s: SphincsSigner = /* @__PURE__ */ gen(PARAMS['192s'], SHAKE_SIMPLE);
+/** SLH-DSA: 256-bit fast SHAKE version. */
 export const slh_dsa_shake_256f: SphincsSigner = /* @__PURE__ */ gen(PARAMS['256f'], SHAKE_SIMPLE);
+/** SLH-DSA: 256-bit short SHAKE version. */
 export const slh_dsa_shake_256s: SphincsSigner = /* @__PURE__ */ gen(PARAMS['256s'], SHAKE_SIMPLE);
 
 type ShaType = typeof sha256 | typeof sha512;
@@ -665,10 +673,15 @@ const SHA512_SIMPLE = {
   getContext: genSha(sha256, sha512),
 };
 
-// Only simple mode in SLH-DSA
+/** SLH-DSA: 128-bit fast SHA2 version. */
 export const slh_dsa_sha2_128f: SphincsSigner = /* @__PURE__ */ gen(PARAMS['128f'], SHA256_SIMPLE);
+/** SLH-DSA: 128-bit small SHA2 version. */
 export const slh_dsa_sha2_128s: SphincsSigner = /* @__PURE__ */ gen(PARAMS['128s'], SHA256_SIMPLE);
+/** SLH-DSA: 192-bit fast SHA2 version. */
 export const slh_dsa_sha2_192f: SphincsSigner = /* @__PURE__ */ gen(PARAMS['192f'], SHA512_SIMPLE);
+/** SLH-DSA: 192-bit small SHA2 version. */
 export const slh_dsa_sha2_192s: SphincsSigner = /* @__PURE__ */ gen(PARAMS['192s'], SHA512_SIMPLE);
+/** SLH-DSA: 256-bit fast SHA2 version. */
 export const slh_dsa_sha2_256f: SphincsSigner = /* @__PURE__ */ gen(PARAMS['256f'], SHA512_SIMPLE);
+/** SLH-DSA: 256-bit small SHA2 version. */
 export const slh_dsa_sha2_256s: SphincsSigner = /* @__PURE__ */ gen(PARAMS['256s'], SHA512_SIMPLE);