Skip to main content

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.

The @ecies/post-quantum library exposes a Config class that controls every tunable aspect of the encryption pipeline — which ML-KEM variant to use for key encapsulation, which AEAD cipher to use for payload encryption, and (for AES-256-GCM) how long the random nonce should be. Sensible defaults are provided out of the box through the exported DEFAULT_CONFIG singleton so that most applications need zero configuration to get started.

​
Type definitions

The three exported types and their defaults are: 
export type AsymmetricAlgorithm = "ml-kem-512" | "ml-kem-768" | "ml-kem-1024";
export type SymmetricAlgorithm = "aes-256-gcm" | "xchacha20";
export type NonceLength = 12 | 16; // aes-256-gcm only

export class Config {
  asymmetricAlgorithm: AsymmetricAlgorithm = "ml-kem-768";
  symmetricAlgorithm: SymmetricAlgorithm = "aes-256-gcm";
  symmetricNonceLength: NonceLength = 16; // aes-256-gcm only
}

export const DEFAULT_CONFIG = new Config();
DEFAULT_CONFIG is a module-level singleton created once at import time. It is ready to use immediately and reflects the NIST-recommended defaults.

​
Asymmetric algorithm

The asymmetricAlgorithm field selects which ML-KEM variant handles key encapsulation. All three variants are standardised in NIST FIPS 203 and resist quantum attacks, but they differ in ciphertext size and security level.
VariantPKE Ciphertext SizeSecurity LevelNotes
ml-kem-512768 bytesLevel 1 (≈ AES-128)Fastest, smallest overhead
ml-kem-7681088 bytesLevel 3 (≈ AES-192)NIST recommended default
ml-kem-10241568 bytesLevel 5 (≈ AES-256)Highest security margin
The PKE ciphertext is prepended to every encrypted payload, so choosing a higher-security variant increases the minimum output size by the corresponding number of bytes. To select a different variant, create a fresh Config instance and set asymmetricAlgorithm before calling encrypt or decrypt: 
import { Config, encrypt, decrypt } from "@ecies/post-quantum";

const config = new Config();
config.asymmetricAlgorithm = "ml-kem-1024";

const { secretKey, publicKey } = config.asymmetricModule.keygen();
const encrypted = encrypt(publicKey, data, config);
const decrypted = decrypt(secretKey, encrypted, config);
The config.asymmetricModule getter returns the correct @noble/post-quantum module (ml_kem512, ml_kem768, or ml_kem1024) for the selected variant, so key generation automatically produces the right key sizes.

​
Symmetric cipher

The symmetricAlgorithm field selects the AEAD cipher used to encrypt the actual payload. Both options provide authenticated encryption — confidentiality plus integrity. AES-256-GCM ("aes-256-gcm", default) is the standard choice for environments with hardware AES acceleration (AES-NI). Most modern desktop and server CPUs support AES-NI, making this the fastest option in those contexts. The symmetricNonceLength field applies only to this cipher. XChaCha20-Poly1305 ("xchacha20") is a constant-time stream cipher that does not rely on hardware acceleration. It is the better choice for low-end, embedded, or mobile devices that lack AES-NI, and for applications where timing-side-channel resistance is a priority. Its nonce is always 24 bytes and is not configurable. To switch to XChaCha20-Poly1305: 
import { Config, encrypt, decrypt } from "@ecies/post-quantum";

const config = new Config();
config.symmetricAlgorithm = "xchacha20";

const encrypted = encrypt(publicKey, data, config);
const decrypted = decrypt(secretKey, encrypted, config);

​
Nonce length (AES-256-GCM only)

When using AES-256-GCM, you can choose between a 12-byte and a 16-byte random nonce: 
import { Config, encrypt, decrypt } from "@ecies/post-quantum";

const config = new Config();
config.symmetricNonceLength = 12; // or 16 (default)

const encrypted = encrypt(publicKey, data, config);
const decrypted = decrypt(secretKey, encrypted, config);
The 12-byte nonce follows the most common GCM convention and is slightly more compact. The 16-byte nonce (the default) provides a larger nonce space, which reduces the probability of nonce collision when nonces are generated randomly — useful in high-volume or long-lived deployments.
symmetricNonceLength is ignored when symmetricAlgorithm is "xchacha20". XChaCha20-Poly1305 always uses a 24-byte nonce, which is large enough that random nonce collision is effectively impossible.

​
Using DEFAULT_CONFIG safely

DEFAULT_CONFIG is a shared singleton. Mutating it directly changes the configuration for every subsequent encrypt and decrypt call in the same process — including those made by other modules that imported the same singleton. 
// ⚠️ Mutating DEFAULT_CONFIG affects all future calls globally
import { DEFAULT_CONFIG, encrypt } from "@ecies/post-quantum";
DEFAULT_CONFIG.symmetricAlgorithm = "xchacha20"; // visible to all callers
For custom settings that should not bleed into other code, always create a new Config() instance: 
// ✅ Isolated config — no side-effects on other callers
import { Config, encrypt, decrypt } from "@ecies/post-quantum";

const config = new Config();
config.symmetricAlgorithm = "xchacha20";
config.asymmetricAlgorithm = "ml-kem-1024";

const encrypted = encrypt(publicKey, data, config);
const decrypted = decrypt(secretKey, encrypted, config);
The sender and receiver must use identical Config settings. If the asymmetric algorithm, symmetric cipher, or nonce length differs between the encrypting and decrypting side, decryption will fail. Agree on a configuration and share it out-of-band, or encode it alongside the ciphertext in your protocol.

Build docs developers (and LLMs) love

Get started for freeTalk to us