modify: 说明文档

README.md

@@ -0,0 +1,72 @@
+# chongming-password
+
+基于 **Rust + PyO3** 实现的 Argon2id 密码哈希库，性能优越，内存安全。
+
+---
+
+## 安装
+
+```bash
+uv pip install -e utils/password
+```
+
+需要 Rust 工具链，`uv` 自动通过 `maturin` 编译。
+
+---
+
+## API
+
+```python
+import chongming_password
+
+# 哈希密码
+hashed: str = chongming_password.hash_password("my-secret-password")
+# => "$argon2id$v=19$m=19456,t=2,p=1$..."
+
+# 验证密码
+chongming_password.verify_password("my-secret-password", hashed)  # True
+chongming_password.verify_password("wrong-password", hashed)      # False
+```
+
+| 函数              | 签名                                          | 说明                               |
+| ----------------- | --------------------------------------------- | ---------------------------------- |
+| `hash_password`   | `(password: str) -> str`                      | Argon2id 哈希，返回 PHC 格式字符串 |
+| `verify_password` | `(password: str, password_hash: str) -> bool` | 验证明文密码与哈希是否匹配         |
+
+---
+
+## Argon2id 参数
+
+| 参数             | 值                 | 说明                                           |
+| ---------------- | ------------------ | ---------------------------------------------- |
+| **变体**         | Argon2id           | 混合模式（抗 GPU + 抗侧信道）                  |
+| **内存成本 (m)** | 19456 KiB (19 MiB) | 每次哈希消耗内存                               |
+| **迭代次数 (t)** | 2                  | 时间成本                                       |
+| **并行度 (p)**   | 1                  | 线程数                                         |
+| **输出格式**     | PHC 字符串         | `$argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>` |
+
+---
+
+## 安全性
+
+- **Argon2id**：2015 年密码哈希竞赛冠军，对抗 GPU/ASIC/FPGA 暴力破解
+- 每次哈希自动生成随机 **salt**（16 字节）
+- 输出 PHC 格式，包含所有验证所需参数
+- 密码为空 → `ValueError`
+- 哈希格式无效 → `ValueError`
+
+---
+
+## 手动编译
+
+```bash
+uv run maturin develop --release -m utils/password/Cargo.toml
+```
+
+---
+
+## 依赖 (Rust)
+
+- `argon2` — Argon2 密码哈希
+- `pyo3` — Python 绑定
+- `rand_core` — 安全随机数（salt）