Post-quantum key encapsulation via ML-KEM (FIPS 203), plus MlKemSuite for hybrid KEM + symmetric AEAD with Seal, SealStream, and OpenStream.

Table of Contents

• Overview
• Parameter Sets
• Init
• MlKem API
• Wipe Discipline
• MlKemSuite
• Format enum
• Full example
• Error reference

ML-KEM (formerly ML-KEM) is a lattice-based key encapsulation mechanism standardized by NIST in FIPS 203. It provides key agreement that is secure against both classical and quantum adversaries.

This module provides three things. MlKem512, MlKem768, and MlKem1024 give you raw KEM operations: keygen, encapsulate, and decapsulate. Use these when you need direct access to the KEM. MlKemSuite is a factory that wraps a MlKemBase instance and an inner CipherSuite into a hybrid KEM + AEAD suite. Pass the result to Seal, SealStream, or OpenStream exactly as you would a symmetric cipher suite. All three parameter sets are verified against 240 NIST ACVP test vectors covering keygen, encap, decap, and implicit rejection.

Use MlKem768 for general-purpose applications. Use MlKem512 only if you have strict size or performance constraints. Use MlKem1024 for long-lived keys or high-assurance requirements.

import { init } from 'leviathan-crypto'
import { mlkemWasm }    from 'leviathan-crypto/mlkem/embedded'
import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'

await init({ mlkem: mlkemWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })

Both mlkem and sha3 are required. The mlkem module handles polynomial arithmetic. The sha3 module provides the Keccak sponge operations used for key generation and encapsulation. If using MlKemSuite with XChaCha20Cipher, also load chacha20 and sha2. With SerpentCipher, load serpent and sha2.

'keccak' is an alias for 'sha3'; same WASM binary, same instance slot. You can substitute keccakWasm and init({ keccak: keccakWasm }) anywhere sha3 is used. See init.md for details.

For tree-shakeable imports, the leviathan-crypto/mlkem subpath exports its own init function:

import { mlkemInit } from 'leviathan-crypto/mlkem'
import { mlkemWasm } from 'leviathan-crypto/mlkem/embedded'

await mlkemInit(mlkemWasm)

mlkemInit(source) initializes only the mlkem WASM binary. Note that ML-KEM classes additionally require sha3 (or keccak), both modules must be initialized before constructing any MlKem* instance.

All three classes share the same interface via MlKemBase. Construct the parameter set you want and call methods on the instance.

import { MlKem768 } from 'leviathan-crypto/mlkem'

const kem = new MlKem768()

Generates a fresh keypair using CSPRNG randomness.

const { encapsulationKey, decapsulationKey } = kem.keygen()
// encapsulationKey: Uint8Array, share with senders
// decapsulationKey: Uint8Array, keep secret, never transmit

The encapsulation key (ek) is the public key. Share it freely. The decapsulation key (dk) is the private key. Store it securely and never transmit it.

Deterministic keygen for testing. Both d and z must be 32 bytes. Do not use in production. Randomness must come from the CSPRNG.

Generates a shared secret and KEM ciphertext. The sender calls this.

const { ciphertext, sharedSecret } = kem.encapsulate(encapsulationKey)
// ciphertext:   Uint8Array, send to recipient alongside your message
// sharedSecret: Uint8Array (32 bytes), derive session keys from this

The shared secret is 32 bytes. It is never transmitted. The sender and recipient independently derive the same value.

Deterministic encapsulation. m is 32 bytes of randomness. KAT and testing only. Applies the same FIPS 203 §7.2 validation as encapsulate(ek).

Recovers the shared secret. The recipient calls this.

const sharedSecret = kem.decapsulate(decapsulationKey, ciphertext)
// sharedSecret: Uint8Array (32 bytes)

ML-KEM uses implicit rejection. If the ciphertext was tampered with, decapsulate returns a pseudorandom value derived from a secret random string rather than throwing. The FO transform is algorithm-level constant-time on the FO branch, so decapsulation failure is not distinguishable from success at the algorithm level. The shared secret simply won't match, causing authentication failure at the AEAD layer. See architecture.md §Where defense ends for hardware-level scope.

Returns true if ek is a well-formed encapsulation key per FIPS 203 §7.2. Checks length, then decodes the polyvec portion via polyvec_frombytes and scans every coefficient against c < Q = 3329.

if (!kem.checkEncapsulationKey(ek)) throw new Error('invalid ek')

Returns true if dk is a well-formed decapsulation key per FIPS 203 §7.3.

Wipes the WASM memory buffers. Call when done with the instance. Every public mlkem op (keygen, encapsulate, decapsulate, checkDecapsulationKey) already zeros sha3 scratch before returning, so sha3 linear memory carries no residue across an op boundary, dispose() handles the mlkem module's own buffers.

Structural interface implemented by MlKem512, MlKem768, and MlKem1024. Used by MlKemSuite and RatchetKeypair.decap(), pass any MlKem* instance where a MlKemLike is expected.

interface MlKemLike {
    readonly params: MlKemParams;
    encapsulate(ek: Uint8Array): MlKemEncapsulation;
    decapsulate(dk: Uint8Array, c: Uint8Array): Uint8Array;
    keygen(): MlKemKeyPair;
}

Every public ML-KEM operation (keygen, encapsulate, decapsulate) zeroes the mlkem WASM scratch regions that held secret or secret-derived bytes before returning. Without the wipe, residual state persists in linear memory until the next mlkem op or MlKem.dispose(), a window during which any other code holding the mlkem exports could read it.

The sha3 module is also wiped on every op via sx.wipeBuffers(). SHA-3 state and inputs/outputs would otherwise carry the K-PKE message, sponge intermediates, or G/J/H outputs across the call boundary.

The wiped regions are not equal-weight. Highest-severity residual first:

Public regions are intentionally skipped: PK_OFFSET, CT_OFFSET, POLYVEC_SLOT_0 (Â rows derived from public rho), POLYVEC_SLOT_3 / POLYVEC_SLOT_4 (t̂, t1, both published in pk).

kemKeypairDerand (keygen). Wipes the CPA sk slot, the keygen noise polyvecs, and the PRF buffer.

kemEncapsulateDerand. Wipes MSG_OFFSET, all six noise/intermediate polyvec and poly slots, and the PRF buffer.

kemDecapsulate. Wipes every region the encap path touches, plus SK_OFFSET (the CPA secret key restaged for re-encryption) and POLY_SLOT_0/1 (the conditional-select inputs K' and K_bar).

MlKem.dispose(). Wipes the entire mlkem mutable region. Call it when finished with the instance.

MlKemSuite combines a MlKemBase instance with an inner CipherSuite (XChaCha20Cipher or SerpentCipher) into a new object that satisfies the CipherSuite interface. Pass it anywhere you would pass a symmetric cipher suite.

import { MlKemSuite, MlKem768 } from 'leviathan-crypto/mlkem'
import { XChaCha20Cipher }      from 'leviathan-crypto/chacha20'

const kem   = new MlKem768()
const suite = MlKemSuite(kem, XChaCha20Cipher)

Delegates to kem.keygen(). Returns { encapsulationKey, decapsulationKey }.

const { encapsulationKey: ek, decapsulationKey: dk } = suite.keygen()

The sender encrypts with ek. The recipient decrypts with dk.

import { Seal } from 'leviathan-crypto'

// sender
const blob = Seal.encrypt(suite, ek, plaintext)

// recipient
const pt = Seal.decrypt(suite, dk, blob)

The blob wire format is preamble || ciphertext. For KEM suites the preamble includes the KEM ciphertext:

import { SealStream, OpenStream } from 'leviathan-crypto'

// sender
const sealer   = new SealStream(suite, ek)
const preamble = sealer.preamble       // 1108 bytes for MlKem768
const ct0      = sealer.push(chunk0)
const ctFinal  = sealer.finalize(lastChunk)

// recipient
const opener  = new OpenStream(suite, dk, preamble)
const pt0     = opener.pull(ct0)
const ptFinal = opener.finalize(ctFinal)

Any combination of parameter set and inner cipher works:

import { SerpentCipher } from 'leviathan-crypto/serpent'
import { MlKem1024 }     from 'leviathan-crypto/mlkem'

const suite = MlKemSuite(new MlKem1024(), SerpentCipher)
// formatEnum: 0x32 (ML-KEM-1024 + Serpent)
// preamble:   20 + 1568 = 1588 bytes

Generate a keypair once on the recipient side. Distribute ek to all senders and store dk securely. The decapsulation key never leaves the recipient. There is no session concept at this layer. Each Seal.encrypt call performs a fresh encapsulation with fresh randomness. Before trusting a received public key, validate it with kem.checkEncapsulationKey(ek).

MlKemSuite sets formatEnum = kemNibble | cipherNibble. This is encoded in byte 0 of the 20-byte header (bits 4-6 = KEM, bits 0-3 = cipher):

Symmetric suites have KEM bits = 0x00 and are backward compatible.

import { init, Seal }           from 'leviathan-crypto'
import { MlKemSuite, MlKem768 } from 'leviathan-crypto/mlkem'
import { XChaCha20Cipher }      from 'leviathan-crypto/chacha20'
import { mlkemWasm }    from 'leviathan-crypto/mlkem/embedded'
import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'

await init({ mlkem: mlkemWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })

const kem   = new MlKem768()
const suite = MlKemSuite(kem, XChaCha20Cipher)

// keygen, once, on the recipient side
const { encapsulationKey: ek, decapsulationKey: dk } = suite.keygen()
// store dk securely; distribute ek to senders

// sender, only needs ek
const message = new TextEncoder().encode('hello post-quantum world')
const blob    = Seal.encrypt(suite, ek, message)

// recipient, only needs dk
const plaintext = Seal.decrypt(suite, dk, blob)
console.log(new TextDecoder().decode(plaintext)) // 'hello post-quantum world'

kem.dispose()