Scrypt与HMAC认证参数顺序陷阱解析

引言：Go语言密码认证库的构建

在Go语言中实现安全的密码认证通常涉及使用强大的密钥派生函数（如Scrypt）和消息认证码（如HMAC-SHA256）。Scrypt用于将用户密码和随机盐值（Salt）转换为一个高强度的密钥，以抵御彩虹表攻击和暴力破解。HMAC则使用一个秘密密钥对Scrypt生成的密钥进行签名，以验证数据的完整性和真实性。一个典型的密码认证库会包含两个核心功能：New用于生成新的密码哈希和盐值，Check用于验证给定密码的正确性。

然而，即使是经验丰富的开发者，在处理多个类型相同但语义不同的参数时，也可能不慎引入难以察觉的错误，尤其是在加密相关的敏感操作中。本文将通过一个实际案例，深入探讨此类问题及其解决方案。

问题溯源：哈希函数参数顺序的隐性错误

在上述密码认证库的实现中，核心的哈希生成逻辑封装在一个名为 hash 的辅助函数中。该函数接收HMAC密钥、密码和盐值作为输入，并按特定顺序进行处理：首先使用Scrypt处理密码和盐值，然后使用HMAC对Scrypt的输出进行签名。

// hash takes an HMAC key, a password and a salt (as byte slices)
// scrypt transforms the password and salt, and then HMAC transforms the result.
// Returns the resulting 256 bit hash.
func hash(hmk, pw, s []byte) (h []byte, err error) {
    // 1. Scrypt处理：密码和盐值
    sch, err := scrypt.Key(pw, s, N, R, P, KEYLENGTH)
    if err != nil {
        return nil, err
    }
    // 2. HMAC签名：使用HMAC密钥对Scrypt输出进行签名
    hmh := hmac.New(sha256.New, hmk)
    hmh.Write(sch)
    h = hmh.Sum(nil)
    hmh.Reset() // 重置HMAC实例，虽然在此处非必需，但保持良好习惯
    return h, nil
}

问题出在 Check 和 New 这两个函数在调用 hash 函数时，对参数 hmk (HMAC密钥)、pw (密码) 和 s (盐值) 的传递顺序不一致。

• Check 函数中的调用：

  // Check函数中，参数传递顺序为 (hmk, pw, s)
  hchk, err := hash(hmk, pw, s)

  这里，hmk 被正确地作为第一个参数传入 hash，pw 作为第二个，s 作为第三个。这与 hash 函数的定义 func hash(hmk, pw, s []byte) 保持一致。

• New 函数中的调用：

  // New函数中，参数传递顺序为 (pw, hmk, s)
  h, err = hash(pw, hmk, s) // 错误发生在这里！

  在 New 函数中，HMAC密钥 (hmk) 和密码 (pw) 的位置被颠倒了。pw 被作为第一个参数传入 hash，而 hmk 被作为第二个参数传入。这意味着 hash 函数内部接收到的 hmk 实际上是密码，而 pw 实际上是HMAC密钥。

由于 hash 函数内部的 Scrypt 密钥派生和 HMAC 签名操作都依赖于这些参数的正确语义，参数顺序的颠倒会导致 New 函数生成一个基于错误输入的哈希值。当 Check 函数尝试使用正确的参数顺序验证这个错误的哈希时，自然会失败，因为两者计算出的哈希值完全不同。

原始代码分析

为了更清晰地展示问题，我们回顾原始代码中相关的部分：

package main

import (
    "golang.org/x/crypto/scrypt" // 更新为标准导入路径
    "crypto/hmac"
    "crypto/rand"
    "crypto/sha256"
    "crypto/subtle"
    "errors"
    "fmt"
    "io"
)

// Constants for scrypt.
const (
    KEYLENGTH = 32
    N         = 16384
    R         = 8
    P         = 1
)

// hash 函数定义：func hash(hmk, pw, s []byte)
func hash(hmk, pw, s []byte) (h []byte, err error) {
    sch, err := scrypt.Key(pw, s, N, R, P, KEYLENGTH)
    if err != nil {
        return nil, err
    }
    hmh := hmac.New(sha256.New, hmk)
    hmh.Write(sch)
    h = hmh.Sum(nil)
    return h, nil
}

// Check 函数：正确调用 hash(hmk, pw, s)
func Check(hmk, h, pw, s []byte) (chk bool, err error) {
    fmt.Printf("Check - Input: Hash:%x HMAC:%x Salt:%x Pass:%x\n", h, hmk, s, pw)
    hchk, err := hash(hmk, pw, s) // 参数顺序正确
    if err != nil {
        return false, err
    }
    fmt.Printf("Check - Computed: Hchk:%x\n", hchk)
    if subtle.ConstantTimeCompare(h, hchk) != 1 {
        return false, errors.New("Error: Hash verification failed")
    }
    return true, nil
}

// New 函数：错误调用 hash(pw, hmk, s)
func New(hmk, pw []byte) (h, s []byte, err error) {
    s = make([]byte, KEYLENGTH)
    _, err = io.ReadFull(rand.Reader, s)
    if err != nil {
        return nil, nil, err
    }
    h, err = hash(pw, hmk, s) // 错误：hmk 和 pw 的位置颠倒了
    if err != nil {
        return nil, nil, err
    }
    fmt.Printf("New - Output: Hash:%x Salt:%x Pass:%x\n", h, s, pw)
    return h, s, nil
}

func main() {
    // 示例数据和测试逻辑保持不变
    pass := "pleaseletmein"
    // ... (hash, salt, hmac 字节数组定义) ...
    hash := []byte{ /* ... */ }
    salt := []byte{ /* ... */ }
    hmacKey := []byte{ /* ... */ } // 重命名变量以避免与函数名冲突

    fmt.Println("Checking known values (works)...")
    chk, err := Check(hmacKey, hash, []byte(pass), salt)
    if err != nil {
        fmt.Printf("Error: %s\n", err)
    }
    fmt.Printf("Result: %t\n\n", chk)

    fmt.Println("Creating new hash and salt values (then fails verification)...")
    newHash, newSalt, err := New(hmacKey, []byte(pass))
    if err != nil {
        fmt.Printf("Error: %s\n", err)
    }

    fmt.Println("Checking new hash and salt values...")
    chk, err = Check(hmacKey, newHash, []byte(pass), newSalt)
    if err != nil {
        fmt.Printf("Error: %s\n", err)
    }
    fmt.Printf("Result: %t\n", chk)
}

运行上述代码，你会发现使用 New 函数新生成的哈希值无法通过 Check 函数的验证，而旧的、硬编码的哈希值却可以。

解决方案：统一参数传递顺序

解决此问题的关键在于确保所有调用 hash 函数的地方都使用一致的参数顺序。只需修改 New 函数中对 hash 的调用，将 hmk 和 pw 的位置交换回来。

// New 函数：修正后的调用
func New(hmk, pw []byte) (h, s []byte, err error) {
    s = make([]byte, KEYLENGTH)
    _, err = io.ReadFull(rand.Reader, s)
    if err != nil {
        return nil, nil, err
    }
    // 修正：将 pw, hmk 调整为 hmk, pw
    h, err = hash(hmk, pw, s) // 正确的参数顺序
    if err != nil {
        return nil, nil, err
    }
    fmt.Printf("New - Output: Hash:%x Salt:%x Pass:%x\n", h, s, pw)
    return h, s, nil
}

通过这一简单的修改，New 函数将生成与 Check 函数期望的计算方式一致的哈希值，从而使整个认证流程正常工作。

完整修正后的代码示例

package main

import (
    "golang.org/x/crypto/scrypt" // 更新为标准导入路径
    "crypto/hmac"
    "crypto/rand"
    "crypto/sha256"
    "crypto/subtle"
    "errors"
    "fmt"
    "io"
)

// Constants for scrypt.
const (
    KEYLENGTH = 32
    N         = 16384
    R         = 8
    P         = 1
)

// hash takes an HMAC key, a password and a salt (as byte slices)
// scrypt transforms the password and salt, and then HMAC transforms the result.
// Returns the resulting 256 bit hash.
func hash(hmk, pw, s []byte) (h []byte, err error) {
    sch, err := scrypt.Key(pw, s, N, R, P, KEYLENGTH)
    if err != nil {
        return nil, err
    }
    hmh := hmac.New(sha256.New, hmk)
    hmh.Write(sch)
    h = hmh.Sum(nil)
    // hmh.Reset() // 在此场景下非必需，因为hmh实例在函数结束后会被垃圾回收
    return h, nil
}

// Check takes an HMAC key, a hash to check, a password and a salt (as byte slices)
// Calls hash().
// Compares the resulting 256 bit hash against the check hash and returns a boolean.
func Check(hmk, h, pw, s []byte) (chk bool, err error) {
    fmt.Printf("Check - Input: Hash:%x HMAC:%x Salt:%x Pass:%x\n", h, hmk, s, pw)
    hchk, err := hash(hmk, pw, s)
    if err != nil {
        return false, err
    }
    fmt.Printf("Check - Computed: Hchk:%x\n", hchk)
    if subtle.ConstantTimeCompare(h, hchk) != 1 {
        return false, errors.New("Error: Hash verification failed")
    }
    return true, nil
}

// New takes an HMAC key and a password (as byte slices)
// Generates a new salt using "crypto/rand"
// Calls hash().
// Returns the resulting 256 bit hash and salt.
func New(hmk, pw []byte) (h, s []byte, err error) {
    s = make([]byte, KEYLENGTH)
    _, err = io.ReadFull(rand.Reader, s)
    if err != nil {
        return nil, nil, err
    }
    // 修正了参数顺序：hmk 作为第一个参数，pw 作为第二个参数
    h, err = hash(hmk, pw, s)
    if err != nil {
        return nil, nil, err
    }
    fmt.Printf("New - Output: Hash:%x Salt:%x Pass:%x\n", h, s, pw)
    return h, s, nil
}

func main() {
    pass := "pleaseletmein"

    // 示例中使用的硬编码哈希、盐值和HMAC密钥
    // 注意：在实际应用中，这些值应安全存储和管理，不应硬编码
    hash := []byte{
        0x6f, 0x38, 0x7b, 0x9c, 0xe3, 0x9d, 0x9, 0xff,
        0x6b, 0x1c, 0xc, 0xb5, 0x1, 0x67, 0x1d, 0x11,
        0x8f, 0x72, 0x78, 0x85, 0xca, 0x6, 0x50, 0xd0,
        0xe6, 0x8b, 0x12, 0x9c, 0x9d, 0xf4, 0xcb, 0x29,
    }

    salt := []byte{
        0x77, 0xd6, 0x57, 0x62, 0x38, 0x65, 0x7b, 0x20,
        0x3b, 0x19, 0xca, 0x42, 0xc1, 0x8a, 0x4, 0x97,
        0x48, 0x44, 0xe3, 0x7, 0x4a, 0xe8, 0xdf, 0xdf,
        0xfa, 0x3f, 0xed, 0xe2, 0x14, 0x42, 0xfc, 0xd0,
    }

    hmacKey := []byte{ // 变量名改为 hmacKey 以避免与包名冲突
        0x70, 0x23, 0xbd, 0xcb, 0x3a, 0xfd, 0x73, 0x48,
        0x46, 0x1c, 0x6, 0xcd, 0x81, 0xfd, 0x38, 0xeb,
        0xfd, 0xa8, 0xfb, 0xba, 0x90, 0x4f, 0x8e, 0x3e,
        0xa9, 0xb5, 0x43, 0xf6, 0x54, 0x5d, 0xa1, 0xf2,
    }

    fmt.Println("--- 验证已知值 ---")
    chk, err := Check(hmacKey, hash, []byte(pass), salt)
    if err != nil {
        fmt.Printf("错误: %s\n", err)
    }
    fmt.Printf("验证结果: %t\n\n", chk) // 预期为 true

    fmt.Println("--- 生成新哈希和盐值 ---")
    newHash, newSalt, err := New(hmacKey, []byte(pass))
    if err != nil {
        fmt.Printf("错误: %s\n", err)
    }
    fmt.Printf("新生成的哈希: %x\n新生成的盐值: %x\n\n", newHash, newSalt)

    fmt.Println("--- 验证新生成的值 ---")
    chk, err = Check(hmacKey, newHash, []byte(pass), newSalt)
    if err != nil {
        fmt.Printf("错误: %s\n", err)
    }
    fmt.Printf("验证结果: %t\n", chk) // 预期为 true
}

最佳实践与经验总结

这个案例提供了一些重要的编程经验和教训：

1. 参数一致性原则： 当函数有多个相同类型的参数时，务必确保在所有调用点都严格遵守参数的顺序和语义。尤其是在加密、哈希等对输入敏感的场景中，微小的差异都可能导致功能失效或安全漏洞。
2. 提升代码可读性与健壮性：
   • 自定义类型： 考虑为具有特定语义的 []byte 参数定义自定义类型，例如 type HMACKey []byte、type Password []byte、type Salt []byte。虽然Go语言在函数签名中不会强制这些自定义类型之间的严格区分（它们底层仍是 []byte），但它能显著提高代码的可读性，并在一定程度上帮助开发者识别潜在的参数混淆。
   • 明确的变量命名： 使用清晰、描述性的变量名，如 hmacKey 而不是简单的 hmac，以避免与包名或函数名冲突，并明确其用途。
   • 函数文档： 为函数编写详细的文档注释，说明每个参数的预期用途和顺序，这对于协作开发尤为重要。
3. 单元测试的价值： 正如原作者所说，这个问题是在编写单元测试时发现的。这再次印证了单元测试的重要性。对于核心功能，特别是涉及安全和数据完整性的部分，应编写全面的单元测试，覆盖所有可能的输入组合和边缘情况，以确保其行为符合预期。在本例中，一个简单的测试用例，即生成一个新哈希并立即尝试验证它，就能立即暴露此问题。
4. 代码审查： 定期的代码审查可以帮助团队成员发现此类隐性错误。多一双眼睛检查代码，尤其是对关键逻辑，能够有效提高代码质量和健壮性。

总结

在Go语言中构建密码认证系统时，使用Scrypt和HMAC是常见的安全实践。然而，即使是看似简单的参数顺序错误，也可能导致整个认证流程失效。通过本案例，我们深入理解了参数传递一致性的重要性，并学习了如何通过细致的代码审查、明确的函数定义、自定义类型以及全面的单元测试等最佳实践来避免此类问题。在处理加密相关代码时，严谨性和一致性是确保系统安全可靠的基石。