Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ecies/js-post-quantum/llms.txt
Use this file to discover all available pages before exploring further.
@ecies/post-quantum is a TypeScript library that implements a post-quantum Integrated Encryption Scheme (IES) by replacing the elliptic-curve key exchange used in classical ECIES with ML-KEM — the Module-Lattice Key Encapsulation Mechanism standardised in NIST FIPS 203. This page explains the cryptographic design behind the library, its key features, and how the KEM+DEM construction works end to end.
What is ECIES — and how does this differ?
Classical ECIES (Elliptic Curve Integrated Encryption Scheme) combines:- An elliptic-curve Diffie-Hellman key exchange to derive a shared secret, and
- A symmetric cipher (the Data Encapsulation Mechanism, or DEM) to encrypt the actual message using that shared secret.
@ecies/post-quantum follows the same KEM+DEM pattern but replaces the elliptic-curve step with ML-KEM. Because ML-KEM’s security is based on the hardness of lattice problems rather than the discrete logarithm problem, it remains secure against attacks from large-scale quantum computers — something classical elliptic-curve cryptography cannot guarantee.
What is ML-KEM?
ML-KEM (Module-Lattice Key Encapsulation Mechanism) is a key encapsulation mechanism standardised by NIST in FIPS 203. It is derived from Kyber and is designed to be secure against both classical and quantum adversaries. ML-KEM comes in three variants that trade off key and ciphertext size against security level:| Variant | PKE Ciphertext Size | Security Level |
|---|---|---|
| ML-KEM-512 | 768 bytes | NIST Level 1 |
| ML-KEM-768 | 1,088 bytes | NIST Level 3 (recommended) |
| ML-KEM-1024 | 1,568 bytes | NIST Level 5 |
@ecies/post-quantum uses it as DEFAULT_CONFIG.
Key features
Three ML-KEM variants
Choose between ML-KEM-512, ML-KEM-768, and ML-KEM-1024 to balance payload size against your required security level. The NIST-recommended ML-KEM-768 is the default.
Two symmetric ciphers
Encrypt messages with AES-256-GCM (hardware-accelerated on most platforms) or XChaCha20-Poly1305 (preferred for low-end devices or when you want to avoid AES entirely).
Multi-platform support
Runs on Node.js (≥16), Bun (≥1), Deno (≥2), modern browsers, and React Native — with the same API across all environments.
Native crypto acceleration
Uses
@ecies/ciphers to transparently select node:crypto’s native AES-256-GCM and XChaCha20-Poly1305 implementations when running on Node.js or Bun, falling back to pure-JS implementations elsewhere.How it works
@ecies/post-quantum uses the standard KEM+DEM construction:
Key Encapsulation (KEM)
The sender calls encapsulate with the receiver’s ML-KEM public key. This produces two outputs:
- A KEM ciphertext (
pke) that can be sent to the receiver. - A shared secret that only the holder of the matching private key can reproduce by calling
decapsulate.
encrypt function returns a single Uint8Array with the following layout:
pke ciphertext is 768, 1,088, or 1,568 bytes depending on the ML-KEM variant; the nonce is 12 or 16 bytes for AES-256-GCM (configurable) or 24 bytes for XChaCha20-Poly1305; and the AEAD tag is always 16 bytes.
On decryption, the receiver splits the payload at the known PKE size boundary, decapsulates the shared secret from the KEM ciphertext using their private key, and then decrypts the symmetric payload.
Get started
Quickstart
Install the library, generate a key pair, and encrypt your first message in under five minutes.