hpke-js

hpke-js

For Node.js, you can install @hpke/core and other extensions via npm, yarn, pnpm or jsr:

# Using npm:
npm install @hpke/core
yarn add @hpke/core
pnpm install @hpke/core
# Using jsr:
npx jsr add @hpke/core
yarn add jsr:@hpke/core
pnpm add jsr:@hpke/core

Following extensions can be installed in the same manner:

• @hpke/chacha20poly1305
• @hpke/dhkem-x25519
• @hpke/dhkem-x448
• @hpke/dhkem-secp256k1
• @hpke/hybridkem-x-wing
• @hpke/ml-kem
• @hpke/hybridkem-x25519-kyber768 - deprecated

Then, you can use it as follows:

import {
  Aes128Gcm,
  CipherSuite,
  DhkemP256HkdfSha256,
  HkdfSha256,
} from "@hpke/core";

async function doHpke() {
  const suite = new CipherSuite({
    kem: new DhkemP256HkdfSha256(),
    kdf: new HkdfSha256(),
    aead: new Aes128Gcm(),
  });

  // A recipient generates a key pair.
  const rkp = await suite.kem.generateKeyPair();

  // A sender encrypts a message with the recipient public key.
  const sender = await suite.createSenderContext({
    recipientPublicKey: rkp.publicKey,
  });
  const ct = await sender.seal(new TextEncoder().encode("Hello world!"));

  // The recipient decrypts it.
  const recipient = await suite.createRecipientContext({
    recipientKey: rkp.privateKey,
    enc: sender.enc,
  });
  const pt = await recipient.open(ct);

  // Hello world!
  console.log(new TextDecoder().decode(pt));
}

try {
  doHpke();
} catch (e) {
  console.log("failed:", e.message);
}

Index

• Packages
• Supported Features
• Supported Environments
• Warnings and Restrictions
• Contributing
• References

Packages

HPKE Library

name	registry	description
@hpke/core		The HPKE core module implemented using only Web Cryptography API. It does not support the X448-based KEM and the ChaCha20/Poly1305 AEAD, but it has no external module dependencies. It’s small in size and tree-shaking friendly. README / samples
@hpke/chacha20poly1305		The HPKE module extension for ChaCha20Poly1305 AEAD. README / samples
@hpke/dhkem-x25519		The HPKE module extension for DHKEM(X25519, HKDF-SHA256). README / samples
@hpke/dhkem-x448		The HPKE module extension for DHKEM(X448, HKDF-SHA512). README / samples
hpke-js		The HPKE module supporting all of the ciphersuites defined in RFC9180, which consists of the above @hpke/{core, dhkem-x25519, dhkem-x448, chacha20poly1305} internally. README / samples
@hpke/hpke-js		The JSR version of the above hpke-js. README / samples
@hpke/ml-kem		EXPERIMENTAL AND NOT STANDARDIZED The HPKE module extension for ML-KEM. README / samples
@hpke/hybridkem-x-wing		EXPERIMENTAL AND NOT STANDARDIZED The HPKE module extension for X-Wing: general-purpose hybrid post-quantum KEM. README / samples
@hpke/hybridkem-x25519-kyber768 (deprelated)		EXPERIMENTAL AND NOT STANDARDIZED The HPKE module extension for the hybrid post-quantum KEM currently named X25519Kyber768Draft00. README / samples
@hpke/dhkem-secp256k1		EXPERIMENTAL AND NOT STANDARDIZED The HPKE module extension for DHKEM(secp256k1, HKDF-SHA256). README / samples

HPKE-based Protocol Implementations

name	registry	description
@hpke/ohttp		Oblivious HTTP (RFC 9458) client and server implementation using HPKE. README / samples
@hpke/cose		COSE-HPKE (draft-ietf-cose-hpke-27) implementation built on top of @hpke/core. README / samples
@hpke/jose		JOSE-HPKE (draft-ietf-jose-hpke-encrypt-22) encryption implementation built on top of @hpke/core. README / samples

Supported Features

HPKE Modes

[^auth]: Auth and AuthPSK require authenticated KEM support. ML-KEM, X-Wing and X25519-Kyber768 support only Base and PSK; requesting Auth or AuthPSK with these KEMs throws NotSupportedError.

Key Encapsulation Machanisms (KEMs)

Key Derivation Functions (KDFs)

• (*1) The HKDF functions built in @hpke/core can derive keys of the same length as the hash size. If you want to derive keys longer than the hash size, use hpke-js.

Authenticated Encryption with Associated Data (AEAD) Functions

Supported Environments

• Web Browser: Web Cryptography API supported browsers
  • Confirmed: Chrome, Firefox, Edge, Safari, Opera, Vivaldi, Brave
• Node.js: 16.x, 17.x, 18.x, 19.x, 20.x, 21.x, 22.x, 23.x, 24.x, 25.x, 26.x
• Deno: 2.x
• Cloudflare Workers
• bun: 0.x (0.6.0-), 1.x

Warnings and Restrictions

• Although this library has been passed the following test vectors, it has not been formally audited.
  • RFC9180 official test vectors provided on github.com/cfrg/draft-irtf-cfrg-hpke
  • ECDH/X25519/X448 test vectors provided on Project Wycheproof
• The upper limit of the AEAD sequence number is further rounded to JavaScript’s MAX_SAFE_INTEGER (2^53-1).

Contributing

We welcome all kind of contributions, filing issues, suggesting new features or sending PRs. Please see our CONTRIBUTING.md for detailed guidelines on:

• Development setup and prerequisites
• Available development tasks
• Code quality requirements
• Project structure
• Testing requirements
• Documentation guidelines

References

• W3C: Web Cryptography API
• W3C/WICG: Secure Curves in the Web Cryptography API
• W3C: Web Cryptography API Level 2
• IETF/HPKE-WG: Hybrid Public Key Encryption
• IETF/HPKE-WG: Post-Quantum and Post-Quantum/Traditional Hybrid Algorithms for HPKE
• IRTF/CFRG: RFC9180: Hybrid Public Key Encryption
• IRTF/CFRG: X25519Kyber768Draft00 hybrid post-quantum KEM for HPKE
• IRTF/CFRG: X-Wing: general-purpose hybrid post-quantum KEM
• IRTF/CFRG: Hybrid PQ/T Key Encapsulation Mechanisms
• IRTF/CFRG: Concrete Hybrid PQ/T Key Encapsulation Mechanisms
• IRTF/CFRG: Deterministic Nonce-less Hybrid Public Key Encryption
• IRTF/CFRG: SHA-3 for HPKE
• IETF: RFC 9458: Oblivious HTTP
• IETF: Chunked Oblivious HTTP Messages (draft-ietf-ohai-chunked-ohttp-08)
• IETF/COSE-WG: COSE-HPKE
• IETF/JOSE-WG: JOSE-HPKE