# 算法说明

花钥本版本只保留两类密码生成算法：**花密 v5 兼容**与 **VaultCanvas 随机密码**。VaultCanvas 的 BLAKE3 确定性派生、33 词口令短语，以及花钥此前的增强派生均已移除；文件加密与隐写只使用 VaultCanvas 格式，详见[文件格式](file-formats.md)。

所有字符串按 UTF-8 编码处理；花密输出使用小写十六进制。VaultCanvas 文件格式使用大端序。

---

## 1. 算法总览

| 模式 | 可重现 | 上游算法 | 输出域 |
|---|---|---|---|
| 花密 v5 | 是 | FlowerPassword v5（MD5 / HMAC-MD5） | 十六进制字符 + 大小写规则，2–32 位 |
| VaultCanvas 随机 | 否 | CSPRNG + 缩减字符集 | 任意正长度（界面 1–64），25/24/8/13 字符集 |

VaultCanvas 的强度评分仍用于随机密码的界面提示；它不是密码生成算法。

---

## 2. 花密兼容模式（FlowerPassword v5）

### 2.1 目的

只用于**复现 flowerpassword.com / flowerpassword.js v5 已经生成的密码**。它不是花钥的推荐新密码方案。

### 2.2 算法

输入：

- `master`：记忆密码（任意 Unicode 字符串）
- `code`：区分代号（任意 Unicode 字符串）
- `length`：输出长度，整数 2–32

步骤：

```text
base   = hex(HMAC-MD5(key = code,   message = master))
source = hex(HMAC-MD5(key = "snow", message = base))
rule   = hex(HMAC-MD5(key = "kise", message = base))
```

如果 `code` 为空，第一步与 blueimp-md5 的行为一致，退化为 `hex(MD5(master))`。空 `master` 仍参与计算。

随后逐位处理 32 个十六进制字符：

```text
for i in 0..31:
    if source[i] is not a digit and rule[i] ∈ MAGIC:
        source[i] = uppercase(source[i])
```

`MAGIC` 是花密源码中的 26 字符魔法串 `sunlovesnow1990090127xykab`。

最后处理首位并截断：

```text
full = transformed(source)          # 32 char
if full[0] is a digit:
    output = "K" + full[1 : length]
else:
    output = full[0 : length]
```

因此：

- 输出只包含数字 `0-9`、小写 `a-f`、可能的大写 `A-F`，以及首位的 `K`。
- 首位永远是字母（`K` 或 `a-f`/`A-F`）。
- 长度 2–32 的输出是长度 32 输出的前缀。

### 2.3 官方兼容向量

| master | code | length | output |
|---|---|---|---|
| `password` | `key` | 2 | `K3` |
| `password` | `key` | 8 | `K3A2a66B` |
| `password` | `key` | 16 | `K3A2a66Bf88b628c` |
| `password` | `key` | 32 | `K3A2a66Bf88b628c2Cd7cDA9958f6b26` |
| `test` | `github.com` | 16 | `D04175F7A9c7Ab4a` |
| `mypassword` | `example.com` | 12 | `K0CA12CecFFB` |
| `12345` | `site` | 16 | `K05a62bfea0C1553` |
| `密码` | `网站.com` | 16 | `KFF7FEa7928bAAAa` |
| `""` | `key` | 16 | `K46eB52c968caeAa` |
| `password` | `""` | 16 | `eB3b1cA3D6B54c00` |

这些向量同时存在于 `tests/algorithm-tests.js` 与 `tests/browser-tests.js` 中，任何算法改动都必须保持它们通过。

### 2.4 安全性说明

- 花密的公开算法基于 **MD5 / HMAC-MD5**。MD5 的抗碰撞性早已被攻破，HMAC-MD5 也不是现代推荐的密钥派生函数。保留它完全是为了兼容历史密码。
- 输出字母表很小：十六进制字符（数字 + `a-f`）和大小写规则。按每位 4 bit 的**保守估算**，16 位约 64 bit，32 位约 128 bit。大写规则会带来少量额外熵，但不改变“历史算法”的性质。
- 花密兼容模式不能防止彩虹表/字典攻击对记忆密码本身的猜测。记忆密码必须足够强且唯一。
- **新账户应使用随机密码**。

---

## 3. VaultCanvas 随机密码

实现文件：`js/vaultcanvas-password.js`。对应 `VaultCanvas/crates/password_engine/src/lib.rs` 的 `generate_password`。

### 3.1 缩减字符集

```text
LOWER    abcdefghijkmnopqrstuvwxyz        25（缺 l）
UPPER    ABCDEFGHJKLMNPQRSTUVWXYZ         24（缺 I、O）
DIGITS   23456789                          8（缺 0、1）
SYMBOLS  !@#$%^&*-_=+?                    13
合计                                       70
```

启用多个字符集时，按“小写 → 大写 → 数字 → 符号”的顺序拼接。界面默认全部勾选。

### 3.2 生成流程

```text
alphabet = 所有启用字符集的并集
for i in 0..length-1:
    output[i] = alphabet[uniform_random_index(alphabet.length)]
```

- 对并集均匀取字符；
- **不保证**每个字符组至少出现一次；
- 长度可为任意正整数；界面范围为 1–64；
- 浏览器使用 `crypto.getRandomValues`，并采用单字节拒绝采样消除取模偏差：先拒绝 `>= 256 - (256 % n)` 的字节，再取模；
- 每次生成独立，不可重现，也不保存。

### 3.3 与 VaultCanvas 的关系

本版本只保留 Rust `generate_password` 的随机语义。VaultCanvas 的 BLAKE3 确定性派生与口令短语生成器不在花钥中实现，界面也没有对应入口。

---

## 4. VaultCanvas 强度评分

```text
pool = 出现小写 ? 25 : 0
     + 出现大写 ? 24 : 0
     + 出现数字 ?  8 : 0
     + 出现符号 ? 13 : 0
entropy = f32(UTF-8 字节长度 × log2(pool))
```

- 按密码中**实际出现**的 ASCII 类别计分，未出现的类别不加入 pool；
- 逐 Unicode 标量迭代；
- 符号判断复刻 Rust 的 `c as u8` 截断：`SYMBOLS.contains((code & 0xff) as char)`；
- 熵按 IEEE-754 单精度（`Math.fround`）计算；
- 阈值：40 / 56 / 72 / 96，对应 0–4 分；
- 原始 label 为 `excellent` / `strong` / `moderate` / `weak` / `very weak`，界面映射为中文。

随机密码的强度显示使用该函数。

---

## 5. 界面强度表

界面使用以下阈值（单位 bit）：

| 熵 | 分数 | 标签 |
|---|---|---|
| < 40 | 0 | 很弱 |
| 40–55 | 1 | 偏弱 |
| 56–71 | 2 | 中等 |
| 72–95 | 3 | 强 |
| ≥ 96 | 4 | 极强 |

不同模式的口径：

- **花密兼容**：`length × 4`（保守估算）。
- **VaultCanvas 随机**：VaultCanvas `score_password` 的实际类别 pool 与 UTF-8 字节长度。

强度条只是**用户教育提示**，不是密码破解难度证明。

---

## 6. 实现映射

| 能力 | 文件 | 主要依赖 |
|---|---|---|
| MD5 与 HMAC-MD5 | `js/md5.js` | 无 |
| 花密兼容派生 | `js/flowerpassword.js` | `js/md5.js` |
| VaultCanvas 随机密码/评分 | `js/vaultcanvas-password.js` | Web Crypto CSPRNG + TextEncoder |
| VaultCanvas 文件加密 | `js/vaultcanvas-crypto.js` | hash-wasm Argon2id/SHA3 + Web Crypto AES-GCM |
| VaultCanvas 文件隐写 | `js/vaultcanvas-stego.js` | Web Crypto PBKDF2/AES-CBC/SHA-256 + CompressionStream |
| 共享工具 | `js/crypto-common.js` | Web Crypto、字节与文件名辅助 |

## 7. 参考

- FlowerPassword 官方站点：<https://flowerpassword.com/>
- flowerpassword.js v5（官方站点打包脚本）
- `xlsdg/flowerpassword.rust`（MIT，用于交叉验证兼容向量）
- VaultCanvas `crates/password_engine/src/lib.rs`（本仓库上级目录）
- [`hash-wasm`](https://github.com/Daninet/hash-wasm)（MIT，本机捆绑的 Argon2id/SHA3）

花钥与 FlowerPassword 项目没有隶属关系。
