# 2key-ratchet 中文文档

规范地址：https://npmcn.com/package/2key-ratchet/

版本：1\.0\.18
npm 元数据更新时间：2022-06-12T14:06:58.952Z
中文译文更新时间：2026-11-06T09:46:06.019Z
软件包许可：https://github\.com/PeculiarVentures/2key-ratchet/blob/master/LICENSE\.md

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

原始 npm 页面：https://www.npmjs.com/package/2key-ratchet
原文对照：https://npmcn.com/package/2key-ratchet/?lang=original
项目主页：https://github.com/PeculiarVentures/2key-ratchet#readme
源码仓库：https://github.com/PeculiarVentures/2key-ratchet

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

- 包体积（解压后）：120 kB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2017-05-25T11:22:19.400Z
- 最新版本发布：2020-05-25T13:37:04.641Z
- 近 30 天下载量：3519（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 0 个）

## 中文简介

2key-ratchet是使用WebCrypto在TypeScript中执行双Ratchet协议和X3DH.

## 安装

```sh
npm install 2key-ratchet
```

也可以使用：`pnpm add 2key-ratchet`、`yarn add 2key-ratchet`、`bun add 2key-ratchet`

## README

# 2个键盘

[![CircleCI](https://circleci.com/gh/PeculiarVentures/2key-ratchet.svg?style=svg&circle-token=29f5d4fefececbe5668f0c0858cc583e4e130765)](https://circleci.com/gh/PeculiarVentures/2key-ratchet) [![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat)](https://raw.githubusercontent.com/PeculiarVentures/2key-ratchet/master/LICENSE.md) [![Coverage Status](https://coveralls.io/repos/github/PeculiarVentures/2key-ratchet/badge.svg?branch=master)](https://coveralls.io/github/PeculiarVentures/2key-ratchet?branch=master) [![npm version](https://badge.fury.io/js/2key-ratchet.svg)](https://badge.fury.io/js/2key-ratchet)

[![NPM](https://nodei.co/npm/2key-ratchet.png)](https://nodei.co/npm/2key-ratchet/)

`2key-ratchet` 执行 [双键](https://whispersystems.org/docs/specifications/doubleratchet/) 礼宾和 [X3DH 密码](https://whispersystems.org/docs/specifications/x3dh) 使用 WebCrypto 键入脚本.

设计双层雷管协议和X3DH的目的是既提供前向保密又提供密码解密。 重要的是,有一些独立的 [安保审查](https://eprint.iacr.org/2016/1013.pdf) 最后,他们完成了这些目标.

“双重Ratchet”一词来源于协议如何确保每个消息都得到一个新的密钥: [Diffie-Hellman 键被“切开”](https://github.com/PeculiarVentures/2key-ratchet/blob/master/src/classes/asym_ratchet.ts) 以每个新信件交换方式进行; 发送/接收链条也是如此 [“对称-钥匙鼠标”](https://github.com/PeculiarVentures/2key-ratchet/blob/master/src/classes/sym_ratchet.ts)) (中文(简体) ).

有几个 [差异](https://github.com/PeculiarVentures/2key-ratchet/blob/master/DIFFERENCES.md) 原规格与 `2key-ratchet`最重要的是,正如它的名字所示,它使用 [二键](https://github.com/PeculiarVentures/2key-ratchet/blob/3538a1481b4249830549e1c1d251fb6a7a7512ec/src/classes/data/identity.ts#L18-L19),一个用于认证,另一个用于密钥交换。 另一个大个是使用secp256r1代替了曲线25519,因为浏览器尚未在本土支持这个曲线.

见 [智利](https://github.com/PeculiarVentures/2key-ratchet/blob/master/ARCHITECTURE.md) 文档以更好地了解库结构.

对于你可能使用的地方的想法 `2key-ratchet` 见 [萨尔瓦多](https://github.com/PeculiarVentures/2key-ratchet/blob/master/SCENARIOS.md) 文档.

关于许可证发放信息,见 [自由主义](https://github.com/PeculiarVentures/2key-ratchet/blob/master/LICENSE.md) 文档.

## 概览

### 身份钥匙

协议中的每个对等方都有 `IdentityKey`,这些是 sepp256r1 键。 这些密钥用来验证两者 `PreKeys` 财务报告和审定财务报表 `ExchangeKeys`。 。 。 . `IdentityKeys` 在X.509证书中与公用钥匙类似.

### 交换键

交换钥匙由 `2key-ratchet`,用来获取 `PreKeys`编辑 `ExchangeKey` 由同行签名 `IdentityKey`。 。 。 .

### 预键

单位 `2key-ratchet` a PreKey是一个有相关独特标识的secp256r1公钥. 这些 `PreKeys` 由 `IdentityKey`。 。 。 .

在第一次使用时,客户端生成一个签名的PreKey,以及大量未签名的PreKeys列表,并将其全部传送给服务器.

### 服务器

协议中的服务器是一个不值得信赖的实体,它只是存储预键进行检索,当对等点可能离线和无法到达时.

### 会议

双射纹协议面向会话. 同伴建立一个 `session` 互相交流,然后用于随后的所有交流。 这些会话可以保持开放并被重新使用,因为每条消息都用新的和独特的加密密钥加密.

## 大小和附属关系

| 名称 | 大小 | 说明 |
| --- | --- | --- |
| 2key-ratchet.js (英语) | 66个Kb | 没有外部模块的 UMD 模块 |

**注:** 您还必须导入 [tslib 语录](https://github.com/Microsoft/tslib) 财务报告和审定财务报表 [原生生物库](https://github.com/dcodeIO/ProtoBuf.js/#browsers) 用于浏览器.

## 说明

### 安装

```
npm install 2key-ratchet
```

### 使用量

包含 `2key-ratchet` 及其申请中的依赖性.

诺德杰斯:

```javascript
let DKeyRatchet = require("2key-ratchet");
```

布鲁斯:

```html
<script src="2key-ratchet.js"></script>
```

这个 `DKeyRatchet` 命名空间将永远在全球提供,并支持AMD加载器.

#### 生成身份密钥

第一步是创建"身份钥匙".

```javascript
let AliceID;
DKeyRatchet.Identity.create(16453, 1, 1)
    .then((id) => {
        AliceID = id;
    });
```

然后创建您的 PreKey 信件捆绑 :

```javascript
let bundle = new DKeyRatchet.PreKeyBundleProtocol();

bundle.identity.fill(AliceID)
    .then(() => {
        bundle.registrationId = AliceID.id;
        const preKey = AliceID.signedPreKeys[0];
        bundle.preKeySigned.id = 1;
        bundle.preKeySigned.key = preKey.publicKey;
        return bundle.preKeySigned.sign(AliceID.signingKey.privateKey);
    })
    .then(() => {
        return bundle.exportProto();
    })
    .then((ab) => {
        console.log(ab); // ArrayBuffer { byteLength: 374 }
    });
```

然后导入生成的 PreKey 信件捆绑 :

```javascript
DKeyRatchet.PreKeyBundleProtocol.importProto(ab)
    .then((bundle) => {
        // check signed prekey
        return bundle.preKeySigned.verify(AliceID.signingKey.publicKey);
    })
    .then((trusted) => {
        if (!trusted)
            throw new Error("Error: The PreKey is not trusted");
    })
```

#### 创建会话

您现在可以创建一个会话:

> 注:数据转换使用了模块 `pvtsutils`。 。 。 .

```javascript
DKeyRatchet.AsymmetricRatchet.create(BobID, bundle)
    .then((cipher) => {
        return cipher.encrypt(Convert.FromUtf8String("Hello world!"));
    })
    .then((preKeyMessage) => {
        return preKeyMessage.exportProto();
    })
    .then((BobMessage) => {
        console.log(BobMessage); // ArrayBuffer {byteLength: 408}
    });
```

在另一边你也会这么做:

```javascript
// Parse received bytes to proto
return DKeyRatchet.PreKeyMessageProtocol.importProto(BobMessage)
    .then((proto) => {
        return DKeyRatchet.AsymmetricRatchet.create(AliceID, proto)
            .then((cipher) => {
                return cipher.decrypt(proto.signedMessage);
            })
            .then((message) => {
                console.log(Convert.ToUtf8String(message)); // Hello world!
            });
    });
```

我们有一个 [完整的示例, 您可以在这里查看](https://github.com/PeculiarVentures/2key-ratchet/tree/master/src/examples)。 。 。 .

## 捐款

如果你发现2键滑板有问题,请打开一出新作. 特色要求也是受欢迎的.

拉出请求 — — 补丁、改进、新功能 — — 是一个了不起的帮助。 在提出任何重大拉动请求(例如执行新功能)之前,请先询问.

## 说明

布鲁斯·施奈尔(Bruce Schneier)出名地说"如果你认为密码学可以解决你的问题,那么你就不了解你的问题,也不懂密码". 要点是,使用2key-ratchet,或者任何其他"与计算机相关的"库,并不一定会让你的产品安全.

简而言之,制造安全产品比添加加密技术要多得多, [这是一本很棒的书 让你熟悉防御性思维](https://www.amazon.com/Threat-Modeling-Designing-Adam-Shostack/dp/1118809998)。 。 。 .

### 警告

虽然这个图书馆是基于 [双射纹算法](https://whispersystems.org/docs/specifications/doubleratchet/) 财务报告和审定财务报表 [x3DH 关键协议议定书](https://whispersystems.org/docs/specifications/x3dh/) 多个 [变动](https://github.com/PeculiarVentures/2key-ratchet/blob/master/DIFFERENCES.md) 可能改变它们提供的安全财产。 此时,你应当认为,在完成进一步的安保审查之前,这一执行是适当的.

## 鸣谢

Double Ratchet和X3DH都是由特雷弗·佩林和莫克西·马林斯派克设计的,我们感谢他们的工作.

## 相关

-   [信号信使协议的正式安全分析](https://eprint.iacr.org/2016/1013.pdf)
-   [安全文件分析](https://courses.csail.mit.edu/6.857/2016/files/36.pdf)
-   [网络加密 API](https://www.w3.org/TR/2016/PR-WebCryptoAPI-20161215/)
-   [X3DH 关键协议议定书](https://whispersystems.org/docs/specifications/x3dh/)
-   [双轨算法](https://whispersystems.org/docs/specifications/doubleratchet/)
-   [谷歌密钥透明](https://github.com/google/keytransparency)
-   [OMEMO 多端信件和对象加密](https://xmpp.org/extensions/xep-0384.html)
-   [矩阵OLM](https://matrix.org/docs/guides/e2e_implementation.html)
-   [双键和量子计算机](https://www.fredericjacobs.com/blog/2016/04/07/qc-axolotl/)
-   [加密卡特加密概览](https://crypto.cat/security.html)

## 常见问题

### 2key-ratchet 是什么？

2key-ratchet是使用WebCrypto在TypeScript中执行双Ratchet协议和X3DH\.

### 如何安装 2key-ratchet？

在项目目录运行 npm install 2key-ratchet，或使用 pnpm add / yarn add / bun add。

### 2key-ratchet 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### 2key-ratchet 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### 2key-ratchet 可以商用吗？

2key-ratchet 使用 https://github\.com/PeculiarVentures/2key-ratchet/blob/master/LICENSE\.md 许可。声明的许可为 https://github\.com/PeculiarVentures/2key-ratchet/blob/master/LICENSE\.md，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### 2key-ratchet 的下载量有多少？

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

### 2key-ratchet 还在维护吗？

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