ecies/js

# eciesjs [](https://app.codacy.com/app/ecies/js) [](https://github.com/ecies/js) [](https://www.npmjs.com/package/eciesjs) [](https://npm-stat.link/eciesjs) [](https://bundlephobia.com/package/eciesjs@latest) [](https://github.com/ecies/js/actions) [](https://codecov.io/gh/ecies/js) 在 TypeScript 中实现 secp256k1/curve25519 的椭圆曲线集成加密方案。 这是 [eciespy](https://github.com/ecies/py) 的 JavaScript/TypeScript 版本，内置了类风格的 secp256k1/curve25519 [API](#privatekey)。 你可以在 [DETAILS.md](./DETAILS.md) 中了解详细信息。 ## 安装 ``` npm install eciesjs ``` 我们推荐使用最新的 JavaScript/TypeScript 运行时，尽管在某些旧版本上仍然可以安装。 本库支持多种平台（浏览器、Node、bun/deno、react native），请参阅[多平台支持](#multi-platform-support)。 关于安全性，请参阅[安全性](#security)。 ## 快速开始 ``` // example/runtime/quick-start.js import { PrivateKey, decrypt, encrypt } from "eciesjs"; const encoder = new TextEncoder(); const decoder = new TextDecoder(); const sk = new PrivateKey(); const data = encoder.encode("hello world🌍"); const decrypted = decrypt(sk.secret, encrypt(sk.publicKey.toBytes(), data)); console.log(decoder.decode(decrypted)); ``` 或者运行示例代码： ``` $ pnpm install && pnpm build && cd example/runtime && pnpm install && node quick-start.js hello world🌍 ``` 请参阅[配置](#configuration)以进行更细粒度的控制。 ## API ### `encrypt(receiverRawPK: string | Uint8Array, data: Uint8Array, config?: Config): Uint8Array` 参数： - `receiverRawPK` - 接收者的公钥，十六进制 `string` 或 `Uint8Array` - `data` - 待加密的数据 - `config` - 可选配置（默认为 `ECIES_CONFIG`） 返回值：`Uint8Array` ### `decrypt(receiverRawSK: string | Uint8Array, data: Uint8Array, config?: Config): Uint8Array` 参数： - `receiverRawSK` - 接收者的私钥，十六进制 `string` 或 `Uint8Array` - `data` - 待解密的数据 - `config` - 可选配置（默认为 `ECIES_CONFIG`） 返回值：`Uint8Array` ### `PrivateKey` - 方法 ``` static fromHex(hex: string, curve?: EllipticCurve): PrivateKey; constructor(secret?: Uint8Array, curve?: EllipticCurve); toHex(): string; encapsulate(pk: PublicKey, compressed?: boolean): Uint8Array; multiply(pk: PublicKey, compressed?: boolean): Uint8Array; equals(other: PrivateKey): boolean; ``` - 属性 ``` get secret(): Uint8Array; readonly publicKey: PublicKey; ``` ### `PublicKey` - 方法 ``` static fromHex(hex: string, curve?: EllipticCurve): PublicKey; constructor(data: Uint8Array, curve?: EllipticCurve); toBytes(compressed?: boolean): Uint8Array; toHex(compressed?: boolean): string; decapsulate(sk: PrivateKey, compressed?: boolean): Uint8Array; equals(other: PublicKey): boolean; ``` ## 配置 以下配置可用。 - 椭圆曲线：secp256k1 或 curve25519 (x25519/ed25519) - payload 中的临时密钥格式：压缩或非压缩（仅适用于 secp256k1） - 密钥派生中的共享椭圆曲线密钥格式：压缩或非压缩（仅适用于 secp256k1） - 对称加密算法：AES-256-GCM 或 XChaCha20-Poly1305 - 对称随机数（nonce）长度：12 或 16 字节（仅适用于 AES-256-GCM） 为了兼容性，请确保不同的应用共享相同的配置。 ``` export type EllipticCurve = "secp256k1" | "x25519" | "ed25519"; export type SymmetricAlgorithm = "aes-256-gcm" | "xchacha20"; export type NonceLength = 12 | 16; export class Config { ellipticCurve: EllipticCurve = "secp256k1"; isEphemeralKeyCompressed: boolean = false; isHkdfKeyCompressed: boolean = false; symmetricAlgorithm: SymmetricAlgorithm = "aes-256-gcm"; symmetricNonceLength: NonceLength = 16; } export const ECIES_CONFIG = new Config(); ``` ### 椭圆曲线配置 当 `ellipticCurve = "x25519"` 或 `ellipticCurve = "ed25519"` 时，将使用 x25519（基于 curve25519 的密钥交换函数）或 ed25519（基于 curve25519 的签名算法）代替 secp256k1 进行密钥交换。 在这种情况下，payload 将始终为：`32 字节 + 加密后内容`，而不受 `isEphemeralKeyCompressed` 的影响。 ### secp256k1 专属配置 当 `isEphemeralKeyCompressed = true` 时，payload 将为：`33 字节 + 加密后内容`，而不是 `65 字节 + 加密后内容`。 当 `isHkdfKeyCompressed = true` 时，hkdf 密钥将从 `临时公钥（压缩）+ 共享公钥（压缩）` 派生，而不是 `临时公钥（非压缩）+ 共享公钥（非压缩）`。 ### 对称加密配置 当 `symmetricAlgorithm = "xchacha20"` 时，明文数据将使用 XChaCha20-Poly1305 进行加密。 当 `symmetricNonceLength = 12` 时，AES-256-GCM 的随机数（nonce）将为 12 字节。无论 `symmetricNonceLength` 设置如何，XChaCha20-Poly1305 的随机数始终为 24 字节。 ### 我应该选择哪种配置？ 为了与其他 [ecies 库](https://github.com/orgs/ecies/repositories)兼容，建议从默认配置（搭配 AES-256-GCM 的 secp256k1）开始。 如果追求速度和安全性，请选择搭配 XChaCha20-Poly1305 的 x25519。 如果你确切知道自己在做什么，可以根据自己的意愿进行配置，或者使用本库构建你自己的 ecies 逻辑。 ## 多平台支持 | | 完全支持 | | ------------ | --------------- | | Node | ✅ | | Bun | ✅ | | Deno | ✅（见下文） | | 浏览器 | ✅ | | React Native | ✅ | 通过 [`@ecies/ciphers`](https://github.com/ecies/js-ciphers)，如果可用，将会选择 `node:crypto` 的 AES-256-GCM 和 XChaCha20-Poly1305 原生实现。 ### 浏览器 本库对浏览器友好，查看 [`example/browser`](./example/browser) 目录了解更多详情。你也可以查看[在线演示](https://js-demo.ecies.org/)。 如果你希望使用 WASM 版本直接在现代浏览器或某些区块链上运行，也可以尝试 [`ecies-wasm`](https://github.com/ecies/rs-wasm)。 ### Bun/Deno 关于 bun/deno，请参阅 [`example/runtime`](./example/runtime)。目前存在一些限制，在 [`@ecies/ciphers`](https://github.com/ecies/js-ciphers#known-limitations) 中提到： - bun 上会使用 `chacha20-poly1305` 的纯 JS 实现（由于缺乏实现，`node:crypto` 的 `chacha20-poly1305` 不可用）； - 你可能需要升级 deno 和/或使用 `--conditions deno` (>=2.4.0) 或 `--unstable-node-conditions deno`(>=2.3.6,<2.4.0) 运行。 ### React Native 请参阅 [React Native 演示](https://github.com/ecies/js-rn-demo)。 ## 安全性 为了降低安全风险，例如[供应链攻击](https://slowmist.medium.com/supply-chain-attack-on-ledger-connect-kit-analyzing-the-impact-and-preventive-measures-1005e39422fd)和零日[漏洞](https://github.com/advisories/GHSA-vjh7-7g9h-fjfh)，我们仅使用 `node:crypto` 以及以下经过审计的依赖项： - [noble-curves](https://github.com/paulmillr/noble-curves#security) - [noble-hashes](https://github.com/paulmillr/noble-hashes#security) - [noble-ciphers](https://github.com/paulmillr/noble-ciphers#security) 每次发布都是通过 GitHub Actions 构建的，并附带[出处证明](https://www.npmjs.com/package/eciesjs#provenance)。 本库也是完全可审计的。我们正在寻求资金，以进行专业的第三方安全审计，从而验证实现并识别潜在漏洞。 如果你依赖本库，或看重安全的开源密码学，请考虑[捐赠](https://github.com/sponsors/kigawas)以资助此次审计。 ## 更新日志 请参阅 [CHANGELOG.md](./CHANGELOG.md)。

标签：ECIES, secp256k1, TypeScript, 加密库, 安全插件, 密码学, 手动系统调用, 数据可视化, 椭圆曲线加密, 自动化攻击