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.

This quickstart walks you through everything needed to perform your first post-quantum encryption with @ecies/post-quantum — from installation to generating a key pair, encrypting data, and decrypting it back to plaintext. All examples use the library’s defaults: ML-KEM-768 for key encapsulation and AES-256-GCM for symmetric encryption.
1

Install the package

Install @ecies/post-quantum from the npm registry:
npm
npm install @ecies/post-quantum
For pnpm, yarn, bun, and platform-specific setup (Deno, React Native, browser), see the Installation guide.
2

Generate a key pair

Key pairs are generated through the asymmetricModule exposed by DEFAULT_CONFIG. The keygen() method returns a secretKey and a publicKey as raw Uint8Array buffers.
import { DEFAULT_CONFIG } from "@ecies/post-quantum";

// Generate a new ML-KEM-768 key pair
const { secretKey, publicKey } = DEFAULT_CONFIG.asymmetricModule.keygen();

console.log("Public key length:", publicKey.length);  // 1184 bytes
console.log("Secret key length:", secretKey.length);  // 2400 bytes
The public key is shared with anyone who needs to encrypt messages to you. Keep the secret key private — it is the only thing that can decrypt messages encrypted to the corresponding public key.
3

Encrypt data

Call encrypt(publicKey, data) with the receiver’s public key and your plaintext as a Uint8Array. It returns a single Uint8Array that bundles the ML-KEM ciphertext, nonce, AEAD authentication tag, and encrypted payload:
pke ciphertext (1,088 bytes) || nonce (16 bytes) || AEAD tag (16 bytes) || ciphertext

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

const { secretKey, publicKey } = DEFAULT_CONFIG.asymmetricModule.keygen();

const encoder = new TextEncoder();
const plaintext = encoder.encode("hello world🌍");

// Returns Uint8Array: pke || nonce || tag || ciphertext
const encrypted = encrypt(publicKey, plaintext);

console.log("Encrypted length:", encrypted.length);
Both encrypt and decrypt operate on Uint8Array. Convert strings with TextEncoder / TextDecoder, or use Buffer.from(str) / Buffer.toString() in Node.js. Do not pass raw strings directly.
4

Decrypt data

Call decrypt(secretKey, encryptedData) with the receiver’s secret key and the full encrypted payload returned by encrypt. It returns the original plaintext as a Uint8Array.
import { decrypt, DEFAULT_CONFIG } from "@ecies/post-quantum";

// secretKey and encrypted come from the previous steps
const decrypted = decrypt(secretKey, encrypted);

const decoder = new TextDecoder();
console.log(decoder.decode(decrypted)); // "hello world🌍"
If the ciphertext has been tampered with, the underlying AEAD cipher will throw an authentication error before returning any data.

​
Full working example

The following self-contained example mirrors the canonical usage in example/runtime/main.js: 
import { DEFAULT_CONFIG, decrypt, encrypt } from "@ecies/post-quantum";

// Helpers for converting between strings and Uint8Array
const encoder = new TextEncoder();
const decoder = new TextDecoder();

const msg = encoder.encode("hello world🌍");

// 1. Generate an ML-KEM-768 key pair
const { secretKey, publicKey } = DEFAULT_CONFIG.asymmetricModule.keygen();

// 2. Encrypt: returns pke || nonce || tag || ciphertext as Uint8Array
const encrypted = encrypt(publicKey, msg);

// 3. Decrypt: recovers the original plaintext
const decrypted = decrypt(secretKey, encrypted);

console.log(decoder.decode(decrypted)); // "hello world🌍"
DEFAULT_CONFIG uses ML-KEM-768 for key encapsulation and AES-256-GCM with a 16-byte nonce for symmetric encryption. This is the NIST-recommended configuration and a sensible default for most applications.
Need a different security level or prefer XChaCha20-Poly1305 over AES-256-GCM? Pass a custom Config object as the third argument to encrypt and decrypt. See the configuration guide for all available options.

​
Next steps

Configuration

Learn how to switch between ML-KEM variants and symmetric ciphers by constructing a custom Config object.

API Reference

Full reference for encrypt, decrypt, Config, and DEFAULT_CONFIG, including all parameter types and return values.

Build docs developers (and LLMs) love

Get started for freeTalk to us