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

Table of Contents

• Overview
• Parameter Sets
• Init
• MlKem API
• KyberSuite
• Format enum
• Full example
• Error reference

ML-KEM (formerly Kyber) 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. KyberSuite 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 { kyberWasm }    from 'leviathan-crypto/kyber/embedded'
import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'

await init({ kyber: kyberWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })

Both kyber and sha3 are required. The kyber module handles polynomial arithmetic. The sha3 module provides the Keccak sponge operations used for key generation and encapsulation. If using KyberSuite 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/kyber subpath exports its own init function:

import { kyberInit } from 'leviathan-crypto/kyber'
import { kyberWasm } from 'leviathan-crypto/kyber/embedded'

await kyberInit(kyberWasm)

kyberInit(source) initializes only the kyber 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/kyber'

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. This prevents timing attacks on decapsulation failure. The shared secret simply won't match, causing authentication failure at the AEAD layer.

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 kyber 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 kyber module's own buffers.

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

interface MlKemLike {
    readonly params: KyberParams;
    encapsulate(ek: Uint8Array): KyberEncapsulation;
    decapsulate(dk: Uint8Array, c: Uint8Array): Uint8Array;
    keygen(): KyberKeyPair;
}

KyberSuite 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 { KyberSuite, MlKem768 } from 'leviathan-crypto/kyber'
import { XChaCha20Cipher }      from 'leviathan-crypto/chacha20'

const kem   = new MlKem768()
const suite = KyberSuite(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/kyber'

const suite = KyberSuite(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).

KyberSuite 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 { KyberSuite, MlKem768 } from 'leviathan-crypto/kyber'
import { XChaCha20Cipher }      from 'leviathan-crypto/chacha20'
import { kyberWasm }    from 'leviathan-crypto/kyber/embedded'
import { sha3Wasm }     from 'leviathan-crypto/sha3/embedded'
import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded'
import { sha2Wasm }     from 'leviathan-crypto/sha2/embedded'

await init({ kyber: kyberWasm, sha3: sha3Wasm, chacha20: chacha20Wasm, sha2: sha2Wasm })

const kem   = new MlKem768()
const suite = KyberSuite(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()