跳转到内容

std.crypto.pbkdf2

标准库Zig 0.17.1官方原文
源码std/crypto/pbkdf2.zig

第 1 行

std.crypto.pbkdf2.HmacSha1

别名

第 149 行

别名目标 std.crypto.hmac.HmacSha1

std.crypto.pbkdf2.htest

常量

第 148 行

std.crypto.pbkdf2.maxInt

别名

第 3 行

别名目标 std.math.maxInt

std.crypto.pbkdf2.mem

别名

第 2 行

别名目标 std.mem

std.crypto.pbkdf2.OutputTooLongError

别名

第 4 行

别名目标 std.crypto.errors.OutputTooLongError

std.crypto.pbkdf2.pbkdf2

函数

第 53 行

应用 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

别名

第 1 行

别名目标 std

std.crypto.pbkdf2.WeakParametersError

别名

第 5 行

别名目标 std.crypto.errors.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);
}