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