hpke

hpke is a JavaScript module for Hybrid Public Key Encryption (HPKE). This module is designed to work across various Web-interoperable runtimes including Node.js, browsers, Cloudflare Workers, Deno, Bun, and others.

💗 Help the project

Support from the community to continue maintaining and improving this module is welcome. If you find this module useful, please consider supporting this project by becoming a sponsor.

Dependencies: 0

hpke has no dependencies and it exports tree-shakeable ESM.

API Reference

hpke is distributed via npmjs.com, jsdelivr.com, and github.com.

Quick Start

import * as HPKE from 'hpke'

// 1. Choose a cipher suite
const suite = new HPKE.CipherSuite(
  HPKE.KEM_DHKEM_P256_HKDF_SHA256,
  HPKE.KDF_HKDF_SHA256,
  HPKE.AEAD_AES_128_GCM,
)

// 2. Generate recipient key pair
const recipient = await suite.GenerateKeyPair()

// 3. Encrypt a message
const plaintext = new TextEncoder().encode('Hello, World!')
const { encapsulatedSecret, ciphertext } = await suite.Seal(recipient.publicKey, plaintext)

// 4. Decrypt the message
const decrypted = await suite.Open(recipient.privateKey, encapsulatedSecret, ciphertext)
console.log(new TextDecoder().decode(decrypted)) // "Hello, World!"

Examples

For more advanced examples, including how to integrate external cryptographic libraries, see the examples directory.

Supported Runtimes

This module is compatible with JavaScript runtimes that support the utilized Web API globals and standard built-in objects or are Node.js.

The following runtimes are supported (this is not an exhaustive list):

Bun
Browsers
Cloudflare Workers
Deno
Electron
Node.js

Please note that some suites may not be available depending on the runtime used.

Supported Algorithms

Algorithm implementations exposed by this module are built on top of Web Cryptography (and its extensions, e.g. Secure Curves, Modern Algorithms). Runtimes implementing Web Cryptography are not required to support all of its algorithms and so not all algorithms are available in all runtimes.

This module is designed to be extensible, you can bring outside-built implementations of any KEM, KDF, or AEAD algorithm into any JavaScript runtime by conforming to the respective interfaces (KEM, KDF, or AEAD). This allows you to use alternative cryptographic libraries, native bindings, or specialized hardware implementations alongside the built-in Web Cryptography-based algorithms.

For extended algorithm support across all runtimes, see @panva/hpke-noble, which provides these KEM, KDF, and AEAD implementations using Paul Miller's @noble cryptographic libraries. These implementations can be freely mixed and matched with the built-in algorithms.

Below are the algorithms built in (based on Web Cryptography) and their runtime support matrix.

Key Encapsulation Mechanisms (KEM)

| Name | Node.js | Deno | Bun | CF Workers | Browsers | Extensibility | | :--------------------------------------------- | :-----: | :--: | :-: | :--------: | :----------: | :---------------: | | DHKEM(P-256, HKDF-SHA256) 0x0010 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | DHKEM(P-384, HKDF-SHA384) 0x0011 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | DHKEM(P-521, HKDF-SHA512) 0x0012 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | DHKEM(X25519, HKDF-SHA256) 0x0020 | ✓ | ✓ | | ✓ | ✓ | ✓ | | DHKEM(X448, HKDF-SHA512) 0x0021 | ✓ | | | | | ✓ | | ML-KEM-512 0x0040 | ✓ | | | | | ✓ | | ML-KEM-768 0x0041 | ✓ | | | | | ✓ | | ML-KEM-1024 0x0042 | ✓ | | | | | ✓ | | MLKEM768-P256 0x0050 | ✓ | | | | | ✓ | | MLKEM768-X25519 0x647a | ✓ | | | | | ✓ | | MLKEM1024-P384 0x0051 | ✓ | | | | | ✓ |

Key Derivation Functions (KDF)

| Name | Node.js | Deno | Bun | CF Workers | Browsers | Extensibility | | :-------------------------------- | :-----: | :--: | :-: | :--------: | :----------: | :---------------: | | HKDF-SHA256 0x0001 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | HKDF-SHA384 0x0002 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | HKDF-SHA512 0x0003 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | SHAKE128 0x0010 | ✓ | | | | | ✓ | | SHAKE256 0x0011 | ✓ | | | | | ✓ | | TurboSHAKE128 0x0012 | ✓ | | | | | ✓ | | TurboSHAKE256 0x0013 | ✓ | | | | | ✓ |

Authenticated Encryption (AEAD)

| Name | Node.js | Deno | Bun | CF Workers | Browsers | Extensibility | | :----------------------------------- | :-----: | :--: | :-: | :--------: | :----------: | :---------------: | | AES-128-GCM 0x0001 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | AES-256-GCM 0x0002 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | ChaCha20Poly1305 0x0003 | ✓ | | | | | ✓ |

Specifications

The algorithm implementations are being tested using test vectors from their respective specifications.

Supported Versions

| Version | Security Fixes 🔑 | Other Bug Fixes 🐞 | New Features ⭐ | | ----------------------------------------------- | ----------------- | ------------------ | --------------- | | v1.x | Security Policy | ✓ | ✓ |

Hpke

Install / Use

README