Skip to content

Commit 5ee421c

Browse files
SheepChefSheepChef
committed
Update Doc and test.
1 parent a9cd5e2 commit 5ee421c

5 files changed

Lines changed: 124 additions & 33 deletions

File tree

‎JavyInputAppendix.js‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,8 @@
2525
"mode":"", // ENCRYPT | DECRYPT | AUTO // AUTO 仅在 method 指定 OLD 时合法
2626
"key":"", // 加密密钥，一个字符串 //如果缺省，自动使用默认值
2727
"q":bool, // OLD模式下，决定是否添加标志位
28-
"WenyanConfig":{ //文言文生成配置，解密时可以缺省。
29-
"PunctuationMark": bool;// 指定是否为密文添加标点符号，默认 true/添加;
30-
"RandomIndex":number, // 仅WENYAN模式下需要：算法的随机程度，越大随机性越强，默认 50，最大100，超过100将会出错;
31-
"PianwenMode":bool, // 仅WENYAN模式下需要：尽可能使用对仗的骈文句式; 与逻辑句式冲突
32-
"LogicMode":bool, // 仅WENYAN模式下需要：尽可能使用逻辑句式; 与骈文句式冲突
33-
"Traditional":bool, // 仅WENYAN模式下需要：输出繁体中文。
34-
},
28+
"WenyanConfig":{...}, //文言文生成配置，详情见JavaScript接口定义。
29+
"AdvancedEncConfig":{...} //高级加密配置，详情见JavaScript接口定义。
3530
}
3631
3732
*/

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -216,11 +216,12 @@ AES 加密密钥和转轮密钥是同一个，均采用哈希值。
216216
以下是本项目的依赖项：
217217

218218
- [**Unishox2**](https://github.com/siara-cc/Unishox2) 短字符串压缩实现 _©Siara-cc_, **Apache-2.0** License.
219-
- [**crypto-js**](https://github.com/brix/crypto-js) AES加密实现 _©Jeff Mott/Evan Vosberg_, **MIT** License.
219+
- [**crypto-js**](https://github.com/brix/crypto-js) 加密算法实现 _©Jeff Mott/Evan Vosberg_, **MIT** License.
220220
- [**pako**](https://github.com/nodeca/pako) GZIP压缩实现 _©Vitaly Puzrin/Andrei Tuputcyn_, **MIT** License.
221221
- [**js-base64**](https://github.com/dankogai/js-base64) Base64编码工具实现 _©Dan Kogai_, **BSD-3-Clause** License.
222222
- [**mersenne-twister**](https://github.com/boo1ean/mersenne-twister) 梅森旋转算法实现 _©Makoto Matsumoto/Takuji Nishimura_, **BSD-3-Clause** License.
223223
- [**opencc-js**](https://github.com/nk2028/opencc-js) 简繁体转换实现 _©nk2028_, **MIT** License.
224+
- [**otplib**](https://github.com/yeojz/otplib) TOTP 实现 _©Gerald Yeo_, **MIT** License.
224225

225226
本项目许可证与所有依赖项的许可证兼容。
226227

‎docs/document/js-deploy.md‎

Lines changed: 85 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,9 @@ let Abra = new Abracadabra(InputMode, OutputMode);
4444
使用`Uint8Array`作为输入/输出方式，魔曰可以加解密任意二进制(图片/视频/任何文件)，但是不推荐这么做。
4545
:::
4646

47-
### WenyanInput() 文言仿真加密函数
47+
### WenyanInput() 文言仿真加解密函数
4848

49-
`WenyanInput()` 函数用来对数据执行文言文仿真加密。
49+
`WenyanInput()` 函数用来对数据执行文言文仿真加解密。
5050

5151
```js
5252
import { Abracadabra } from "abracadabra-cn";
@@ -60,10 +60,11 @@ let Abra = new Abracadabra(); //不附带参数，
6060
* @param {string} mode 指定模式，可以是 ENCRYPT DECRYPT 中的一种;
6161
* @param {string} key 指定密钥，默认是 ABRACADABRA;
6262
* @param {WenyanConfig} WenyanConfigObj 文言文的生成配置;
63+
* @param {AdvancedEncConfig}AdvancedEncObj 指定安全加密特性;
6364
* @param {any}callback 回调函数，获取执行过程中特定位置的结果
6465
* @return {number} 成功则返回 0（失败不会返回，会抛出异常）
6566
*/
66-
Abra.WenyanInput(input, mode, key, {...}, callback);
67+
Abra.WenyanInput(input, mode, key, {...}, {...}, callback);
6768
```
6869

6970
第一个参数 `input` 接受两种类型的输入，分别是 `String` 和 `Uint8Array`，这是此前在实例化的时候指定的输入类型。
@@ -76,7 +77,9 @@ Abra.WenyanInput(input, mode, key, {...}, callback);
7677

7778
如果指定了错误的密码，那么在解码/解密数据校验过程中会抛出错误。
7879

79-
第五个参数 `callback` 接受一个回调函数，缺省时为 `null`。程序会在执行中关键位置多次调用此函数，以便调试，无调试需求可忽略此项。
80+
第六个参数 `callback` 接受一个回调函数，缺省时为 `null`。程序会在执行中关键位置多次调用此函数，以便调试，无调试需求可忽略此项。
81+
82+
---
8083

8184
第四个参数接受一个`WenyanConfig`配置对象的输入，仅在加密的时候需要：
8285

@@ -107,18 +110,90 @@ export interface WenyanConfig {
107110

108111
`PianwenMode` 和 `LogicMode` 不能同时指定为 `true`，否则会抛出错误。
109112

113+
---
114+
115+
第五个参数接受一个`AdvancedEncConfig`配置对象的输入，仅在高级加密的时候需要：
116+
117+
```javascript
118+
export interface AdvancedEncConfig {
119+
/** 指定是否打开高级加密功能，默认 false/不开启; */
120+
Enable?: boolean;
121+
/** 指定是否使用完整16字节IV，默认 true/开启*/
122+
UseStrongIV?: boolean;
123+
/** 指定是否使用HMAC对消息签名，默认 false/不开启; */
124+
UseHMAC?: boolean;
125+
/** 指定是否对密钥加盐并使用密钥衍生函数 false/不开启;*/
126+
UsePBKDF2?: boolean;
127+
/** 指定是否使用TOTP作为密钥衍生的盐值，默认 false/不开启，若不使用密钥衍生函数，则不生效;*/
128+
UseTOTP?: boolean;
129+
/** 指定TOTP时间窗口，取值范围 0~15
130+
* 对应 [3 5 10 30 min] [2 6 12 h] [1 3 5 d] [1 3 Week] [1 2 6 Month] [1 yr], 默认4;
131+
**/
132+
TOTPTimeStep?: number;
133+
/** 指定用于TOTP加密的Unix时间戳记，以毫秒为单位(JS标准)，默认为系统时间；*/
134+
135+
TOTPEpoch?: number;
136+
/**
137+
* 指定用于TOTP加密的预共享密钥，默认为加密主密钥，推荐使用网站域名作为此项密钥以提升安全性;
138+
* 注意，TOTP的安全性主要依赖于此BaseKey
139+
**/
140+
TOTPBaseKey?: string;
141+
}
142+
```
143+
144+
::: tip 提示
145+
146+
注意高级加密参数在解密时无需传递，除非需要指定 TOTP BaseKey 和 TOTP Epoch。
147+
148+
:::
149+
150+
`Enable` 是布尔值，默认为 `false`。如果传入 `true`，则将启用高级加密，解密时可以忽略这个参数。
151+
152+
`UseStrongIV` 是布尔值，默认为 `true`，如果传入 `true`，则高级加密时将使用完整 16 字节 IV。解密时可以忽略这个参数。
153+
154+
`UseHMAC` 是布尔值，默认为 `false`。如果传入 `true`，则高级加密时将使用 HMAC 对消息签名。解密时可以忽略这个参数。
155+
156+
`UsePBKDF2` 是布尔值，默认为 `false`。如果传入 `true`，则高级加密时将对密钥加盐并使用密钥衍生函数。解密时可以忽略这个参数。
157+
158+
`UseTOTP` 是布尔值，默认为 `false`。如果传入 `true`，则高级加密时将使用 TOTP 作为密钥衍生的盐值，若 `UsePBKDF2` 传入 `false`，则不生效。解密时可以忽略这个参数。
159+
160+
`TOTPTimeStep` 是整数值，默认为`4`，最小值`0`，最大值`15`，超过范围的输入将会报错。用于指定 TOTP 每步时长，每个值代表的时间见上方注释。解密时可以忽略这个参数。
161+
162+
`TOTPEpoch` 是整数值，默认为系统当前 Unix 时间戳，用于指定 TOTP 加密的 Unix 时间戳记，以毫秒为单位(JS 标准)。解密时可以携带这个参数，以指定用于解密的时间戳。
163+
164+
`TOTPBaseKey` 是字符串，默认为加密主密钥，用于指定 TOTP 加密的预共享密钥。解密时可以携带这个参数，以指定用于解密的 TOTP Basekey。
165+
166+
---
167+
110168
```javascript
111169
//正确调用方式：
112170

113171
import { Abracadabra } from "abracadabra-cn";
114172
let Abra = new Abracadabra(); //不附带参数，
115173

116-
Abra.WenyanInput(TestTemp, "ENCRYPT", "ABRACADABRA", {
117-
RandomIndex: 25,
118-
PianwenMode: true,
119-
}); //指定随机指数为25，并使用骈文模式，缺省项自动使用默认值
120-
121-
Abra.WenyanInput(TestTemp, "DECRYPT", "ABRACADABRA"); //解密不需要传入配置
174+
Abra.WenyanInput(
175+
TestTemp,
176+
"ENCRYPT",
177+
"ABRACADABRA",
178+
{
179+
RandomIndex: 25,
180+
PianwenMode: true,
181+
},
182+
{
183+
Enable: true,
184+
UseStrongIV: true,
185+
UseHMAC: true,
186+
UsePBKDF2: true,
187+
UseTOTP: true,
188+
}
189+
); //指定随机指数为25，并使用骈文模式，启用高级加密，缺省项自动使用默认值
190+
191+
Abra.WenyanInput(TestTemp, "DECRYPT", "ABRACADABRA"); //解密一般不需要传入配置
192+
193+
Abra.WenyanInput(TestTemp, "DECRYPT", "ABRACADABRA", null, {
194+
TOTPBaseKey: "Basekey",
195+
TOTPEpoch: 12345678,
196+
}); //可额外传入TOTP参数用于解密。
122197
```
123198

124199
在无错误的情况下， `WenyanInput()` 函数的返回值通常是 `0`。

‎docs/document/wasm-deploy.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,15 @@
1111
本模块的合法输入为一个 JSON 字符串，输入时请勿附带注释，遵循以下格式：
1212

1313
::: warning 兼容性提示
14+
1415
注意，V3.2 修改了接口标准，WASM 未对旧版本留有兼容，请参照新版接口来编写调用方式。
16+
17+
WASM 不是魔曰的主线开发任务，依赖库未经积极更新，如果遇到问题，请提 Issue。
18+
1519
:::
1620

1721
```json
22+
1823
{
1924
"method":"", // WENYAN | OLD
2025
"inputType":"", // TEXT | UINT8
@@ -23,14 +28,10 @@
2328
"mode":"", // ENCRYPT | DECRYPT | AUTO // AUTO 仅在 method 指定 OLD 时合法
2429
"key":"", // 加密密钥，一个字符串 //如果缺省，自动使用默认值
2530
"q":bool, // OLD模式下，决定是否添加标志位
26-
"WenyanConfig":{ //文言文生成配置，可以缺省，缺省自动使用默认值。
27-
"PunctuationMark": bool, // 指定是否为密文添加标点符号，默认 true/添加;
28-
"RandomIndex": number, // 仅WENYAN模式下需要：算法的随机程度，越大随机性越强，默认 50，最大100，超过100将会出错;
29-
"PianwenMode":bool, // 仅WENYAN模式下需要：尽可能使用对仗的骈文句式; 与逻辑句式冲突
30-
"LogicMode":bool, // 仅WENYAN模式下需要：尽可能使用逻辑句式; 与骈文句式冲突
31-
"Traditional":bool, // 仅WENYAN模式下需要：输出繁体中文。
32-
},
31+
"WenyanConfig":{...}, //文言文生成配置，详情见JavaScript接口定义。
32+
"AdvancedEncConfig":{...} //高级加密配置，详情见JavaScript接口定义。
3333
}
34+
3435
```
3536

3637
用 wasmtime CLI 调用，在不同的命令行里有不同的方式，大多数时候是输入字符串的字符集的区别，以及是否需要在字符串外面加单引号的区别。

‎src/javascript/main.test.js‎

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -157,8 +157,6 @@ test("高级加密测试", { timeout: 40000 }, () => {
157157

158158
TestData.forEach((data) => {
159159
let TestTemp;
160-
let TestTemp2;
161-
let TestTemp3;
162160
let TOTPEpochFreeze = Date.now();
163161
Abra.WenyanInput(
164162
data,
@@ -183,7 +181,7 @@ test("高级加密测试", { timeout: 40000 }, () => {
183181
TestTemp = Abra.Output();
184182

185183
Abra.WenyanInput(
186-
data,
184+
TestTemp,
187185
"ENCRYPT",
188186
"ABRACADABRA",
189187
{
@@ -204,7 +202,7 @@ test("高级加密测试", { timeout: 40000 }, () => {
204202
});
205203
TestTemp = Abra.Output();
206204
Abra.WenyanInput(
207-
data,
205+
TestTemp,
208206
"ENCRYPT",
209207
"ABRACADABRA",
210208
{
@@ -225,7 +223,7 @@ test("高级加密测试", { timeout: 40000 }, () => {
225223
});
226224
TestTemp = Abra.Output();
227225
Abra.WenyanInput(
228-
data,
226+
TestTemp,
229227
"ENCRYPT",
230228
"ABRACADABRA",
231229
{
@@ -246,7 +244,7 @@ test("高级加密测试", { timeout: 40000 }, () => {
246244
});
247245
TestTemp = Abra.Output();
248246
Abra.WenyanInput(
249-
data,
247+
TestTemp,
250248
"ENCRYPT",
251249
"ABRACADABRA",
252250
{
@@ -267,7 +265,7 @@ test("高级加密测试", { timeout: 40000 }, () => {
267265
});
268266
TestTemp = Abra.Output();
269267
Abra.WenyanInput(
270-
data,
268+
TestTemp,
271269
"ENCRYPT",
272270
"ABRACADABRA",
273271
{
@@ -288,7 +286,28 @@ test("高级加密测试", { timeout: 40000 }, () => {
288286
});
289287
TestTemp = Abra.Output();
290288
Abra.WenyanInput(
291-
data,
289+
TestTemp,
290+
"ENCRYPT",
291+
"ABRACADABRA",
292+
{
293+
RandomIndex: 100,
294+
},
295+
{
296+
Enable: true,
297+
UseStrongIV: true,
298+
UseHMAC: false,
299+
UsePBKDF2: true,
300+
UseTOTP: false,
301+
TOTPEpoch: TOTPEpochFreeze,
302+
}
303+
);
304+
TestTemp = Abra.Output();
305+
Abra.WenyanInput(TestTemp, "DECRYPT", "ABRACADABRA", ...[,], {
306+
TOTPEpoch: TOTPEpochFreeze,
307+
});
308+
TestTemp = Abra.Output();
309+
Abra.WenyanInput(
310+
TestTemp,
292311
"ENCRYPT",
293312
"ABRACADABRA",
294313
{

0 commit comments

Comments
 (0)