1const std = @import("std");
2const mem = std.mem;
3const maxInt = std.math.maxInt;
4const OutputTooLongError = std.crypto.errors.OutputTooLongError;
5const WeakParametersError = std.crypto.errors.WeakParametersError;
6
7// RFC 2898 Section 5.2
8//
9// FromSpec:
10//
11// PBKDF2 applies a pseudorandom function (see Appendix B.1 for an
12// example) to derive keys. The length of the derived key is essentially
13// unbounded. (However, the maximum effective search space for the
14// derived key may be limited by the structure of the underlying
15// pseudorandom function. See Appendix B.1 for further discussion.)
16// PBKDF2 is recommended for new applications.
17//
18// PBKDF2 (P, S, c, dk_len)
19//
20// Options: PRF underlying pseudorandom function (h_len
21// denotes the length in octets of the
22// pseudorandom function output)
23//
24// Input: P password, an octet string
25// S salt, an octet string
26// c iteration count, a positive integer
27// dk_len intended length in octets of the derived
28// key, a positive integer, at most
29// (2^32 - 1) * h_len
30//
31// Output: DK derived key, a dk_len-octet string
32
33// Based on Apple's CommonKeyDerivation, based originally on code by Damien Bergamini.
34
35/// Apply PBKDF2 to generate a key from a password.
36///
37/// PBKDF2 is defined in RFC 2898, and is a recommendation of NIST SP 800-132.
38///
39/// dk: Slice of appropriate size for generated key. Generally 16 or 32 bytes in length.
40/// May be uninitialized. All bytes will be overwritten.
41/// Maximum size is `maxInt(u32) * Hash.digest_length`
42/// It is a programming error to pass buffer longer than the maximum size.
43///
44/// password: Arbitrary sequence of bytes of any length, including empty.
45///
46/// salt: Arbitrary sequence of bytes of any length, including empty. A common length is 8 bytes.
47///
48/// rounds: Iteration count. Must be greater than 0. Common values range from 1,000 to 100,000.
49/// Larger iteration counts improve security by increasing the time required to compute
50/// the dk. It is common to tune this parameter to achieve approximately 100ms.
51///
52/// Prf: Pseudo-random function to use. A common choice is `std.crypto.auth.hmac.sha2.HmacSha256`.
53pub fn pbkdf2(dk: []u8, password: []const u8, salt: []const u8, rounds: u32, comptime Prf: type) (WeakParametersError || OutputTooLongError)!void {
54 if (rounds < 1) return error.WeakParameters;
55
56 const dk_len = dk.len;
57 const h_len = Prf.mac_length;
58 comptime std.debug.assert(h_len >= 1);
59
60 // FromSpec:
61 //
62 // 1. If dk_len > maxInt(u32) * h_len, output "derived key too long" and
63 // stop.
64 //
65 if (dk_len / h_len >= maxInt(u32)) {
66 // Counter starts at 1 and is 32 bit, so if we have to return more blocks, we would overflow
67 return error.OutputTooLong;
68 }
69
70 // FromSpec:
71 //
72 // 2. Let l be the number of h_len-long blocks of bytes in the derived key,
73 // rounding up, and let r be the number of bytes in the last
74 // block
75 //
76
77 const blocks_count: u32 = @intCast(@divCeil(dk_len, h_len));
78 var r = dk_len % h_len;
79 if (r == 0) {
80 r = h_len;
81 }
82
83 // FromSpec:
84 //
85 // 3. For each block of the derived key apply the function F defined
86 // below to the password P, the salt S, the iteration count c, and
87 // the block index to compute the block:
88 //
89 // T_1 = F (P, S, c, 1) ,
90 // T_2 = F (P, S, c, 2) ,
91 // ...
92 // T_l = F (P, S, c, l) ,
93 //
94 // where the function F is defined as the exclusive-or sum of the
95 // first c iterates of the underlying pseudorandom function PRF
96 // applied to the password P and the concatenation of the salt S
97 // and the block index i:
98 //
99 // F (P, S, c, i) = U_1 \xor U_2 \xor ... \xor U_c
100 //
101 // where
102 //
103 // U_1 = PRF (P, S || INT (i)) ,
104 // U_2 = PRF (P, U_1) ,
105 // ...
106 // U_c = PRF (P, U_{c-1}) .
107 //
108 // Here, INT (i) is a four-octet encoding of the integer i, most
109 // significant octet first.
110 //
111 // 4. Concatenate the blocks and extract the first dk_len octets to
112 // produce a derived key DK:
113 //
114 // DK = T_1 || T_2 || ... || T_l<0..r-1>
115
116 var block: u32 = 0;
117 while (block < blocks_count) : (block += 1) {
118 var prev_block: [h_len]u8 = undefined;
119 var new_block: [h_len]u8 = undefined;
120
121 // U_1 = PRF (P, S || INT (i))
122 const block_index = mem.toBytes(mem.nativeToBig(u32, block + 1)); // Block index starts at 0001
123 var ctx = Prf.init(password);
124 ctx.update(salt);
125 ctx.update(block_index[0..]);
126 ctx.final(prev_block[0..]);
127
128 // Choose portion of DK to write into (T_n) and initialize
129 const offset = block * h_len;
130 const block_len = if (block != blocks_count - 1) h_len else r;
131 const dk_block: []u8 = dk[offset..][0..block_len];
132 @memcpy(dk_block, prev_block[0..dk_block.len]);
133
134 var i: u32 = 1;
135 while (i < rounds) : (i += 1) {
136 // U_c = PRF (P, U_{c-1})
137 Prf.create(&new_block, prev_block[0..], password);
138 prev_block = new_block;
139
140 // F (P, S, c, i) = U_1 \xor U_2 \xor ... \xor U_c
141 for (dk_block, 0..) |_, j| {
142 dk_block[j] ^= new_block[j];
143 }
144 }
145 }
146}
147
148const htest = @import("test.zig");
149const HmacSha1 = std.crypto.auth.hmac.HmacSha1;
150
151// RFC 6070 PBKDF2 HMAC-SHA1 Test Vectors
152
153test "RFC 6070 one iteration" {
154 const p = "password";
155 const s = "salt";
156 const c = 1;
157 const dk_len = 20;
158
159 var dk: [dk_len]u8 = undefined;
160
161 try pbkdf2(&dk, p, s, c, HmacSha1);
162
163 const expected = "0c60c80f961f0e71f3a9b524af6012062fe037a6";
164
165 try htest.assertEqual(expected, dk[0..]);
166}
167
168test "RFC 6070 two iterations" {
169 const p = "password";
170 const s = "salt";
171 const c = 2;
172 const dk_len = 20;
173
174 var dk: [dk_len]u8 = undefined;
175
176 try pbkdf2(&dk, p, s, c, HmacSha1);
177
178 const expected = "ea6c014dc72d6f8ccd1ed92ace1d41f0d8de8957";
179
180 try htest.assertEqual(expected, dk[0..]);
181}
182
183test "RFC 6070 4096 iterations" {
184 const p = "password";
185 const s = "salt";
186 const c = 4096;
187 const dk_len = 20;
188
189 var dk: [dk_len]u8 = undefined;
190
191 try pbkdf2(&dk, p, s, c, HmacSha1);
192
193 const expected = "4b007901b765489abead49d926f721d065a429c1";
194
195 try htest.assertEqual(expected, dk[0..]);
196}
197
198test "RFC 6070 16,777,216 iterations" {
199 // These iteration tests are slow so we always skip them. Results have been verified.
200 if (true) {
201 return error.SkipZigTest;
202 }
203
204 const p = "password";
205 const s = "salt";
206 const c = 16777216;
207 const dk_len = 20;
208
209 var dk: [dk_len]u8 = @splat(0);
210
211 try pbkdf2(&dk, p, s, c, HmacSha1);
212
213 const expected = "eefe3d61cd4da4e4e9945b3d6ba2158c2634e984";
214
215 try htest.assertEqual(expected, dk[0..]);
216}
217
218test "RFC 6070 multi-block salt and password" {
219 const p = "passwordPASSWORDpassword";
220 const s = "saltSALTsaltSALTsaltSALTsaltSALTsalt";
221 const c = 4096;
222 const dk_len = 25;
223
224 var dk: [dk_len]u8 = undefined;
225
226 try pbkdf2(&dk, p, s, c, HmacSha1);
227
228 const expected = "3d2eec4fe41c849b80c8d83662c0e44a8b291a964cf2f07038";
229
230 try htest.assertEqual(expected, dk[0..]);
231}
232
233test "RFC 6070 embedded NUL" {
234 const p = "pass\x00word";
235 const s = "sa\x00lt";
236 const c = 4096;
237 const dk_len = 16;
238
239 var dk: [dk_len]u8 = undefined;
240
241 try pbkdf2(&dk, p, s, c, HmacSha1);
242
243 const expected = "56fa6aa75548099dcc37d7f03425e0c3";
244
245 try htest.assertEqual(expected, dk[0..]);
246}
247
248test "Very large dk_len" {
249 // This test allocates 8GB of memory and is expected to take several hours to run.
250 if (true) {
251 return error.SkipZigTest;
252 }
253 const p = "password";
254 const s = "salt";
255 const c = 1;
256 const dk_len = 1 << 33;
257
258 const dk = try std.testing.allocator.alloc(u8, dk_len);
259 defer std.testing.allocator.free(dk);
260
261 // Just verify this doesn't crash with an overflow
262 try pbkdf2(dk, p, s, c, HmacSha1);
263}