签入版本

DjangoAdmin_Flask_AntdVue/zh/volume4/tools/password.md

@@ -0,0 +1,118 @@
+# 密码工具
+
+:::tip 说明
+项目采用 bcrypt 双重加盐方案存储密码，源码位于 `src/core/password.py`。工作因子 12（约 250ms），在安全性和性能之间取得平衡。
+:::
+
+## 加密方案
+
+密码存储采用「外部随机盐 + bcrypt 内部盐」双重加盐方案：
+
+```
+用户密码 + 外部盐 → bcrypt.hashpw → 存储哈希值
+```
+
+### 生成盐值
+
+```python
+import secrets
+
+BCRYPT_ROUNDS = 12  # 工作因子，约250ms
+
+def generate_salt(length: int = 10) -> str:
+    """生成随机盐值"""
+    return secrets.token_urlsafe(length)[:length]
+```
+
+### 加密密码
+
+```python
+import bcrypt
+
+def encrypt_password(password: str, salt: str) -> str:
+    """使用 bcrypt 加密密码（外部 salt 双重加盐）"""
+    combined = (password + salt).encode('utf-8')
+    hashed = bcrypt.hashpw(combined, bcrypt.gensalt(rounds=BCRYPT_ROUNDS))
+    return hashed.decode('utf-8')
+```
+
+### 验证密码
+
+```python
+def verify_password(password: str, salt: str, hashed: str) -> bool:
+    """验证密码是否正确"""
+    combined = (password + salt).encode('utf-8')
+    return bcrypt.checkpw(combined, hashed.encode('utf-8'))
+```
+
+## 工作因子
+
+`BCRYPT_ROUNDS = 12` 表示 bcrypt 的工作因子为 12，即需要 2^12 = 4096 次迭代。值越大计算越慢越安全，12 是当前推荐值（约 250ms）。
+
+:::tip 温馨提示
+bcrypt 的工作因子决定了加密速度。增加 1 会使计算时间翻倍。建议保持默认值 12，在安全性和性能之间取得平衡。
+:::
+
+## 存储结构
+
+用户表中密码相关字段：
+
+| 字段 | 说明 |
+|------|------|
+| `password` | bcrypt 哈希后的密码 |
+| `salt` | 外部随机盐值 |
+
+## 使用示例
+
+### 注册/创建用户
+
+```python
+from src.core.password import generate_salt, encrypt_password
+
+salt = generate_salt()
+hashed = encrypt_password("mypassword", salt)
+# 将 hashed 和 salt 存入数据库
+```
+
+### 登录验证
+
+登录验证位于 `src/modules/auth/service.py`：
+
+```python
+from src.core.password import verify_password
+
+# 从数据库获取用户记录
+user = get_user_by_username(username)
+
+# 验证密码
+password_ok = verify_password(data['password'], user.salt or '', user.password or '')
+if password_ok:
+    # 密码正确
+    ...
+```
+
+### 修改密码
+
+```python
+# 验证旧密码
+if not verify_password(old_password, user.salt, user.password):
+    return R.failed("原密码错误")
+
+# 生成新盐值并加密
+new_salt = generate_salt()
+new_hashed = encrypt_password(new_password, new_salt)
+# 更新数据库
+```
+
+## 安全特性
+
+```
+1. 双重加盐：外部随机盐 + bcrypt 内部盐，即使两个用户使用相同密码，存储的哈希值也不同
+2. 抗彩虹表：bcrypt 自带盐值，无法预计算彩虹表
+3. 抗暴力破解：工作因子 12 使每次验证约 250ms，大幅增加暴力破解成本
+4. 自适应性：工作因子可随硬件提升而增加
+```
+
+## 总结
+
+密码工具采用 bcrypt 双重加盐方案，外部盐值由 `secrets.token_urlsafe()` 生成，bcrypt 内部盐自动处理。工作因子 12 在安全性和性能之间取得平衡，有效抵御彩虹表和暴力破解攻击。