# 不只是md5(密码)：hashlib模块的四个层次与一个红线
**多数Python入门者认识hashlib，是从这一行开始的：**
```python
hashlib.md5(b"123456").hexdigest()
```
**然后被告知：MD5不安全，换SHA256；接着又被警告：密码不能这么存，要用scrypt。**
hashlib模块的文档很短，但**从“能用”到“用对”，中间隔着四个认知层次**。本文以官方文档为纲，结合生产踩坑案例，梳理这套从基础摘要到安全密码存储的完整路径。
## 一、第一层：生成摘要——记住“输入必须是字节”
hashlib的核心接口极简：**`update()`喂数据，`hexdigest()`取摘要**。但第一个报错90%来自这里：
```python
import hashlib
# ❌ 错误示范：字符串不能直接喂给update
data = "hello world"
hash_obj = hashlib.sha256()
# hash_obj.update(data) # TypeError: Unicode-objects must be encoded before hashing
# ✅ 正确做法：显式编码为bytes
hash_obj.update(data.encode('utf-8'))
print(hash_obj.hexdigest())
```
**哈希算法操作的是二进制字节，不是文本字符**。这是hashlib的第一条红线。
**两种常用写法**：
```python
# 分段更新（大文件/流式数据）
m = hashlib.sha256()
m.update(b'part1')
m.update(b'part2')
print(m.hexdigest())
# 单次构造（小数据）
print(hashlib.sha256(b'part1part2').hexdigest()) # 结果同上
```
## 二、第二层：大文件校验——分块是必选项
**一次性读取10GB文件计算哈希，内存会直接爆掉**。正确的姿势是用`update()`分块迭代：
```python
def hash_file(filepath, algorithm='sha256', chunk_size=8192):
hasher = hashlib.new(algorithm) # 支持算法名动态指定
with open(filepath, 'rb') as f:
while True:
chunk = f.read(chunk_size)
if not chunk:
break
hasher.update(chunk)
return hasher.hexdigest()
```
<"e7.p5k3.org.cn">
<"u9.p5k3.org.cn">
<"b2.p5k3.org.cn">
**适用场景**：软件镜像校验、网盘文件秒传判定、备份完整性验证。**不涉及密码存储**。
## 三、第三层：密码存储——普通哈希是“错误答案”
**很多教程止步于“对密码做SHA256存入数据库”**。但这是**典型的错误示范**。
**为什么不行**？
1. **速度太快**：GPU每秒可计算数十亿次SHA256，8位纯数字密码秒破
2. **无随机化**：相同密码生成相同哈希，彩虹表一击即溃
**正确方案：密钥派生函数（KDF）**。hashlib内置**PBKDF2**和**scrypt**两个专业密码哈希函数。
### scrypt（推荐，抗GPU/ASIC）
```python
import hashlib
import os
# 注册：生成随机盐 + scrypt哈希
salt = os.urandom(16) # 每个用户独立盐值
hashed = hashlib.scrypt(
password=b'user_password',
salt=salt,
n=2**14, # CPU/内存成本（根据硬件调大）
r=8, # 块大小
p=1, # 并行因子
dklen=32 # 输出长度
)
# 数据库存储字段：salt + hashed
# 登录验证：取出盐，对输入密码做相同计算
test_hash = hashlib.scrypt(
password=b'input_password',
salt=db_salt,
n=2**14, r=8, p=1, dklen=32
)
if test_hash == db_hashed:
print("密码正确")
```
<"x5.p5k3.org.cn">
<"r1.p5k3.org.cn">
<"k8.p5k3.org.cn">
### PBKDF2（兼容性更广）
```python
dk = hashlib.pbkdf2_hmac(
'sha256',
b'password',
b'salt',
iterations=600000 # 迭代次数，2025年建议60万次以上
)
```
**红线二：普通哈希算法（MD5/SHA系列）不能直接用于密码存储。KDF才是正确答案**。
## 四、第四层：消息认证——用hmac防篡改
**场景**：你给客户端下发一个“VIP有效期为2026-12-31”的令牌，如何防止用户篡改日期？
**方案**：**HMAC（基于哈希的消息认证码）**——带密钥的哈希。
```python
import hmac
import hashlib
key = b'server_secret_key' # 密钥只存服务端
message = b'expire=2026-12-31'
# 生成签名
signature = hmac.new(key, message, hashlib.sha256).hexdigest()
# 令牌内容：expire=2026-12-31&sig=1a2b3c...
# 服务端验证：重新计算签名，比对
```
**HMAC与普通哈希的区别**：**无密钥则无法伪造有效签名**。适用于API签名、JWT替代、配置文件完整性保护。
## 五、红线清单与决策树
| 场景 | 正确工具 | 禁用项 |
|------|--------|--------|
| 文件完整性校验 | `hashlib.sha256()` | MD5/SHA1（抗碰撞弱） |
| 下载镜像比对 | `hashlib.md5()` | ——（仅校验时可用） |
| **用户密码存储** | **`hashlib.scrypt()` / `pbkdf2_hmac`** | **任何MD5/SHA系列** |
| API签名/防篡改 | `hmac.new()` | 明文哈希无密钥 |
| 大文件哈希 | 分块`update()` | 一次性读入内存 |
**官方文档明确警告**：MD5、SHA-1因碰撞攻击已被攻破，不应用于安全敏感场景。**2026年的今天，这个警告仍被大量生产代码忽视**。
**hashlib入门不难，难的是跨过“能用”与“用对”之间的那条认知鸿沟**。**文件校验用SHA256，密码存储用scrypt——记住这两条，你已经胜过很多“熟练使用md5加密密码”的教程**。