From 69aedd0eaae48f6c491523d336fbc2ee9b1a757a Mon Sep 17 00:00:00 2001
From: chakcy <947105045@qq.com>
Date: Wed, 5 Aug 2026 18:21:06 +0800
Subject: [PATCH] =?UTF-8?q?modify:=20=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.py |  0
 2 files changed, 72 insertions(+)
 create mode 100644 README.md
 create mode 100644 README.py

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..155007a
--- /dev/null
+++ b/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）
diff --git a/README.py b/README.py
new file mode 100644
index 0000000..e69de29