noble-post-quantum

The noble-post-quantum library is a pure JavaScript implementation and does not claim constant-time execution. Because of the nature of JavaScript engines (JIT, garbage collection, bigint arithmetic), it is susceptible to timing side-channel attacks.

Key Security Considerations:

• ML-DSA: Signing uses rejection loops and conditional arithmetic that depends on secret-key state.
• Falcon: Signing uses data-dependent Gaussian and rejection sampling. Its timing posture is materially weaker than hardened native implementations. Avoid using deterministic or repeated signing randomness.
• Threat Model: These limitations are critical if an attacker can measure signing timing closely (e.g., via hostile co-tenancy or high-resolution local timing oracles).
• Recommendation: Use an isolated execution environment or a reviewed native/constant-time backend if side-channel resistance is a requirement of your threat model.

Supply Chain Security

• Commits: Signed with PGP keys.
• Releases: Published via token-less GitHub CI and Trusted Publishing; verify provenance logs.
• Dependencies: Minimized and strictly pinned. Core dependencies include noble-hashes, noble-curves, and noble-ciphers.

ML-KEM (Module Lattice-based Key Encapsulation Mechanism) is used to establish shared secrets. It is probabilistic and relies on a high-quality CSPRNG.

Important Security Notes:

• Unlike ECDH, decapsulation never throws an error; if the ciphertext was encrypted with a different key, it simply returns a different (unrelated) shared secret.
• Decapsulation follows an implicit-rejection structure.
• For deterministic testing or known-answer vectors, you can provide a 32-byte msg (the preimage of the shared secret) to encapsulate and a 64-byte seed to keygen. Otherwise, the library generates fresh randomness.

Available parameter sets:

• ml_kem512
• ml_kem768
• ml_kem1024

import { ml_kem512 } from '@noble/post-quantum/ml-kem.js';

// 1. Generate keys
const seed = new Uint8Array(ml_kem512.lengths.seed!); // 64 bytes
const { secretKey, publicKey } = ml_kem512.keygen(seed);

// 2. Encapsulate (generate shared secret and ciphertext)
const msg = new Uint8Array(ml_kem512.lengths.msgRand!); // 32 bytes
const { cipherText, sharedSecret } = ml_kem512.encapsulate(publicKey, msg);

// 3. Decapsulate (recover shared secret)
const recovered = ml_kem512.decapsulate(cipherText, secretKey);

// 4. Extract public key from secret key if needed
const publicKey2 = ml_kem512.getPublicKey(secretKey);

The webcrypto.ts module provides asynchronous wrappers for Key Encapsulation Mechanism (KEM) operations using the browser's built-in crypto.subtle API. This is useful for offloading lattice-based cryptography to the runtime's native implementation.

Supported Algorithms

• ml_kem512: ML-KEM-512
• ml_kem768: ML-KEM-768
• ml_kem1024: ML-KEM-1024
• ml_kem768_x25519: ML-KEM-768 + X25519 (X-Wing)

Key Concepts

• Deterministic Key Generation: If you provide a seed to keygen(), the resulting private key is the raw seed itself, not the expanded decapsulation key. This seed is compatible with the synchronous implementations' keygen(seed) method.
• Support Probing: Because WebCrypto's post-quantum algorithms are experimental, always call isSupported() before attempting operations to ensure the runtime implements the full required surface (key generation, encapsulation, and decapsulation).

import { ml_kem768 } from '@noble/post-quantum/webcrypto';

// 1. Check support
if (await ml_kem768.isSupported()) {
  // 2. Generate key pair
  const { secretKey, publicKey } = await ml_kem768.keygen();

  // 3. Encapsulate (Sender side)
  const { cipherText, sharedSecret: ssSender } = await ml_kem768.encapsulate(publicKey);

  // 4. Decapsulate (Recipient side)
  const ssRecipient = await ml_kem768.decapsulate(cipherText, secretKey);

  // ssSender === ssRecipient
}

ML-KEM is a lattice-based Key Encapsulation Mechanism (KEM) used to establish shared secrets.

Workflow:

1. Alice generates keys using keygen(seed) and sends the publicKey to Bob.
2. Bob uses encapsulate(publicKey) to generate a cipherText and a sharedSecret. Bob sends the cipherText to Alice.
3. Alice uses decapsulate(cipherText, secretKey) to derive the same sharedSecret.

Security Warning: Unlike ECDH, ML-KEM does not verify the identity of the sender. If a Man-in-the-Middle (MITM) provides a different ciphertext, decapsulate will not throw an error; it will simply return a different, incorrect shared secret.

WebCrypto Wrapper: For environments supporting the experimental WebCrypto API, use the async wrappers from @noble/post-quantum/webcrypto.js.

import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
import { randomBytes } from '@noble/post-quantum/utils.js';

const seed = randomBytes(64); // optional
const aliceKeys = ml_kem768.keygen(seed);
const { cipherText, sharedSecret: bobShared } = ml_kem768.encapsulate(aliceKeys.publicKey);
const aliceShared = ml_kem768.decapsulate(cipherText, aliceKeys.secretKey);