Composite ML-KEM (draft-ietf-lamps-pq-composite-kem)

Composite ML-KEM key establishment (draft-ietf-lamps-pq-composite-kem): a post-quantum ML-KEM hybridized with a traditional RSA-OAEP, ECDH, X25519, or X448, so the established shared secret stays secure as long as EITHER component is unbroken. pki.kem.encapsulate turns a recipient's composite public key into a 256-bit shared secret and a ciphertext; pki.kem.decapsulate recovers the same secret from that ciphertext and the composite private key. Each component KEM runs independently, and the two secrets are mixed through the SHA3-256 combiner that also binds the traditional ciphertext, the traditional public key, and a per-algorithm label. All twelve registered algorithms -- ML-KEM-768 and ML-KEM-1024 paired with RSA-OAEP 2048/3072/4096, ECDH over P-256/P-384/P-521 and brainpool, X25519, and X448 -- are verified against the draft Appendix G known-answer vectors.

pki.kem.decapsulate

since 0.6.6 stable
pki.kem.decapsulate(privateKey, ciphertext) -> Promise<Buffer>

Recover the 256-bit composite shared secret from a ciphertext. privateKey is the composite PKCS#8 (a OneAsymmetricKey DER Buffer or PRIVATE KEY PEM whose privateKeyAlgorithm is a composite ML-KEM OID and whose privateKey octets are the raw mlkemSeed || tradSK, draft sec. 4.2); ciphertext is the composite ciphertext (mlkemCT || tradCT, sec. 4.3). The ML-KEM half and the traditional half are decapsulated independently and combined with SHA3-256, so the secret is recovered only when both components agree. A malformed key or ciphertext, an unsupported algorithm, or a component decapsulation failure throws a typed KemError.

Example

async function example() {
  // requires: privatePkcs8Der -- the composite ML-KEM PKCS#8 private key (DER)
  // requires: ciphertext -- the composite KEM ciphertext received from the sender
  var secret = await pki.kem.decapsulate(privatePkcs8Der, ciphertext);   // 32-byte Buffer
}
example();

See also: pki.kem.encapsulate

References

pki.kem.encapsulate

since 0.6.6 stable
pki.kem.encapsulate(publicKey) -> Promise<{ sharedSecret: Buffer, ciphertext: Buffer }>

Establish a 256-bit shared secret for a recipient's composite ML-KEM public key. publicKey is the composite SubjectPublicKeyInfo (a DER Buffer or PUBLIC KEY PEM whose algorithm is a composite ML-KEM OID and whose subjectPublicKey octets are the raw mlkemEK || tradPK, draft sec. 4.1). Returns the sharedSecret (a 32-byte Buffer) and the ciphertext (mlkemCT || tradCT) to send to the recipient, who recovers the same secret with pki.kem.decapsulate. The ML-KEM and traditional component encapsulations run independently and are mixed through SHA3-256. A malformed or unsupported public key throws a typed KemError.

Example

async function example() {
  // requires: recipientSpkiDer -- the recipient's composite ML-KEM SubjectPublicKeyInfo (DER)
  var out = await pki.kem.encapsulate(recipientSpkiDer);
  out.sharedSecret.length === 32;   // send out.ciphertext to the recipient
}
example();

See also: pki.kem.decapsulate

References