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 Config class controls every algorithm choice in @ecies/post-quantum. It lets you select the ML-KEM key encapsulation variant, the AEAD symmetric cipher, and the nonce length — and exposes computed getters that resolve these choices into concrete cryptographic modules and payload sizes used internally by encrypt() and decrypt().

​
Type Exports

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

​
Class Properties

​
asymmetricAlgorithm
AsymmetricAlgorithm
The ML-KEM variant to use for key encapsulation and decapsulation. Defaults to "ml-kem-768", which is the variant recommended by NIST FIPS 203.
ValueSecurity levelpkeSize
"ml-kem-512"Level 1768 bytes
"ml-kem-768"Level 3 (default)1088 bytes
"ml-kem-1024"Level 51568 bytes
​
symmetricAlgorithm
SymmetricAlgorithm
The AEAD cipher to use for symmetric encryption and authentication. Defaults to "aes-256-gcm".
ValueCipherNonce
"aes-256-gcm"AES-256-GCM12 or 16 bytes (see symmetricNonceLength)
"xchacha20"XChaCha20-Poly1305Always 24 bytes
​
symmetricNonceLength
NonceLength
Nonce length in bytes for AES-256-GCM. Defaults to 16. Accepted values are 12 or 16. This property is ignored when symmetricAlgorithm is "xchacha20" — XChaCha20-Poly1305 always uses a 24-byte nonce.

​
Computed Getters

​
asymmetricModule (read-only)

Returns the @noble/post-quantum ML-KEM module corresponding to the current asymmetricAlgorithm. The returned module exposes three methods:
MethodDescription
keygen()Generates a { publicKey, secretKey } key pair
encapsulate(publicKey)Returns { cipherText, sharedSecret }
decapsulate(cipherText, secretKey)Returns sharedSecret
Throws Error: Unsupported asymmetric algorithm: <value> if asymmetricAlgorithm is set to an unrecognised string.

​
pkeSize (read-only)

Returns the PKE ciphertext size in bytes for the current asymmetricAlgorithm. Used internally by decrypt() to split the leading pke_ciphertext from the rest of the encrypted payload.
asymmetricAlgorithmpkeSize
"ml-kem-512"768
"ml-kem-768"1088
"ml-kem-1024"1568

​
DEFAULT_CONFIG

DEFAULT_CONFIG is a pre-constructed, exported singleton Config instance with the following defaults:
PropertyDefault value
asymmetricAlgorithm"ml-kem-768"
symmetricAlgorithm"aes-256-gcm"
symmetricNonceLength16
It is the value used by encrypt() and decrypt() when no config argument is supplied.
DEFAULT_CONFIG is a mutable singleton. Assigning to its properties (e.g. DEFAULT_CONFIG.asymmetricAlgorithm = "ml-kem-1024") will affect every subsequent encrypt() and decrypt() call that relies on the default. For isolated or non-default configuration, always construct a fresh new Config() instance instead.

​
Usage Examples

import { DEFAULT_CONFIG, encrypt, decrypt } from "@ecies/post-quantum";

// DEFAULT_CONFIG uses ML-KEM-768 + AES-256-GCM (16-byte nonce)
const { publicKey, secretKey } = DEFAULT_CONFIG.asymmetricModule.keygen();

const data = new TextEncoder().encode("hello world");
const encrypted = encrypt(publicKey, data);
const decrypted = decrypt(secretKey, encrypted);

console.log(new TextDecoder().decode(decrypted)); // "hello world"

​
PKE Sizes Reference

The total payload overhead added by encrypt() is the sum of the PKE ciphertext, nonce, and AEAD authentication tag:
VariantpkeSizePayload overhead
ml-kem-512768 bytes768 + nonce + 16 bytes
ml-kem-7681088 bytes1088 + nonce + 16 bytes
ml-kem-10241568 bytes1568 + nonce + 16 bytes
Where nonce is 12 or 16 bytes for AES-256-GCM (controlled by symmetricNonceLength), or always 24 bytes for XChaCha20-Poly1305.

Build docs developers (and LLMs) love

Get started for freeTalk to us