# @digitalbazaar/minimal-cipher 中文文档

规范地址：https://npmcn.com/package/%40digitalbazaar/minimal-cipher/

版本：6\.1\.1
npm 元数据更新时间：2026-06-05T01:10:23.935Z
中文译文更新时间：2026-11-12T08:47:54.002Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40digitalbazaar/minimal-cipher
原文对照：https://npmcn.com/package/%40digitalbazaar/minimal-cipher/?lang=original
项目主页：https://github.com/digitalbazaar/minimal-cipher
源码仓库：https://github.com/digitalbazaar/minimal-cipher

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：65.2 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2021-03-12T16:29:39.731Z
- 最新版本发布：2026-06-05T01:10:23.807Z
- 近 30 天下载量：2971（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 2 个）

## 中文简介

最小加密/解密 JWE 库.

## 安装

```sh
npm install @digitalbazaar/minimal-cipher
```

也可以使用：`pnpm add @digitalbazaar/minimal-cipher`、`yarn add @digitalbazaar/minimal-cipher`、`bun add @digitalbazaar/minimal-cipher`

## README

# 最小密码 _(@digitalbazaar/最小密码)_

最小加密/解密 [津巴布韦](https://tools.ietf.org/html/rfc7516) 库,仅安全 algs,浏览器兼容.

## 目录

-   [警卫](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/#readme-security)
-   [背景情况](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/#readme-background)
-   [安装](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/#readme-install)
-   [使用量](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/#readme-usage)
-   [贡献](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/#readme-contribute)
-   [商业支助](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/#readme-commercial-support)
-   [许可证](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/#readme-license)

## 警卫

传统发展

## 背景情况

此库的每个版本最多只能提供两个算法 加密/解密:推荐的算法和符合FIPS的 算法。 加密 API 将期望用户指定“ 建议 ” 或"fips"作为要使用的算法版本,默认为"推荐".

如果FIPS的符合算法与推荐的相同 在一个特定版本的库中,然后该特定版本将 无论用户指定的"版本",都使用相同的算法.

这个版本的图书馆将使用"XChacha20-Poly1305"作为"推荐" 版本和256位"AES-GCM"作为FIPS兼容版本.

注: XSalsa20-Poly1305是一个AE(认证加密)算法,而不是 aEAD(经认证的加密和相关数据)算法,使其成为 与目前所需经费不符 [JWE( JOSE 网络加密) (JOSE 网络加密)](https://tools.ietf.org/html/rfc7516) `protected` 清晰的文本头.

这个库的API需要用于密钥加密密钥(KEKs)的接口. 这个 能够通过HSM/SSM使用不受过滤保护的关键材料 API,包括Web KMS(TODO:需要引用).

## 安装

该软件需要并支持维持的最近版本的Node.js和 浏览器. 更新可能会去除对旧的未维护的平台版本的支持. 请使用依赖性版本锁文件和测试以确保兼容性 与这个软件.

从国家预防机制安装:

https://www.npmjs.com/package/@digitalbazaar/minimal-cipher 页面存档备份,存于互联网档案馆

```sh
npm install @digitalbazaar/minimal-cipher
```

在当地安装(用于开发):

```sh
git clone https://github.com/digitalbazaar/minimal-cipher.git
cd minimal-cipher
npm install
```

## 使用量

选择一个 Cipher 接口(`recommended` 或者说 `fips`)并创建实例:

```js
import {Cipher} from '@digitalbazaar/minimal-cipher';

const cipher = new Cipher(); // by default {version: 'recommended'}
```

### 加密

要加密某物(创建密码,序列化为JWE JSON文档), 您需要:

-   要加密的一些数据( 字符串、 对象、 流)
-   密钥(称为关键协议密钥,简称KAK)

(你还需要一个) `keyResolver`以后再说吧

首先,集合您的密钥协议公用钥匙(你会与它们加密, 而预期的收件人会使用相应的私钥来解密.

列出 `recipients` (基本上,你正在列出 `id`页:1 用于加密/解密信件的公用/私用密钥配对 :

```js
// Retrieve them from config, a ledger, registry or back channel
const keyAgreementKey = await fetchFromSomewhere();

// or derive them from an existing Ed25519 signing key
import {X25519KeyAgreementKey2020} from '@digitalbazaar/x25519-key-agreement-key-2020';
import {Ed25519VerificationKey2020} from '@digitalbazaar/ed25519-verification-key-2020';
const keyPair = await Ed25519VerificationKey2020.generate();

const keyAgreementKey = X25519KeyPair.fromEd25519VerificationKey2020({keyPair});
// If the source key pair didn't have a controller set, don't forget to set one:
keyAgreementKey.controller = did; // The controller's DID
keyAgreementKey.id = `${did}#${keyAgreementKey.fingerprint()}`;

// or derive them from an authentication key extracted from DID Document
const didDoc = await veresDriver.get({did});
const authnKey = didDoc.getVerificationMethod({proofPurpose: 'authentication'});
const edKeyPair = await Ed25519VerificationKey2020.from(authnKey);
const keyPair = X25519KeyPair.fromEd25519VerificationKey2020({keyPair});

const recipient = {
  header: {
    kid: keyAgreementKey.id,
    alg: 'ECDH-ES+A256KW'
  }
}

const recipients = [recipient];
```

你也需要一个 `keyResolver`. 注意到 `recipients` 仅列出密钥ID, 不是钥匙本身。 A 类 `keyResolver` 是接受密钥ID的函数 并且决定相应的公用钥匙.

一些实例解析者:

```js
// Basic hardcoded key resolver; you already have the key material
const publicKeyNode = {
  '@context': 'https://w3id.org/security/suites/x25519-2020/v1',
  id: keyAgreementKey.id,
  type: 'X25519KeyAgreementKey2020',
  publicKeyMultibase: keyAgreementKey.publicKeyMultibase
};
const keyResolver = async () => publicKeyNode;
```

```js
// A more advanced resolver based on DID doc authentication keys
const keyResolver = async ({id}) => {
  // Use veres driver to fetch the authn key directly
  const keyPair = await Ed25519VerificationKey2020.from(await veresDriver.get({did: id}));
  // Convert authn key to key agreement key
  return X25519KeyPair.fromEd25519VerificationKey2020({keyPair});
}
```

```js
// Using did-veres-one driver as a resolver for did:v1:nym: DID keys
// TODO: Implement this
```

```js
// Using the did:key method driver as a key resolver
```

创建 JWE :

```js
// To encrypt a string or a Uint8Array
const data = 'plain text';
const jweDoc = await cipher.encrypt({data, recipients, keyResolver});

// To encrypt an object
const obj = {key: 'value'};
const jweDoc = await cipher.encryptObject({obj, recipients, keyResolver});
```

### 解密

使用私密文件解密 JWE JSON 文件 `keyAgreementKey`数字 :

```js
const data = await cipher.decrypt({jwe, keyAgreementKey});

const object = await cipher.decryptObject({jwe, keyAgreementKey});
```

描述所需的 KEK API : / 请检查url=值 (帮助) `id`, (中文(简体) ), `algorithm`, (中文(简体) ), `wrapKey({unwrappedKey})`,以及 `unwrapKey({wrappedKey})`

## 贡献

见 [贡献文件](https://github.com/digitalbazaar/bedrock/blob/master/CONTRIBUTING.md)来啊!

公关接受.

如果编辑 README, 请遵守 [标准读取](https://github.com/RichardLitt/standard-readme) 规格.

## 商业支助

该图书馆的商务支助可应下列请求提供: 数字集市: [支持@ digitalbazaar.com](mailto:support@digitalbazaar.com)

## 许可证

[新建 BSD 许可证( 3- clause)](https://npmcn.com/package/%40digitalbazaar/minimal-cipher/LICENSE) 数字集市

## 常见问题

### @digitalbazaar/minimal-cipher 是什么？

最小加密/解密 JWE 库\.

### 如何安装 @digitalbazaar/minimal-cipher？

在项目目录运行 npm install @digitalbazaar/minimal-cipher，或使用 pnpm add / yarn add / bun add。

### @digitalbazaar/minimal-cipher 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/digitalbazaar\_\_minimal-cipher 是否存在。

### @digitalbazaar/minimal-cipher 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @digitalbazaar/minimal-cipher 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @digitalbazaar/minimal-cipher 可以商用吗？

@digitalbazaar/minimal-cipher 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @digitalbazaar/minimal-cipher 的下载量有多少？

根据 npm 官方下载统计，@digitalbazaar/minimal-cipher 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,971 次，日均约 99 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @digitalbazaar/minimal-cipher 还在维护吗？

最新版本 6\.1\.1 发布于 2026/06/05（5 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 2 个；首次发布于 2021/03/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。