Hybrid post-quantum

@webbuf/aesgcm-mlkem

AES-256-GCM with ML-KEM-768 key encapsulation: post-quantum authenticated encryption

Install

npm install @webbuf/aesgcm-mlkem

Usage

import { aesgcmMlkemEncrypt, aesgcmMlkemDecrypt } from "@webbuf/aesgcm-mlkem";
import { mlKem768KeyPair } from "@webbuf/mlkem";
import { WebBuf } from "@webbuf/webbuf";

// Recipient generates a keypair (once, persistent)
const { encapsulationKey, decapsulationKey } = mlKem768KeyPair();

// Sender encrypts to recipient's encapsulationKey
const plaintext = WebBuf.fromUtf8("hello, post-quantum");
const ciphertext = aesgcmMlkemEncrypt(encapsulationKey, plaintext);

// Recipient decrypts using decapsulationKey
const recovered = aesgcmMlkemDecrypt(decapsulationKey, ciphertext);
// recovered.toUtf8() === "hello, post-quantum"

API reference (4 exports)

Constants

AESGCM_MLKEM

const

AESGCM_MLKEM: { readonly versionByte: 1; readonly kemCiphertextSize: 1088; readonly ivSize: 12; readonly tagSize: 16; readonly fixedOverhead: number; readonly hkdfInfo: "webbuf:aesgcm-mlkem v1"; }

Functions

_aesgcmMlkemEncryptDeterministic

function

Test/internal-only: encrypt with caller-supplied ML-KEM `m` and AES-GCM `iv`. Used by the KAT regression tests in `test/audit.test.ts` to assert byte-precise output against the captured fixtures from issue 0004 (empty AAD) and issue 0006 Experiment 2 (non-empty AAD). Application code should use `aesgcmMlkemEncrypt`.

_aesgcmMlkemEncryptDeterministic(recipientEncapKey: FixedBuf<1184>, plaintext: WebBuf, m: FixedBuf<32>, iv: FixedBuf<12>, aad?: WebBuf): WebBuf

aesgcmMlkemDecrypt

function

Decrypt an `@webbuf/aesgcm-mlkem` ciphertext using an ML-KEM-768 decapsulation key. Validates the version byte and minimum length, decapsulates the shared secret, derives the AES key, and decrypts. Throws if the version byte is wrong, the ciphertext is truncated, or AES-GCM authentication fails (which catches tampered KEM ciphertext, tampered AES ciphertext, tampered IV, AAD mismatch, or wrong recipient key).

aesgcmMlkemDecrypt(decapKey: FixedBuf<2400>, ciphertext: WebBuf, aad?: WebBuf): WebBuf

aesgcmMlkemEncrypt

function

Encrypt a message under an ML-KEM-768 encapsulation key. Generates fresh ML-KEM encapsulation randomness and a fresh AES-GCM IV per call via `FixedBuf.fromRandom`. Two calls with identical `recipientEncapKey` and `plaintext` produce different ciphertexts. `aad` is optional Additional Authenticated Data — bytes that are authenticated by the AES-GCM tag but not encrypted and not transmitted in the output. The recipient must supply the same `aad` bytes the sender used; any mismatch causes `aesgcmMlkemDecrypt` to throw. Empty AAD is the default and matches the original issue 0004 behavior. Output layout: [0..1) version byte (0x01) [1..1089) ML-KEM-768 ciphertext (1088 bytes) [1089..1101) AES-GCM IV (12 bytes) [1101..1101+N) AES-GCM ciphertext (N bytes; same length as plaintext) [1101+N..1117+N) AES-GCM authentication tag (16 bytes)

aesgcmMlkemEncrypt(recipientEncapKey: FixedBuf<1184>, plaintext: WebBuf, aad?: WebBuf): WebBuf