# 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）