dajiaji/hpke-js
GitHub: dajiaji/hpke-js
一个基于Web Cryptography API的TypeScript混合公钥加密库，用于在JavaScript环境中实现安全加密通信。
Stars: 117 | Forks: 14
hpke-js
一个基于 Web Cryptography API 构建的
模块化 TypeScript 混合公钥加密 (HPKE)
库及基于 HPKE 的协议套件
(OHTTP,
COSE-HPKE,
JOSE-HPKE)。
适用于 Web 浏览器、Node.js、Deno 及各种其他 JavaScript 运行时。
文档：[jsr.io](https://jsr.io/@hpke/core/doc) |
[页面（仅限最新版本）](https://dajiaji.github.io/hpke-js/core/docs/)
对于 Node.js，您可以通过 npm、yarn、pnpm 或 jsr 安装 `@hpke/core` 和其他扩展：
```
# 使用 npm：
npm install @hpke/core
yarn add @hpke/core
pnpm install @hpke/core
# 使用 jsr：
npx jsr add @hpke/core
yarn add jsr:@hpke/core
pnpm add jsr:@hpke/core
```
可以以相同方式安装以下扩展：
- `@hpke/chacha20poly1305`
- `@hpke/dhkem-x25519`
- `@hpke/dhkem-x448`
- `@hpke/dhkem-secp256k1`
- `@hpke/hybridkem-x-wing`
- `@hpke/ml-kem`
- `@hpke/hybridkem-x25519-kyber768` - 已弃用
然后，您可以按如下方式使用：
```
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);
}
```
## 目录
- [包](#packages)
- [支持的功能](#supported-features)
- [支持的环境](#supported-environments)
- [警告与限制](#warnings-and-restrictions)
- [贡献](#contributing)
- [参考](#references)
## 包
### HPKE 库
| 名称 | 注册表 | 描述 |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @hpke/core | [](https://www.npmjs.com/package/@hpke/core)[](https://jsr.io/@hpke/core) | 仅使用 [Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/) 实现的 HPKE 核心模块。它不支持基于 X448 的 KEM 和 ChaCha20/Poly1305 AEAD，但没有外部模块依赖。体积小，支持 tree-shaking。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/core/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/core/samples) | | @hpke/chacha20poly1305 | [](https://www.npmjs.com/package/@hpke/chacha20poly1305)
[](https://jsr.io/@hpke/chacha20poly1305) | 用于 ChaCha20Poly1305 AEAD 的 HPKE 模块扩展。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/chacha20poly1305/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/chacha20poly1305/samples) | | @hpke/dhkem-x25519 | [](https://www.npmjs.com/package/@hpke/dhkem-x25519)
[](https://jsr.io/@hpke/dhkem-x25519) | 用于 DHKEM(X25519, HKDF-SHA256) 的 HPKE 模块扩展。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/dhkem-x25519/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/dhkem-x25519/samples) | | @hpke/dhkem-x448 | [](https://www.npmjs.com/package/@hpke/dhkem-x448)
[](https://jsr.io/@hpke/dhkem-x448) | 用于 DHKEM(X448, HKDF-SHA512) 的 HPKE 模块扩展。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/dhkem-x448/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/dhkem-x448/samples) | | hpke-js | [](https://www.npmjs.com/package/hpke-js) | 支持 [RFC9180](https://datatracker.ietf.org/doc/html/rfc9180) 中定义的所有密码套件的 HPKE 模块，它内部由上述 @hpke/{core, dhkem-x25519, dhkem-x448, chacha20poly1305} 组成。
[README](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/samples) | | @hpke/hpke-js | [](https://jsr.io/@hpke/hpke-js) | 上述 `hpke-js` 的 JSR 版本。
[README](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/hpke-js/samples) | | @hpke/ml-kem | [](https://www.npmjs.com/package/@hpke/ml-kem)
[](https://jsr.io/@hpke/ml-kem) | **实验性且非标准化**
用于 [ML-KEM](https://datatracker.ietf.org/doc/draft-connolly-cfrg-hpke-mlkem/) 的 HPKE 模块扩展。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/ml-kem/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/ml-kem/samples) | | @hpke/hybridkem-x-wing | [](https://www.npmjs.com/package/@hpke/hybridkem-x-wing)
[](https://jsr.io/@hpke/hybridkem-x-wing) | **实验性且非标准化**
用于 [X-Wing：通用混合后量子 KEM](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/) 的 HPKE 模块扩展。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/hybridkem-x-wing/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/hybridkem-x-wing/samples) | | @hpke/hybridkem-x25519-kyber768（已弃用） | [](https://www.npmjs.com/package/@hpke/hybridkem-x25519-kyber768)
[](https://jsr.io/@hpke/hybridkem-x25519-kyber768) | **实验性且非标准化**
用于当前命名为 [X25519Kyber768Draft00](https://datatracker.ietf.org/doc/draft-westerbaan-cfrg-hpke-xyber768d00/) 的混合后量子 KEM 的 HPKE 模块扩展。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/hybridkem-x25519-kyber768/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/hybridkem-x25519-kyber768/samples) | | @hpke/dhkem-secp256k1 | [](https://www.npmjs.com/package/@hpke/dhkem-secp256k1)
[](https://jsr.io/@hpke/dhkem-secp256k1) | **实验性且非标准化**
用于 DHKEM(secp256k1, HKDF-SHA256) 的 HPKE 模块扩展。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/dhkem-secp256k1/README.md) / [示例](https://github.com/dajiaji/hpke-js/tree/main/packages/dhkem-secp256k1/samples) | ### 基于 HPKE 的协议实现（即将推出） | 名称 | 注册表 | 描述 | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @hpke/ohttp | - | 使用 HPKE 实现的 [Oblivious HTTP (RFC 9458)](https://datatracker.ietf.org/doc/rfc9458/) 客户端和服务器端。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/ohttp/README.md) | | @hpke/cose | - | 基于 @hpke/core 构建的 [COSE-HPKE (draft-ietf-cose-hpke)](https://datatracker.ietf.org/doc/draft-ietf-cose-hpke/) 实现。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/cose/README.md) | | @hpke/jose | - | 基于 @hpke/core 构建的 [JOSE-HPKE (draft-ietf-jose-hpke-encrypt)](https://datatracker.ietf.org/doc/draft-ietf-jose-hpke-encrypt/) 加密实现。
[README](https://github.com/dajiaji/hpke-js/blob/main/packages/jose/README.md) | ## 支持的功能 ### HPKE 模式 | 基础 | PSK | 认证 | 认证 PSK | | ---- | --- | ---- | ------- | | ✅ | ✅ | ✅ | ✅ | ### 密钥封装机制 (KEM) | KEM | 浏览器 | Node.js | Deno | Cloudflare
Workers | bun | | ------------------------------ | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | | DHKEM (P-256, HKDF-SHA256) | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | DHKEM (P-384, HKDF-SHA384) | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | DHKEM (P-521, HKDF-SHA512) | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | DHKEM (X25519, HKDF-SHA256) | ✅
hpke-js
@hpke/core
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/core
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/core
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/core
@hpke/dhkem-x25519 | ✅
hpke-js
@hpke/core
@hpke/dhkem-x25519 | | DHKEM (X448, HKDF-SHA512) | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | ✅
hpke-js
@hpke/dhkem-x448 | | ML-KEM-512 | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | | ML-KEM-768 | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | | ML-KEM-1024 | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | ✅
@hpke/ml-kem | | X-Wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | ✅
@hpke/hybridkem-x-wing | | 混合 KEM (X25519, Kyber768) | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | ✅
@hpke/hybridkem-x25519-kyber768 | | DHKEM (secp256k1, HKDF-SHA256) | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | ✅
@hpke/dhkem-secp256k1 | ### 密钥派生函数 (KDF) | KDF | 浏览器 | Node.js | Deno | Cloudflare
Workers | bun | | ----------- | -------------------------------- | -------------------------------- | -------------------------------- | -------------------------------- | -------------------------------- | | HKDF-SHA256 | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | | HKDF-SHA384 | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | | HKDF-SHA512 | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | ✅
hpke-js
@hpke/core(\*1) | - (\*1) `@hpke/core` 内置的 HKDF 函数可以派生与哈希大小相同长度的密钥。如果您想派生比哈希大小更长的密钥，请使用 `hpke-js`。 ### 带关联数据的认证加密 (AEAD) 函数 | AEAD | 浏览器 | Node.js | Deno | Cloudflare
Workers | bun | | -------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- | | AES-128-GCM | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | AES-256-GCM | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | | ChaCha20
Poly1305 | ✅
hpke-js
@hpke/chacha
20poly1305 | ✅
hpke-js
@hpke/chacha
20poly1305 | ✅
hpke-js
@hpke/chacha
20poly1305 | ✅
hpke-js
@hpke/chacha
20poly1305 | ✅
hpke-js
@hpke/chacha
20poly1305 | | 仅导出 | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ✅
hpke-js
@hpke/core | ## 支持的环境 - **Web 浏览器**：支持 [Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/) 的浏览器 - 已确认：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 - **Deno**：2.x - **Cloudflare Workers** - **bun**：0.x (0.6.0-), 1.x ## 警告与限制 - 尽管此库已通过以下测试向量，但尚未经过正式审计。 - [github.com/cfrg/draft-irtf-cfrg-hpke 提供的 RFC9180 官方测试向量](https://github.com/cfrg/draft-irtf-cfrg-hpke/blob/5f503c564da00b0687b3de75f1dfbdfc4079ad31/test-vectors.json) - [Project Wycheproof 提供的 ECDH/X25519/X448 测试向量](https://github.com/google/wycheproof) - AEAD 序列号的上限进一步四舍五入为 JavaScript 的 MAX\_SAFE\_INTEGER (`2^53-1`)。 ## 贡献 我们欢迎各种形式的贡献，包括提交 issue、建议新功能或发送 PR。有关详细指南，请参阅我们的 [CONTRIBUTING.md](CONTRIBUTING.md)： - 开发设置和前置条件 - 可用的开发任务 - 代码质量要求 - 项目结构 - 测试要求 - 文档指南 ## 参考 - [W3C: Web Cryptography API](https://www.w3.org/TR/2017/REC-WebCryptoAPI-20170126/) - [W3C/WICG: Web Cryptography API 中的安全曲线](https://wicg.github.io/webcrypto-secure-curves/) - [W3C: Web Cryptography API Level 2](https://w3c.github.io/webcrypto/) - [IETF/HPKE-WG: 混合公钥加密](https://datatracker.ietf.org/doc/draft-ietf-hpke-hpke/) - [IETF/HPKE-WG: 用于 HPKE 的后量子及后量子/传统混合算法](https://datatracker.ietf.org/doc/draft-ietf-hpke-pq) - [IRTF/CFRG: RFC9180: 混合公钥加密](https://datatracker.ietf.org/doc/html/rfc9180) - [IRTF/CFRG: 用于 HPKE 的 X25519Kyber768Draft00 混合后量子 KEM](https://datatracker.ietf.org/doc/html/draft-westerbaan-cfrg-hpke-xyber768d00) - [IRTF/CFRG: X-Wing：通用混合后量子 KEM](https://datatracker.ietf.org/doc/html/draft-connolly-cfrg-xwing-kem) - [IRTF/CFRG: 混合 PQ/T 密钥封装机制](https://datatracker.ietf.org/doc/draft-irtf-cfrg-hybrid-kems/) - [IRTF/CFRG: 具体的混合 PQ/T 密钥封装机制](https://datatracker.ietf.org/doc/draft-irtf-cfrg-concrete-hybrid-kems/) - [IRTF/CFRG: 确定性无 Nonce 的混合公钥加密](https://datatracker.ietf.org/doc/draft-irtf-cfrg-dnhpke/) - [IRTF/CFRG: 用于 HPKE 的 SHA-3](https://datatracker.ietf.org/doc/draft-connolly-cfrg-sha3-hpke/) - [IETF: RFC 9458: Oblivious HTTP](https://datatracker.ietf.org/doc/rfc9458/) - [IETF/COSE-WG: COSE-HPKE](https://datatracker.ietf.org/doc/draft-ietf-cose-hpke/) - [IETF/JOSE-WG: JOSE-HPKE](https://datatracker.ietf.org/doc/draft-ietf-jose-hpke-encrypt/)
标签：bun, CMS安全, COSE-HPKE, Deno, GNU通用公共许可证, HPKE, JavaScript, JOSE-HPKE, JSON 请求, MITM代理, Node.js, OHTTP, TypeScript, Web Cryptography API, 公钥加密, 内存取证对抗, 前端加密, 加密, 加密模块, 协议套件, 后端加密, 多平台支持, 安全协议, 安全插件, 密码学, 开源库, 手动系统调用, 搜索引擎爬虫, 数据可视化, 浏览器运行时, 混合公钥加密, 漏洞扫描器, 程序员工具, 网络安全, 自动化攻击, 隐私保护