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 decrypt function is the counterpart to encrypt in @ecies/post-quantum. It takes an encrypted payload and the receiver’s ML-KEM secret key, recovers the shared secret through KEM decapsulation, and uses the AEAD cipher to authenticate and decrypt the symmetric ciphertext — returning the original plaintext bytes.

​
Function Signature

function decrypt(
  receiverSK: Uint8Array,
  data: Uint8Array,
  config?: Config
): Uint8Array

​
Parameters

​
receiverSK
Uint8Array
required
The receiver’s raw ML-KEM secret key. Obtain this from config.asymmetricModule.keygen().secretKey. Must correspond to the public key that was used during encrypt().
​
data
Uint8Array
required
The encrypted payload as returned by encrypt(). Expected layout:
pke_ciphertext (768 / 1088 / 1568 bytes)
  || nonce (12 / 16 / 24 bytes)
  || AEAD tag (16 bytes)
  || ciphertext
The function uses config.pkeSize to determine where to split the pke_ciphertext prefix from the rest of the payload.
​
config
Config
Configuration specifying algorithm choices. Defaults to DEFAULT_CONFIG. This value must exactly match the Config used during encrypt() — including asymmetricAlgorithm, symmetricAlgorithm, and symmetricNonceLength.
The config passed to decrypt must exactly match the config used during encrypt. Mismatched algorithms or nonce lengths will cause decryption failure, even if the key pair is correct.

​
Return Value

​
plaintext
Uint8Array
The original plaintext bytes that were passed to encrypt(). To recover a string, decode with new TextDecoder().decode(plaintext).

​
How It Works

  1. Splits data at byte offset config.pkeSize, extracting the pke_ciphertext prefix and the remaining symmetric payload.
  2. Calls config.asymmetricModule.decapsulate(pke, receiverSK) to recover sharedSecret.
  3. Uses sharedSecret to decrypt and authenticate the symmetric payload with the configured AEAD cipher.
  4. Returns the plaintext bytes on success, or throws on authentication failure.

​
Example

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

const { publicKey, secretKey } = DEFAULT_CONFIG.asymmetricModule.keygen();
const encoder = new TextEncoder();
const decoder = new TextDecoder();

const data = encoder.encode("secret message");
const encrypted = encrypt(publicKey, data);
const decrypted = decrypt(secretKey, encrypted);

console.log(decoder.decode(decrypted)); // "secret message"

​
Error Cases

  • Throws "Unsupported state or unable to authenticate data" (Node.js native crypto) or "invalid tag" (noble ciphers) when AEAD authentication fails. This can occur due to:
    • Wrong secret key (key mismatch between sender and receiver)
    • Tampered or corrupted ciphertext
    • Mismatched config between encrypt and decrypt calls
  • Throws Error: Unsupported asymmetric algorithm: <value> if config.asymmetricAlgorithm is set to an unrecognised value.
Authentication failures are detected and surfaced automatically by the AEAD cipher. You do not need to manually verify data integrity — a successful return from decrypt guarantees the ciphertext was encrypted with the corresponding public key and has not been tampered with.

Build docs developers (and LLMs) love

Get started for freeTalk to us