73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
|
# 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）
|