Go crypto/pbkdf2.Key 派生密码密钥的参数配置方法

Go 1.24 把 PBKDF2 放进了标准库，调用 crypto/pbkdf2.Key 时先记住这一组顺序：hash、password、salt、iter、keyLength。哈希决定每轮计算方式，salt 用来区分每条记录，iter 控制计算成本，keyLength 必须和下游密钥接口的长度一致。官方 API 说明见 https://pkg.go.dev/crypto/pbkdf2。

参数顺序先定清楚

标准库签名是 Key(h func() hash.Hash, password, salt []byte, iter, keyLength int) ([]byte, error)。旧版扩展包常见的形式把密码和 salt 放在前面、把哈希构造器放到末尾，两者不能只靠编辑器自动补全来判断。更稳妥的做法是把调用点旁边的用途写清楚：密码是输入秘密，salt 是公开随机值，iter 是成本参数，keyLength 是最终输出字节数。

四个参数的配置方法

salt 的“公开”不等于可以复用。它的作用是让相同密码在不同记录上得到不同派生结果；真正需要保护的是密码和派生密钥。若系统还要保存算法、hash 名称、iter 和 keyLength，应把这些字段作为记录的一部分，而不是依赖代码里的当前默认值。

一段可落地的派生代码

下面示例把 salt 的生成、参数选择和错误传播放在同一个边界内。100000 只是演示起点，不代表所有机器和业务都适合；上线前要用目标环境的实测耗时调整。

package main

import (
    "crypto/pbkdf2"
    "crypto/rand"
    "crypto/sha256"
    "fmt"
)

func deriveKey(password string) ([]byte, []byte, error) {
    salt := make([]byte, 16)
    // salt 不需要保密，但每条记录都应独立随机生成并随元数据保存。
    if _, err := rand.Read(salt); err != nil {
        return nil, nil, fmt.Errorf("生成 salt: %w", err)
    }

    // 100000 只是校准起点；生产值应由目标机器的可接受耗时决定。
    key, err := pbkdf2.Key(sha256.New, []byte(password), salt, 100_000, 32)
    if err != nil {
        return nil, nil, fmt.Errorf("派生密钥: %w", err)
    }
    return key, salt, nil
}

这里选择 SHA-256 和 32 字节，是因为示例假定下游需要固定长度的密钥；如果消费方要求其他长度，应先改接口契约再改 keyLength。不要把 PBKDF2 的输出直接当成“万能密码存储方案”，本篇只解决 API 参数配置；密码存储协议、登录策略和密钥轮换属于另外的设计边界。

迁移、错误边界与精简问答

从 golang.org/x/crypto/pbkdf2 迁移时，先在数据结构中确认旧记录使用的 hash、salt、iter 与 keyLength，再替换调用。标准库函数可能返回错误，调用方不能只接收一个字节切片就忽略失败。特别是非正的 keyLength、超过实现边界的长度，或不符合约定的迭代参数，都应在业务边界转换成可观测的配置错误；不要用静默默认值掩盖。

iter 越大就一定越安全吗？

不是。它提高每次派生的计算成本，同时也提高正常请求的延迟。应按目标机器和业务吞吐做基准测试，并在记录中保存参数版本，让后续升级可以逐步迁移。

salt 需要加密保存吗？

通常不需要保密。salt 的关键要求是随机、独立、随记录保存；真正不能泄露的是密码和派生密钥。把 salt 当成普通元数据保存即可，但不要把它改成固定常量。

keyLength 能随便填一个大数吗？

不能。它必须是正数，并且要符合函数实现的上限；更重要的是要匹配下游接口。为了 AES-256 选择 32 字节只是一个具体契约示例，不代表所有加密或校验场景都应使用同一长度。