@noble/post-quantum 0.6.1 → 0.7.0

package/README.md

@@ -3,22 +3,20 @@
 Auditable & minimal JS implementation of post-quantum public-key cryptography.
 
 - 🔒 Auditable
-- 🔻 Tree-shakeable: unused code is excluded from your builds
-- 🔍 Reliable: tests ensure correctness
+- 🪶 Minimal: 7KB (gzipped) ML-KEM, unused code is excluded from your builds
+- 🏎 Fast: hand-optimized for caveats of JS engines
+- 🔍 Reliable: ACVP / wycheproof tests ensure correctness
 - 🦾 ML-KEM & CRYSTALS-Kyber: lattice-based KEM from FIPS-203
 - 🔋 ML-DSA & CRYSTALS-Dilithium: lattice-based signatures from FIPS-204
 - 🐈 SLH-DSA & SPHINCS+: hash-based Winternitz signatures from FIPS-205
 - 🦅 Falcon: lattice-based signatures from Falcon Round 3
-- 🍡 Hybrid algorithms, combining classic & post-quantum: Concrete, XWing, KitchenSink
-- 🪶 16KB (gzipped) for everything, including bundled hashes & curves
-
-Take a glance at [GitHub Discussions](https://github.com/paulmillr/noble-post-quantum/discussions) for questions and support.
+- 🍡 Hybrid algorithms (combining classic & post-quantum)
 
 > [!IMPORTANT]
-> NIST published [IR 8547](https://nvlpubs.nist.gov/nistpubs/ir/2024/NIST.IR.8547.ipd.pdf),
-> prohibiting classical cryptography (RSA, DSA, ECDSA, ECDH) after 2035.
-> Australian ASD does same thing [after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
-> Take it into an account while designing a new cryptographic system.
+> NIST published draft [IR 8547](https://nvlpubs.nist.gov/nistpubs/ir/2024/NIST.IR.8547.ipd.pdf),
+> which proposes prohibiting classical cryptography (RSA, DSA, ECDSA, ECDH) after 2035.
+> Australia's ASD does the same [after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
+> Take this into account when designing new cryptographic systems.
 
 ### This library belongs to _noble_ cryptography
 
@@ -34,6 +32,7 @@ Take a glance at [GitHub Discussions](https://github.com/paulmillr/noble-post-qu
   [post-quantum](https://github.com/paulmillr/noble-post-quantum),
   5kb [secp256k1](https://github.com/paulmillr/noble-secp256k1) /
   [ed25519](https://github.com/paulmillr/noble-ed25519)
+- WASM version: [awasm-noble](https://github.com/paulmillr/awasm-noble)
 - [Check out the homepage](https://paulmillr.com/noble/)
   for reading resources, documentation, and apps built with noble
 
@@ -72,8 +71,7 @@ import {
 } from '@noble/post-quantum/falcon.js';
 import {
   ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
-  KitchenSink_ml_kem768_x25519, XWing,
-  QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
+  KitchenSink_ml_kem768_x25519, QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
 } from '@noble/post-quantum/hybrid.js';
 ```
 
@@ -84,16 +82,15 @@ import {
 - [hybrid: XWing, KitchenSink and others](#hybrid-xwing-kitchensink-and-others)
 - [What should I use?](#what-should-i-use)
 - [Security](#security)
-- [Speed](#speed)
 - [Contributing & testing](#contributing--testing)
+- [Speed](#speed)
 - [License](#license)
 
 ### ML-KEM / Kyber shared secrets
 
 ```ts
 import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
-import { randomBytes } from '@noble/post-quantum/utils.js';
-import { notDeepStrictEqual } from 'node:assert';
+import { equalBytes, randomBytes } from '@noble/post-quantum/utils.js';
 const seed = randomBytes(64); // seed is optional
 const aliceKeys = ml_kem768.keygen(seed);
 const { cipherText, sharedSecret: bobShared } = ml_kem768.encapsulate(aliceKeys.publicKey);
@@ -102,7 +99,7 @@ const aliceShared = ml_kem768.decapsulate(cipherText, aliceKeys.secretKey);
 // Warning: Can be MITM-ed
 const malloryKeys = ml_kem768.keygen();
 const malloryShared = ml_kem768.decapsulate(cipherText, malloryKeys.secretKey); // No error!
-notDeepStrictEqual(aliceShared, malloryShared); // Different key!
+console.log(equalBytes(aliceShared, malloryShared)); // false: different key!
 ```
 
 Lattice-based key encapsulation mechanism, defined in [FIPS-203](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf) ([website](https://www.pq-crystals.org/kyber/resources.shtml), [repo](https://github.com/pq-crystals/kyber)).
@@ -142,6 +139,27 @@ Lattice-based digital signature algorithm, defined in [FIPS-204](https://nvlpubs
 [repo](https://github.com/pq-crystals/dilithium)).
 The internals are similar to ML-KEM, but keys and params are different.
 
+`sign` / `verify` accept optional parameters:
+
+```ts
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js';
+import { sha512 } from '@noble/hashes/sha2.js';
+const keys = ml_dsa65.keygen();
+const msg = new TextEncoder().encode('hello noble');
+const ctx = new Uint8Array([1, 2, 3]);
+const sigCtx = ml_dsa65.sign(msg, keys.secretKey, { context: ctx }); // verify needs same context
+const sigDet = ml_dsa65.sign(msg, keys.secretKey, { extraEntropy: false }); // deterministic
+const hml = ml_dsa65.prehash(sha512); // HashML-DSA
+const sigPre = hml.sign(msg, keys.secretKey);
+const isValidPre = hml.verify(sigPre, msg, keys.publicKey);
+```
+
+- `context`: domain-separation byte string, up to 255 bytes; must match between `sign` and `verify`
+- `extraEntropy`: hedged-signing randomness. Default is 32 random bytes;
+  `false` produces deterministic signatures; custom 32-byte value is also allowed
+- `externalMu`: treat `msg` as the precomputed 64-byte message representative µ
+- `prehash(hash)`: pre-hash variant (HashML-DSA) from FIPS-204
+
 ### SLH-DSA / SPHINCS+ signatures
 
 ```ts
@@ -172,6 +190,9 @@ Hash-based digital signature algorithm, defined in [FIPS-205](https://nvlpubs.ni
 - 128 / 192 / 256: indicates security level in bits
 - s / f: indicates small vs fast trade-off
 
+`sign` / `verify` accept the same optional `context`, `extraEntropy` and `prehash(hash)`
+(HashSLH-DSA) parameters as ML-DSA. With `extraEntropy: false`, signing is deterministic.
+
 SLH-DSA is slow: see [benchmarks](#speed) for key size & speed.
 
 ### Falcon signatures
@@ -202,12 +223,12 @@ Lattice-based digital signature algorithm, submitted to NIST PQC Round 3 ([websi
 ```js
 import {
   ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
-  KitchenSink_ml_kem768_x25519, XWing,
+  KitchenSink_ml_kem768_x25519,
   QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
 } from '@noble/post-quantum/hybrid.js';
 ```
 
-Hybrid submodule combine post-quantum algorithms with elliptic curve cryptography:
+The hybrid submodule combines post-quantum algorithms with elliptic curve cryptography:
 
 - `ml_kem768_x25519`: ML-KEM-768 + X25519 (CG Framework, same as XWing)
 - `ml_kem768_p256`: ML-KEM-768 + P-256 (CG Framework)
@@ -225,25 +246,26 @@ The following spec drafts are matched:
 
 ### What should I use?
 
-|         | Speed  | Key size    | Sig size    | Created in | Popularized in | Post-quantum? |
-| ------- | ------ | ----------- | ----------- | ---------- | -------------- | ------------- |
-| RSA     | Normal | 256B - 2KB  | 256B - 2KB  | 1970s      | 1990s          | No            |
-| ECC     | Normal | 32 - 256B   | 48 - 128B   | 1980s      | 2010s          | No            |
-| ML-KEM  | Fast   | 1.6 - 31KB  | 1KB         | 1990s      | 2020s          | Yes           |
-| ML-DSA  | Normal | 1.3 - 2.5KB | 2.5 - 4.5KB | 1990s      | 2020s          | Yes           |
-| SLH-DSA | Slow   | 32 - 128B   | 17 - 50KB   | 1970s      | 2020s          | Yes           |
-| FN-DSA  | Slow   | 0.9 - 1.8KB | 0.6 - 1.2KB | 1990s      | 2020s          | Yes           |
+|         | Speed  | Key size    | Sig / CT size | Created in | Popularized in | Post-quantum? |
+| ------- | ------ | ----------- | ------------- | ---------- | -------------- | ------------- |
+| RSA     | Normal | 256B - 2KB  | 256B - 2KB    | 1970s      | 1990s          | No            |
+| ECC     | Normal | 32 - 256B   | 48 - 128B     | 1980s      | 2010s          | No            |
+| ML-KEM  | Fast   | 0.8 - 1.6KB | 0.8 - 1.6KB   | 1990s      | 2020s          | Yes           |
+| ML-DSA  | Normal | 1.3 - 2.5KB | 2.5 - 4.5KB   | 1990s      | 2020s          | Yes           |
+| SLH-DSA | Slow   | 32 - 128B   | 17 - 50KB     | 1970s      | 2020s          | Yes           |
+| FN-DSA  | Slow   | 0.9 - 1.8KB | 0.6 - 1.2KB   | 1990s      | 2020s          | Yes           |
 
-We suggest to use ECC + ML-KEM for key agreement, ECC + SLH-DSA for signatures.
+ML-KEM is a KEM, not a signature scheme: its last column is ciphertext (CT) size.
+We suggest using ECC + ML-KEM for key agreement, ECC + SLH-DSA for signatures.
 
 ML-KEM and ML-DSA are lattice-based. SLH-DSA is hash-based, which means it is built on top of older, more conservative primitives. NIST guidance for security levels:
 
 - Category 3 (~AES-192): ML-KEM-768, ML-DSA-65, SLH-DSA-192
 - Category 5 (~AES-256): ML-KEM-1024, ML-DSA-87, SLH-DSA-256
 
-NIST recommends to use cat-3+, while australian [ASD only allows cat-5 after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
+NIST recommends cat-3+, while Australian [ASD only allows cat-5 after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
 
-It's also useful to check out [NIST SP 800-131Ar3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar3.ipd.pdf)
+It's also useful to check out draft [NIST SP 800-131Ar3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar3.ipd.pdf)
 for "Transitioning the Use of Cryptographic Algorithms and Key Lengths".
 
 For [hashes](https://github.com/paulmillr/noble-hashes), use SHA512 or SHA3-512 (not SHA256); and for [ciphers](https://github.com/paulmillr/noble-ciphers) ensure AES-256 or ChaCha.
@@ -274,10 +296,11 @@ Keep in mind that even hardware versions ML-KEM [are vulnerable](https://eprint.
   - Version ranges are locked, and changes are checked with npm-diff.
 - **Dev dependencies** are excluded from end-user installs; they're only used for development and build steps.
 
-For this package, there are 2 dependencies; and a few dev dependencies:
+For this package, there are 3 dependencies; and a few dev dependencies:
 
 - [noble-hashes](https://github.com/paulmillr/noble-hashes) provides cryptographic hashing functionality, used internally in every algorithm
 - [noble-curves](https://github.com/paulmillr/noble-curves) provides elliptic curve cryptography for hybrid algorithms
+- [noble-ciphers](https://github.com/paulmillr/noble-ciphers) provides AES-CTR DRBG and ChaCha20, used internally in Falcon
 - jsbt is used for benchmarking / testing / build tooling and developed by the same author
 - prettier, fast-check and typescript are used for code quality / test generation / ts compilation
 
@@ -289,73 +312,63 @@ which is considered a cryptographically secure PRNG.
 
 Browsers have had weaknesses in the past - and could again - but implementing a userspace CSPRNG is even worse, as there’s no reliable userspace source of high-quality entropy.
 
-## Contributing & testing
-
-- `npm install && npm run build && npm test` will build the code and run tests.
-- `npm run lint` / `npm run format` will run linter / fix linter issues.
-- `npm run bench` will run benchmarks
-- `npm run build:release` will build single file
-
-Check out [github.com/paulmillr/guidelines](https://github.com/paulmillr/guidelines)
-for general coding practices and rules.
-
-See [paulmillr.com/noble](https://paulmillr.com/noble/)
-for useful resources, articles, documentation and demos
-related to the library.
-
 ## Speed
 
-> `npm run bench`
+> `npm run benchmark`
 
 Noble is the fastest JS implementation of post-quantum algorithms.
 
-Benchmarks on Apple M4 (**higher is better**):
+There is experimental [git branch](https://github.com/paulmillr/noble-post-quantum/tree/awasm),
+which uses WASM-based [awasm-noble](https://github.com/paulmillr/awasm-noble) for hashing.
+It has 80% faster ML-KEM, 30% faster ML-DSA, 2.3x faster SLH-DSA-SHA256, 15x faster SLH-DSA-SHAKE.
+Try it out.
 
-```
-# ML-KEM768
-keygen x 4,277 ops/sec @ 233μs/op
-encapsulate x 3,470 ops/sec @ 288μs/op
-decapsulate x 3,757 ops/sec @ 266μs/op
-# ML-DSA65
-keygen x 669 ops/sec @ 1ms/op
-sign x 271 ops/sec @ 3ms/op
-verify x 565 ops/sec @ 1ms/op
-# SLH-DSA SHA2 192f
-keygen x 235 ops/sec @ 4ms/op
-sign x 8 ops/sec @ 117ms/op
-verify x 159 ops/sec @ 6ms/op
-# Falcon512
-keygen x 14 ops/sec @ 66ms/op ± 11.01% (56ms..96ms)
-sign x 749 ops/sec @ 1ms/op
-verify x 2,160 ops/sec @ 462μs/op
-# Falcon1024
-keygen x 4 ops/sec @ 247ms/op ± 5.22% (234ms..266ms)
-sign x 343 ops/sec @ 2ms/op
-verify x 950 ops/sec @ 1ms/op
-```
+Benchmarks on Apple M4 (operations/sec, **higher is better**):
 
-Compared with pre-quantum:
-
-| OPs/sec           | Keygen | Signing | Verification | Shared secret |
+| Primitive         | Keygen | Signing | Verification | Shared secret |
 | ----------------- | ------ | ------- | ------------ | ------------- |
-| ECC x/ed25519     | 12648  | 6157    | 1255         | 1981          |
-| ML-KEM-768        | 4277   |         |              | 3757          |
-| ML-DSA65          | 669    | 271     | 565          |               |
-| SLH-DSA-SHA2-192f | 235    | 8       | 159          |               |
-| Falcon512         | 14     | 749     | 950          |               |
-
-SLH-DSA:
-
-|           | sig size | keygen | sign   | verify |
-| --------- | -------- | ------ | ------ | ------ |
-| sha2_128f | 18088    | 4ms    | 90ms   | 6ms    |
-| sha2_192f | 35664    | 6ms    | 160ms  | 9ms    |
-| sha2_256f | 49856    | 15ms   | 340ms  | 9ms    |
-| sha2_128s | 7856     | 260ms  | 2000ms | 2ms    |
-| sha2_192s | 16224    | 380ms  | 3800ms | 3ms    |
-| sha2_256s | 29792    | 250ms  | 3400ms | 4ms    |
-| shake_192f | 35664   | 21ms   | 553ms  | 29ms   |
-| shake_192s | 16224   | 260ms  | 2635ms | 2ms    |
+| ML-KEM-768        | 4661   |         |              | 4089          |
+| ML-DSA-65         | 719    | 294     | 610          |               |
+| Falcon512         | 14     | 749     | 2160         |               |
+| SLH-DSA-SHA2-192f | 321    | 11       | 198          |               |
+| Pre-quantum x/ed25519 | 12648  | 6157    | 1255         | 1981          |
+
+SLH-DSA (`s` variants have 2x shorter signatures; SHAKE is very slow):
+
+|            | keygen | sign   | verify |
+| ---------- | ------ | ------ | ------ |
+| sha2_128f  | 2ms    | 47ms   | 3ms    |
+| shake_128f | 10ms   | 237ms  | 14ms   |
+| sha2_192f  | 3.2ms  | 93ms   | 5.1ms  |
+| shake_192f | 15ms   | 396ms  | 21ms   |
+| sha2_256f  | 8.5ms  | 187ms  | 5.2ms  |
+| shake_256f | 40ms   | 813ms  | 22ms   |
+| sha2_128s  | 140ms  | 1068ms | 1.1ms  |
+| shake_128s | 673ms  | 5114ms | 5.2ms  |
+| sha2_192s  | 209ms  | 2114ms | 1.9ms  |
+| shake_192s | 974ms  | 8779ms | 7.1ms  |
+| sha2_256s  | 137ms  | 1941ms | 2.7ms  |
+| shake_256s | 645ms  | 7689ms | 11ms   |
+
+Key and signature sizes:
+
+| Variant | Public key | Secret key | Signature / Ciphertext |
+|---|---:|---:|---:|
+| ML-KEM-512 | 800 | 1632 | 768 |
+| ML-KEM-768 | 1184 | 2400 | 1088 |
+| ML-KEM-1024 | 1568 | 3168 | 1568 |
+| ML-DSA-44 | 1312 | 2560 | 2420 |
+| ML-DSA-65 | 1952 | 4032 | 3309 |
+| ML-DSA-87 | 2592 | 4896 | 4627 |
+| Falcon512 | 897 | 1281 | 666 |
+| Falcon1024 | 1793 | 2305 | 1280 |
+| SLH-DSA-128f | 32 | 64 | 17088 |
+| SLH-DSA-128s | 32 | 64 | 7856 |
+| SLH-DSA-192f | 48 | 96 | 35664 |
+| SLH-DSA-192s | 48 | 96 | 16224 |
+| SLH-DSA-256f | 64 | 128 | 49856 |
+| SLH-DSA-256s | 64 | 128 | 29792 |
+
 
 ## License
 

package/_crystals.d.ts

@@ -55,9 +55,15 @@ type Crystals<T extends TypedArray> = {
     smod: (a: number, modulo?: number) => number;
     nttZetas: T;
     NTT: {
-        /** Forward transform in place. Mutates and returns `r`. */
+        /**
+         * Forward transform in place. Mutates and returns `r`.
+         * Kyber-mode input coefficients must already use canonical representatives in `[0, Q)`.
+         */
         encode: (r: T) => T;
-        /** Inverse transform in place. Mutates and returns `r`. */
+        /**
+         * Inverse transform in place. Mutates and returns `r`.
+         * Kyber-mode input coefficients must already use canonical representatives in `[0, Q)`.
+         */
         decode: (r: T) => T;
     };
     bitsCoder: (d: number, c: Coder<number, number>) => BytesCoderLen<T>;
@@ -117,4 +123,3 @@ export declare const XOF128: TRet<XOF>;
  */
 export declare const XOF256: TRet<XOF>;
 export {};
-//# sourceMappingURL=_crystals.d.ts.map

package/_crystals.js

@@ -57,14 +57,34 @@ export const genCrystals = (opts) => {
     // Explained: https://electricdusk.com/ntt.html
     // Kyber has slightly different params, since there is no 512th primitive root of unity mod q,
     // only 256th primitive root of unity mod. Which also complicates MultiplyNTT.
-    const field = {
-        add: (a, b) => mod((a | 0) + (b | 0)) | 0,
-        sub: (a, b) => mod((a | 0) - (b | 0)) | 0,
-        mul: (a, b) => mod((a | 0) * (b | 0)) | 0,
-        inv: (_a) => {
-            throw new Error('not implemented');
-        },
+    const inv = (_a) => {
+        throw new Error('not implemented');
     };
+    // ML-KEM (Kyber) polynomials always enter the transform reduced to [0, Q), so add/sub only
+    // need one conditional correction instead of `%`; measured ~20% faster NTT there.
+    // ML-DSA keeps the generic mod() path on purpose: its first forward stage sees centered
+    // (negative) coefficients, and `sub(a, t)` can drop below -Q (t is a mul output in [0, Q)),
+    // so a single correction is not enough. A guarded fast path with mod() fallback was measured
+    // slower than plain `%` for the 23-bit Q (V8 int32 modulo is one div; the branches lose).
+    const field = isKyber
+        ? {
+            add: (a, b) => {
+                const r = (a + b) | 0;
+                return r >= Q ? (r - Q) | 0 : r;
+            },
+            sub: (a, b) => {
+                const r = (a - b) | 0;
+                return r < 0 ? (r + Q) | 0 : r;
+            },
+            mul: (a, b) => mod((a | 0) * (b | 0)) | 0,
+            inv,
+        }
+        : {
+            add: (a, b) => mod((a | 0) + (b | 0)) | 0,
+            sub: (a, b) => mod((a | 0) - (b | 0)) | 0,
+            mul: (a, b) => mod((a | 0) * (b | 0)) | 0,
+            inv,
+        };
     const nttOpts = {
         N,
         roots: nttZetas,
@@ -91,6 +111,13 @@ export const genCrystals = (opts) => {
     // Pack one little-endian `d`-bit word per coefficient, matching FIPS 203 ByteEncode /
     // ByteDecode and the FIPS 204 BitsToBytes-based polynomial packing helpers.
     const bitsCoder = (d, c) => {
+        // Validate the carry shape once: JS bitwise operations silently truncate wider accumulators.
+        for (let i = 0, bufLen = 0; i < N; i++) {
+            bufLen += d;
+            if (bufLen > 32)
+                getMask(bufLen);
+            bufLen %= 8;
+        }
         const mask = getMask(d);
         const bytesLen = d * (N / 8);
         return {
@@ -101,8 +128,10 @@ export const genCrystals = (opts) => {
                 for (let i = 0, buf = 0, bufLen = 0, pos = 0; i < poly.length; i++) {
                     buf |= (c.encode(poly[i]) & mask) << bufLen;
                     bufLen += d;
+                    // Take the low byte directly: `& 0xff` matches the previous getMask(bufLen) result
+                    // after Uint8Array truncation, without a validated function call per output byte.
                     for (; bufLen >= 8; bufLen -= 8, buf >>= 8)
-                        r[pos++] = buf & getMask(bufLen);
+                        r[pos++] = buf & 0xff;
                 }
                 return r;
             },
@@ -198,4 +227,3 @@ export const XOF128 = /* @__PURE__ */ createXofShake(shake128);
  * ```
  */
 export const XOF256 = /* @__PURE__ */ createXofShake(shake256);
-//# sourceMappingURL=_crystals.js.map

package/falcon.d.ts

@@ -81,4 +81,3 @@ export declare const falcon1024: TRet<Falcon>;
 export declare const falcon1024padded: TRet<Falcon>;
 export declare const __tests: any;
 export {};
-//# sourceMappingURL=falcon.d.ts.map