std.crypto.pbkdf2.HmacSha1
别名
std.crypto.pbkdf2.htest
常量
std.crypto.pbkdf2.maxInt
别名
别名目标 std.math.maxInt
std.crypto.pbkdf2.mem
别名
别名目标 std.mem
std.crypto.pbkdf2.OutputTooLongError
别名
std.crypto.pbkdf2.pbkdf2
函数
应用 PBKDF2 从密码生成密钥。
PBKDF2 定义于 RFC 2898,并为 NIST SP 800-132 所推荐。
dk:用于存放生成密钥、大小适当的切片,通常长 16 或 32 字节。
可以未初始化;所有字节均会被覆写。
最大大小为 maxInt(u32) * Hash.digest_length。
传入长度超过此上限的缓冲区属于编程错误。
password:任意长度的字节序列,可以为空。
salt:任意长度的字节序列,可以为空。常见长度为 8 字节。
rounds:迭代次数,必须大于 0。常见取值范围为 1,000 至 100,000。 增大迭代次数会增加计算 dk 所需的时间,从而提升安全性。通常调整此参数,使计算耗时约 100ms。
Prf:使用的伪随机函数。常见选择为 std.crypto.auth.hmac.sha2.HmacSha256。
pub fn pbkdf2(dk: []u8, password: []const u8, salt: []const u8, rounds: u32, comptime Prf: type) (WeakParametersError || OutputTooLongError)!void
参数
dk: []u8
password: []const u8
salt: []const u8
rounds: u32
Prf: type
std.crypto.pbkdf2.std
别名
别名目标 std
std.crypto.pbkdf2.WeakParametersError
别名
源码
std/crypto/pbkdf2.zig
const std = @import("std");
const mem = std.mem;
const maxInt = std.math.maxInt;
const OutputTooLongError = std.crypto.errors.OutputTooLongError;
const WeakParametersError = std.crypto.errors.WeakParametersError;
// RFC 2898 第 5.2 节
//
// 引自规范:
//
// PBKDF2 应用伪随机函数(示例见附录 B.1)
// 派生密钥。派生密钥的长度基本上
// 不受限制。(不过,派生密钥的最大有效搜索空间
// 可能受底层伪随机函数的结构
// 限制。进一步讨论见附录 B.1。)
// 建议新应用使用 PBKDF2。
//
// PBKDF2 (P, S, c, dk_len)
//
// 选项: PRF 底层伪随机函数,h_len
// 表示该伪随机函数输出的
// 字节数
//
// 输入: P 密码,字节串
// S 盐,字节串
// c 迭代次数,正整数
// dk_len 期望的派生密钥字节
// 长度,正整数,最大为
// (2^32 - 1) * h_len
//
// 输出: DK 派生密钥,长度为 dk_len 的字节串
// 基于 Apple 的 CommonKeyDerivation,最初基于 Damien Bergamini 的代码。
/// 应用 PBKDF2 从密码生成密钥。
///
/// PBKDF2 定义于 RFC 2898,并为 NIST SP 800-132 所推荐。
///
/// dk:用于存放生成密钥、大小适当的切片,通常长 16 或 32 字节。
/// 可以未初始化;所有字节均会被覆写。
/// 最大大小为 `maxInt(u32) * Hash.digest_length`。
/// 传入长度超过此上限的缓冲区属于编程错误。
///
/// password:任意长度的字节序列,可以为空。
///
/// salt:任意长度的字节序列,可以为空。常见长度为 8 字节。
///
/// rounds:迭代次数,必须大于 0。常见取值范围为 1,000 至 100,000。
/// 增大迭代次数会增加计算
/// dk 所需的时间,从而提升安全性。通常调整此参数,使计算耗时约 100ms。
///
/// Prf:使用的伪随机函数。常见选择为 `std.crypto.auth.hmac.sha2.HmacSha256`。
pub fn pbkdf2(dk: []u8, password: []const u8, salt: []const u8, rounds: u32, comptime Prf: type) (WeakParametersError || OutputTooLongError)!void {
if (rounds < 1) return error.WeakParameters;
const dk_len = dk.len;
const h_len = Prf.mac_length;
comptime std.debug.assert(h_len >= 1);
// 规范内容:
//
// 1. 若 dk_len > maxInt(u32) * h_len,输出 "derived key too long",并
// 停止。
//
if (dk_len / h_len >= maxInt(u32)) {
// 计数器从 1 开始且为 32 位,因此若必须返回更多块就会溢出
return error.OutputTooLong;
}
// 摘自规范:
//
// 2. 令 l 为派生密钥中长度为 h_len 的字节块数量,
// 向上取整;令 r 为最后一个块
// 的字节数。
//
const blocks_count: u32 = @intCast(@divCeil(dk_len, h_len));
var r = dk_len % h_len;
if (r == 0) {
r = h_len;
}
// 摘自规范:
//
// 3. 对派生密钥的每个块,将下述函数 F 应用于口令 P、盐 S、迭代次数 c 和块索引,计算该块:
//
// T_1 = F (P, S, c, 1) ,
// T_2 = F (P, S, c, 2) ,
// ...
// T_l = F (P, S, c, l) ,
//
// 函数 F 定义为底层伪随机函数 PRF 的前 c 次迭代结果的异或和。PRF 的输入为口令 P,以及盐 S 与块索引 i 的拼接:
//
// F (P, S, c, i) = U_1 \xor U_2 \xor ... \xor U_c
//
// 其中:
//
// U_1 = PRF (P, S || INT (i)) ,
// U_2 = PRF (P, U_1) ,
// ...
// U_c = PRF (P, U_{c-1}) .
//
// INT (i) 是整数 i 的四字节编码,最高有效字节在前。
//
// 4. 拼接各个块,并取前 dk_len 个字节,得到派生密钥 DK:
//
// DK = T_1 || T_2 || ... || T_l<0..r-1>
//
//
//
//
//
//
//
var block: u32 = 0;
while (block < blocks_count) : (block += 1) {
var prev_block: [h_len]u8 = undefined;
var new_block: [h_len]u8 = undefined;
// U_1 = PRF (P, S || INT (i))
const block_index = mem.toBytes(mem.nativeToBig(u32, block + 1)); // 块索引从 0001 开始
var ctx = Prf.init(password);
ctx.update(salt);
ctx.update(block_index[0..]);
ctx.final(prev_block[0..]);
// 选择 DK 中待写入的部分(T_n)并初始化。
const offset = block * h_len;
const block_len = if (block != blocks_count - 1) h_len else r;
const dk_block: []u8 = dk[offset..][0..block_len];
@memcpy(dk_block, prev_block[0..dk_block.len]);
var i: u32 = 1;
while (i < rounds) : (i += 1) {
// U_c = PRF (P, U_{c-1})
Prf.create(&new_block, prev_block[0..], password);
prev_block = new_block;
// F (P, S, c, i) = U_1 \xor U_2 \xor ... \xor U_c
for (dk_block, 0..) |_, j| {
dk_block[j] ^= new_block[j];
}
}
}
}
const htest = @import("test.zig");
const HmacSha1 = std.crypto.auth.hmac.HmacSha1;
// RFC 6070 PBKDF2 HMAC-SHA1 测试向量
test "RFC 6070 one iteration" {
const p = "password";
const s = "salt";
const c = 1;
const dk_len = 20;
var dk: [dk_len]u8 = undefined;
try pbkdf2(&dk, p, s, c, HmacSha1);
const expected = "0c60c80f961f0e71f3a9b524af6012062fe037a6";
try htest.assertEqual(expected, dk[0..]);
}
test "RFC 6070 two iterations" {
const p = "password";
const s = "salt";
const c = 2;
const dk_len = 20;
var dk: [dk_len]u8 = undefined;
try pbkdf2(&dk, p, s, c, HmacSha1);
const expected = "ea6c014dc72d6f8ccd1ed92ace1d41f0d8de8957";
try htest.assertEqual(expected, dk[0..]);
}
test "RFC 6070 4096 iterations" {
const p = "password";
const s = "salt";
const c = 4096;
const dk_len = 20;
var dk: [dk_len]u8 = undefined;
try pbkdf2(&dk, p, s, c, HmacSha1);
const expected = "4b007901b765489abead49d926f721d065a429c1";
try htest.assertEqual(expected, dk[0..]);
}
test "RFC 6070 16,777,216 iterations" {
// 这些迭代测试较慢,因此始终跳过。结果已验证。
if (true) {
return error.SkipZigTest;
}
const p = "password";
const s = "salt";
const c = 16777216;
const dk_len = 20;
var dk: [dk_len]u8 = @splat(0);
try pbkdf2(&dk, p, s, c, HmacSha1);
const expected = "eefe3d61cd4da4e4e9945b3d6ba2158c2634e984";
try htest.assertEqual(expected, dk[0..]);
}
test "RFC 6070 multi-block salt and password" {
const p = "passwordPASSWORDpassword";
const s = "saltSALTsaltSALTsaltSALTsaltSALTsalt";
const c = 4096;
const dk_len = 25;
var dk: [dk_len]u8 = undefined;
try pbkdf2(&dk, p, s, c, HmacSha1);
const expected = "3d2eec4fe41c849b80c8d83662c0e44a8b291a964cf2f07038";
try htest.assertEqual(expected, dk[0..]);
}
test "RFC 6070 embedded NUL" {
const p = "pass\x00word";
const s = "sa\x00lt";
const c = 4096;
const dk_len = 16;
var dk: [dk_len]u8 = undefined;
try pbkdf2(&dk, p, s, c, HmacSha1);
const expected = "56fa6aa75548099dcc37d7f03425e0c3";
try htest.assertEqual(expected, dk[0..]);
}
test "Very large dk_len" {
// 此测试会分配 8GB 内存,预期需要数小时运行。
if (true) {
return error.SkipZigTest;
}
const p = "password";
const s = "salt";
const c = 1;
const dk_len = 1 << 33;
const dk = try std.testing.allocator.alloc(u8, dk_len);
defer std.testing.allocator.free(dk);
// 仅验证溢出时不会崩溃
try pbkdf2(dk, p, s, c, HmacSha1);
}