More docs

paulmillr · Jan 3, 2025 · ffa0b85 · ffa0b85
1 parent c8265dc
commit ffa0b85
Show file tree

Hide file tree

Showing 5 changed files with 55 additions and 47 deletions.
diff --git a/src/_crystals.ts b/src/_crystals.ts
@@ -1,3 +1,7 @@
+/**
+ * Methods for lattices on ML-KEM and ML-DSA.
+ * @module
+ */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
 import { shake128, shake256 } from '@noble/hashes/sha3';
 import type { TypedArray } from '@noble/hashes/utils';

diff --git a/src/ml-dsa.ts b/src/ml-dsa.ts
@@ -1,3 +1,12 @@
+/**
+ * Module Lattice-based Digital Signature Algorithm (ML-DSA). A.k.a. CRYSTALS-Dilithium.
+ * FIPS-204 is implemented.
+ *
+ * Has similar internals to ML-KEM, but their keys and params are different.
+ * Check out [official site](https://www.pq-crystals.org/dilithium/index.shtml),
+ * [repo](https://github.com/pq-crystals/dilithium).
+ * @module
+ */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
 import { shake256 } from '@noble/hashes/sha3';
 import { genCrystals, XOF, XOF128, XOF256 } from './_crystals.js';
@@ -13,16 +22,6 @@ import {
   concatBytes,
 } from './utils.js';
 
-/**
- * Module Lattice-based Digital Signature Algorithm (ML-DSA). A.k.a. CRYSTALS-Dilithium.
- * FIPS-204 is implemented.
- *
- * Has similar internals to ML-KEM, but their keys and params are different.
- * Check out [official site](https://www.pq-crystals.org/dilithium/index.shtml),
- * [repo](https://github.com/pq-crystals/dilithium).
- * @module
- */
-
 // Constants
 const N = 256;
 // 2**23 − 2**13 + 1, 23 bits: multiply will be 46. We have enough precision in JS to avoid bigints
@@ -37,7 +36,8 @@ const GAMMA2_2 = Math.floor((Q - 1) / 32) | 0;
 
 type XofGet = ReturnType<ReturnType<XOF>['get']>;
 
-type Param = {
+/** Various lattice params. */
+export type DSAParam = {
   K: number;
   L: number;
   D: number;
@@ -49,7 +49,7 @@ type Param = {
 };
 /** Internal params for different versions of ML-DSA  */
 // prettier-ignore
-export const PARAMS: Record<string, Param> = {
+export const PARAMS: Record<string, DSAParam> = {
   2: { K: 4, L: 4, D, GAMMA1: 2 ** 17, GAMMA2: GAMMA2_1, TAU: 39, ETA: 2, OMEGA: 80 },
   3: { K: 6, L: 5, D, GAMMA1: 2 ** 19, GAMMA2: GAMMA2_2, TAU: 49, ETA: 4, OMEGA: 55 },
   5: { K: 8, L: 7, D, GAMMA1: 2 ** 19, GAMMA2: GAMMA2_2, TAU: 60, ETA: 2, OMEGA: 75 },

diff --git a/src/ml-kem.ts b/src/ml-kem.ts
@@ -1,17 +1,3 @@
-/*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
-import { sha3_256, sha3_512, shake256 } from '@noble/hashes/sha3';
-import { u32, wrapConstructor, wrapConstructorWithOpts } from '@noble/hashes/utils';
-import { genCrystals, XOF, XOF128 } from './_crystals.js';
-import {
-  Coder,
-  cleanBytes,
-  ensureBytes,
-  equalBytes,
-  randomBytes,
-  splitCoder,
-  vecCoder,
-} from './utils.js';
-
 /**
  * Module Lattice-based Key Encapsulation Mechanism (ML-KEM). A.k.a. CRYSTALS-Kyber.
  * FIPS-203 is implemented.
@@ -33,6 +19,19 @@ import {
  * [spec](https://datatracker.ietf.org/doc/draft-cfrg-schwabe-kyber/).
  * @module
  */
+/*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
+import { sha3_256, sha3_512, shake256 } from '@noble/hashes/sha3';
+import { u32, wrapConstructor, wrapConstructorWithOpts } from '@noble/hashes/utils';
+import { genCrystals, XOF, XOF128 } from './_crystals.js';
+import {
+  Coder,
+  cleanBytes,
+  ensureBytes,
+  equalBytes,
+  randomBytes,
+  splitCoder,
+  vecCoder,
+} from './utils.js';
 
 /** Key encapsulation mechanism interface */
 export type KEM = {
@@ -67,7 +66,7 @@ const { mod, nttZetas, NTT, bitsCoder } = genCrystals({
 });
 
 /** FIPS 203: 7. Parameter Sets */
-type ParameterSet = {
+export type KEMParam = {
   N: number;
   K: number;
   Q: number;
@@ -79,7 +78,7 @@ type ParameterSet = {
 };
 /** Internal params of ML-KEM versions */
 // prettier-ignore
-export const PARAMS: Record<string, ParameterSet> = {
+export const PARAMS: Record<string, KEMParam> = {
   512: { N, Q, K: 2, ETA1: 3, ETA2: 2, du: 10, dv: 4, RBGstrength: 128 },
   768: { N, Q, K: 3, ETA1: 2, ETA2: 2, du: 10, dv: 4, RBGstrength: 192 },
   1024:{ N, Q, K: 4, ETA1: 2, ETA2: 2, du: 11, dv: 5, RBGstrength: 256 },
@@ -142,7 +141,7 @@ type Hash = ReturnType<typeof wrapConstructor>;
 type HashWOpts = ReturnType<typeof wrapConstructorWithOpts>;
 type XofGet = ReturnType<ReturnType<XOF>['get']>;
 
-type KyberOpts = ParameterSet & {
+type KyberOpts = KEMParam & {
   HASH256: Hash;
   HASH512: Hash;
   KDF: Hash | HashWOpts;

diff --git a/src/slh-dsa.ts b/src/slh-dsa.ts
@@ -1,19 +1,3 @@
-/*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
-import { HMAC } from '@noble/hashes/hmac';
-import { sha256, sha512 } from '@noble/hashes/sha2';
-import { shake256 } from '@noble/hashes/sha3';
-import { bytesToHex, hexToBytes, createView, concatBytes } from '@noble/hashes/utils';
-import {
-  Signer,
-  cleanBytes,
-  ensureBytes,
-  equalBytes,
-  getMask,
-  randomBytes,
-  splitCoder,
-  vecCoder,
-} from './utils.js';
-
 /**
  * StateLess Hash-based Digital Signature Standard (SLH-DSA). A.k.a. Sphincs+.
  * FIPS-205 (spec v3.1) is implemented.
@@ -42,6 +26,21 @@ import {
  * Check out [official site](https://sphincs.org) & [repo](https://github.com/sphincs/sphincsplus).
  * @module
  */
+/*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
+import { HMAC } from '@noble/hashes/hmac';
+import { sha256, sha512 } from '@noble/hashes/sha2';
+import { shake256 } from '@noble/hashes/sha3';
+import { bytesToHex, hexToBytes, createView, concatBytes } from '@noble/hashes/utils';
+import {
+  Signer,
+  cleanBytes,
+  ensureBytes,
+  equalBytes,
+  getMask,
+  randomBytes,
+  splitCoder,
+  vecCoder,
+} from './utils.js';
 
 /**
  * * N: Security parameter (in bytes). W: Winternitz parameter
@@ -62,6 +61,7 @@ export type SphincsHashOpts = {
   getContext: GetContext;
 };
 
+/** Winternitz signature params. */
 export const PARAMS: Record<string, SphincsOpts> = {
   '128f': { W: 16, N: 16, H: 66, D: 22, K: 33, A: 6 },
   '128s': { W: 16, N: 16, H: 63, D: 7, K: 14, A: 12 },
@@ -81,9 +81,10 @@ const enum AddressType {
   FORSPRF,
 }
 
+/** Address, byte array of size ADDR_BYTES */
 export type ADRS = Uint8Array;
 
-type Context = {
+export type Context = {
   PRFaddr: (addr: ADRS) => Uint8Array;
   PRFmsg: (skPRF: Uint8Array, random: Uint8Array, msg: Uint8Array) => Uint8Array;
   Hmsg: (R: Uint8Array, pk: Uint8Array, m: Uint8Array, outLen: number) => Uint8Array;
@@ -130,7 +131,7 @@ function getMaskBig(bits: number) {
   return (1n << BigInt(bits)) - 1n; // 4 -> 0b1111
 }
 
-type SphincsSigner = Signer & { seedLen: number };
+export type SphincsSigner = Signer & { seedLen: number };
 
 function gen(opts: SphincsOpts, hashOpts: SphincsHashOpts): SphincsSigner {
   const { N, W, H, D, K, A } = opts;

diff --git a/src/utils.ts b/src/utils.ts
@@ -1,3 +1,7 @@
+/**
+ * Utilities for hex, bytearray and number handling.
+ * @module
+ */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
 import { bytes as abytes } from '@noble/hashes/_assert';
 import { TypedArray, concatBytes, utf8ToBytes, randomBytes as randb } from '@noble/hashes/utils';