diff --git a/src/_crystals.ts b/src/_crystals.ts index d284d7d..11216b9 100644 --- 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 index 0005b5a..7e63bb7 100644 --- 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['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 = { +export const PARAMS: Record = { 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 index f485a3d..11dbdd1 100644 --- 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 = { +export const PARAMS: Record = { 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; type HashWOpts = ReturnType; type XofGet = ReturnType['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 index 4e50507..05f531f 100644 --- 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 = { '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 index b2c5daa..caa384a 100644 --- 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';