如何正确使用 bcrypt 比较密码哈希与明文密码

如何正确使用 bcrypt 比较密码哈希与明文密码

本文详解 Go 语言中 bcrypt.CompareHashAndPassword 的正确用法：必须将已存储的哈希值作为第一个参数、用户提交的明文密码作为第二个参数，顺序颠倒会导致“not the hash of the given password”错误。

在 Go 语言项目中，使用 golang.org/x/crypto/bcrypt 进行密码验证是标准操作，但其中有一个参数顺序的“坑”，不少开发者都曾不小心掉进去过。具体表现就是，你会遇到那个令人困惑的 crypto/bcrypt: hashedPassword is not the hash of the given password 错误。

问题往往出在调用方式上。来看一个典型的错误示例：

err = bcrypt.CompareHashAndPassword(hashedPassword, []byte(u.Password))

这段代码的逻辑哪里不对劲？关键在于对两个参数的理解。hashedPassword 在这里是刚刚用 GenerateFromPassword 为当前登录密码生成的新哈希，而 u.Password 本应是数据库里存储的、作为比对基准的旧哈希。这相当于在问系统：“这个新哈希，是不是那个旧哈希的明文？”——方向完全反了。不仅如此，CompareHashAndPassword 函数内部会先校验第一个参数是否为合法的 bcrypt 哈希格式。如果你误传了明文或格式错误的字符串进去，它当然会立刻抛出上述错误。

✅ 正确的调用姿势

那么，正确的做法是什么？核心原则就一句话：用数据库中持久化的那个哈希值，去验证用户本次提交的明文密码。

具体到代码，应该是这样：

u := models.Users{}
u = u.FindByEmail(login.Email)

// 关键点：确保 u.Password 是从数据库读取的原始 bcrypt 哈希字符串（格式如 "$2a$10$..."），而不是明文！
hashBytes := []byte(u.Password)
plainBytes := []byte(login.Password)

err := bcrypt.CompareHashAndPassword(hashBytes, plainBytes)
if err != nil {
    // 密码不匹配，或者哈希格式本身有问题（比如字段为空、被截断、意外存成了明文等）
    log.Printf("Password verification failed: %v", err)
    http.Error(w, "Invalid credentials", http.StatusUnauthorized)
    return
}
// 验证通过，执行后续登录逻辑

简单来说，CompareHashAndPassword(storedHash, userInput) 的语义就是：“存储的哈希是否由用户输入的明文生成？” 记住这个对应关系，问题就解决了一大半。

⚠️ 几个必须留意的细节

除了参数顺序，下面这几个点同样重要，任何一个环节出问题都可能导致验证失败：

• 存的一定得是哈希，不是明文：在用户注册或修改密码时，务必调用 bcrypt.GenerateFromPassword(plain, cost)，并将返回的哈希字符串（直接转成 string）存入数据库的密码字段。这一步是基础。
• 登录时千万别再生成哈希：登录验证流程中，bcrypt.GenerateFromPassword 是多余的，而且有安全隐患。它的任务只在注册或密码重置时完成。
• 检查存储的内容：确保从数据库读出的 u.Password 字段非空、长度正常（标准的 bcrypt 哈希是 60 个字符），并且没有被意外存入明文。任何格式异常都会导致比对函数立即报错。
• 成本因子（Cost）不用操心：bcrypt 的哈希字符串本身已经编码了盐值（salt）和成本因子。在验证时，CompareHashAndPassword 会自动提取并复用这些参数，开发者无需进行任何额外处理。

总结

归根结底，避免这个错误的关键在于清晰理解函数设计的初衷：bcrypt.CompareHashAndPassword(hashed, plain)。第一个参数位置，永远留给可信的、已存储的哈希值；第二个参数位置，永远留给待验证的原始明文密码。牢牢把握住这个“哈希验明文”的逻辑，就能绕开绝大多数因参数顺序或数据状态引发的认证问题。