bcrypt：Python 密码哈希的标准做法

pyca/bcrypt 在 GitHub 上拿到 1,481 Star。

这个库只做一件事：给 Python 项目提供安全的密码哈希。它基于 bcrypt 算法实现，是目前业界公认的密码存储方案之一。项目由 Python Cryptographic Authority 维护，和知名的 cryptography 库同出一门，安全策略也是同一套标准。

1、这库是干嘛的

密码明文存储是安全问题里最基础的一类，也是最常见的一类。bcrypt 库把这件事变得很简单：输入密码，输出哈希值；下次验证时，拿明文和已有的哈希比对，几行代码就搞定。

它内部完整实现了 bcrypt 算法的核心逻辑，包括随机盐生成、对数级可调工作因子、以及 OpenSSH 使用的 bcrypt_pbkdf 密钥派生函数。支持 $2a$ 和 $2b$ 前缀，兼容大多数历史实现。3.0.0 之前的 $2y$ 前缀依然能在 hashpw 里用，但已经被标记为废弃。

2、安装需要什么

装起来不复杂，一条 pip 命令：

pip install bcrypt

但有个编译前提：系统里得有 C 编译器和 Rust 编译器（最低版本 1.74.0）。Linux 上通常能满足，不同发行版的依赖安装命令如下：

Debian / Ubuntu：

sudo apt-get install build-essential cargo

Fedora / RHEL 系：

sudo yum install gcc cargo

Alpine：

apk add --update musl-dev gcc cargo

Windows 和 macOS 如果装的是预编译 wheel，一般不需要自己编译，开箱即用。

3、怎么用

密码哈希和验证的完整流程只有这几行：

import bcrypt

password = b"super secret password"
hashed = bcrypt.hashpw(password, bcrypt.gensalt())

if bcrypt.checkpw(password, hashed):
    print("It Matches!")

工作因子默认是 12，可以手动调高。数字越大，单次哈希计算越慢，暴力破解的成本也就越高：

hashed = bcrypt.hashpw(password, bcrypt.gensalt(14))

如果密码超过 72 字节，会直接抛 ValueError。这是 3.0.0 之后的行为变更，之前是静默截断。处理超长密码的常见做法是先做 SHA256，再 base64 编码，最后交给 bcrypt 处理：

import base64, hashlib

password = b"an incredibly long password" * 10
hashed = bcrypt.hashpw(
    base64.b64encode(hashlib.sha256(password).digest()),
    bcrypt.gensalt()
)

需要密钥派生的话，3.0.0 之后新增了 kdf 函数，实现的是 bcrypt_pbkdf。这个 KDF 被用在 OpenSSH 的新版加密私钥格式里：

key = bcrypt.kdf(
    password=b'password',
    salt=b'salt',
    desired_key_bytes=32,
    rounds=100
)

4、兼容性与安全策略

支持 Python 3.9 及以上版本，包括 free-threaded 构建，也支持 PyPy 3。和旧版的 py-bcrypt 保持兼容，可以平滑迁移。

安全漏洞的处理方式和 cryptography 库一致：发现安全问题需要私下联系维护者，而不是直接公开提 issue。

项目维护者的态度很实在：bcrypt 目前依然是可接受的选择，但如果有条件，新项目可以考虑 argon2id 或 scrypt。bcrypt 的优势在于成熟度够高、生态够广、几乎所有主流语言和平台都有实现，迁移成本最低。

5、适合谁用

• 在写 Web 后端、需要处理用户注册和登录密码的开发者
• 在做命令行工具或本地脚本、需要密码保护的开发者
• 在维护老项目、已经在用 bcrypt 需要替换 py-bcrypt 的开发者
• 在用 OpenSSH 新版私钥格式、需要 bcrypt_pbkdf 支持的开发者

地脚本、需要密码保护的开发者

• 在维护老项目、已经在用 bcrypt 需要替换 py-bcrypt 的开发者
• 在用 OpenSSH 新版私钥格式、需要 bcrypt_pbkdf 支持的开发者