]>
Commit | Line | Data |
---|---|---|
6d8aba7b JB |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ccd7115a | 5 | EVP_KDF-SCRYPT - The scrypt EVP_KDF implementation |
6d8aba7b | 6 | |
6d8aba7b JB |
7 | =head1 DESCRIPTION |
8 | ||
5a285add DM |
9 | Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF> |
10 | API. | |
11 | ||
ccd7115a | 12 | The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key |
6d8aba7b JB |
13 | derivation function, as described in RFC 7914. It is memory-hard in the sense |
14 | that it deliberately requires a significant amount of RAM for efficient | |
15 | computation. The intention of this is to render brute forcing of passwords on | |
16 | systems that lack large amounts of main memory (such as GPUs or ASICs) | |
17 | computationally infeasible. | |
18 | ||
19 | scrypt provides three work factors that can be customized: N, r and p. N, which | |
20 | has to be a positive power of two, is the general work factor and scales CPU | |
21 | time in an approximately linear fashion. r is the block size of the internally | |
22 | used hash function and p is the parallelization factor. Both r and p need to be | |
23 | greater than zero. The amount of RAM that scrypt requires for its computation | |
24 | is roughly (128 * N * r * p) bytes. | |
25 | ||
26 | In the original paper of Colin Percival ("Stronger Key Derivation via | |
27 | Sequential Memory-Hard Functions", 2009), the suggested values that give a | |
28 | computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = | |
29 | 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for | |
30 | this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5 | |
31 | GHz), this computation takes about 3 seconds. When N, r or p are not specified, | |
5a285add | 32 | they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that |
6d8aba7b JB |
33 | may be used by scrypt defaults to 1025 MiB. |
34 | ||
ccd7115a | 35 | =head2 Identity |
5a285add | 36 | |
e44192d1 | 37 | "SCRYPT" is the name for this implementation; it |
ccd7115a | 38 | can be used with the EVP_KDF_fetch() function. |
5a285add | 39 | |
ccd7115a | 40 | =head2 Supported parameters |
5a285add | 41 | |
ccd7115a | 42 | The supported parameters are: |
5a285add DM |
43 | |
44 | =over 4 | |
45 | ||
0c452a51 | 46 | =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string> |
5a285add | 47 | |
0c452a51 | 48 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> |
5a285add | 49 | |
ccd7115a | 50 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. |
5a285add | 51 | |
0c452a51 | 52 | =item "n" (B<OSSL_KDF_PARAM_SCRYPT_N>) <unsigned integer> |
5a285add | 53 | |
0c452a51 | 54 | =item "r" (B<OSSL_KDF_PARAM_SCRYPT_R>) <unsigned integer> |
5a285add | 55 | |
0c452a51 | 56 | =item "p" (B<OSSL_KDF_PARAM_SCRYPT_P>) <unsigned integer> |
5a285add | 57 | |
ccd7115a | 58 | These parameters configure the scrypt work factors N, r and p. |
e7f2dac9 P |
59 | N is a parameter of type B<uint64_t>. |
60 | Both r and p are parameters of type B<uint32_t>. | |
5a285add DM |
61 | |
62 | =back | |
63 | ||
6d8aba7b JB |
64 | =head1 NOTES |
65 | ||
6d8aba7b JB |
66 | A context for scrypt can be obtained by calling: |
67 | ||
e44192d1 | 68 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); |
660c5344 | 69 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); |
6d8aba7b | 70 | |
a8ca496d | 71 | The output length of an scrypt key derivation is specified via the |
86913ef7 | 72 | "keylen" parameter to the L<EVP_KDF_derive(3)> function. |
6d8aba7b | 73 | |
cda77422 | 74 | =head1 EXAMPLES |
6d8aba7b | 75 | |
5a285add | 76 | This example derives a 64-byte long test vector using scrypt with the password |
6d8aba7b JB |
77 | "password", salt "NaCl" and N = 1024, r = 8, p = 16. |
78 | ||
ccd7115a | 79 | EVP_KDF *kdf; |
5a285add | 80 | EVP_KDF_CTX *kctx; |
6d8aba7b | 81 | unsigned char out[64]; |
ccd7115a P |
82 | OSSL_PARAM params[6], *p = params; |
83 | ||
e44192d1 | 84 | kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); |
660c5344 | 85 | kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a P |
86 | EVP_KDF_free(kdf); |
87 | ||
88 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, | |
89 | "password", (size_t)8); | |
90 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
91 | "NaCl", (size_t)4); | |
92 | *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024); | |
93 | *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8); | |
94 | *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16); | |
95 | *p = OSSL_PARAM_construct_end(); | |
660c5344 MC |
96 | if (EVP_KDF_CTX_set_params(kctx, params) <= 0) { |
97 | error("EVP_KDF_CTX_set_params"); | |
6d8aba7b | 98 | } |
5a285add DM |
99 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { |
100 | error("EVP_KDF_derive"); | |
6d8aba7b JB |
101 | } |
102 | ||
103 | { | |
104 | const unsigned char expected[sizeof(out)] = { | |
105 | 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00, | |
106 | 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe, | |
107 | 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30, | |
108 | 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62, | |
109 | 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88, | |
110 | 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda, | |
111 | 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d, | |
112 | 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40 | |
113 | }; | |
114 | ||
115 | assert(!memcmp(out, expected, sizeof(out))); | |
116 | } | |
117 | ||
660c5344 | 118 | EVP_KDF_CTX_free(kctx); |
6d8aba7b JB |
119 | |
120 | =head1 CONFORMING TO | |
121 | ||
122 | RFC 7914 | |
123 | ||
124 | =head1 SEE ALSO | |
125 | ||
4c04e7b1 | 126 | L<EVP_KDF(3)>, |
660c5344 MC |
127 | L<EVP_KDF_CTX_new(3)>, |
128 | L<EVP_KDF_CTX_free(3)>, | |
129 | L<EVP_KDF_CTX_set_params(3)>, | |
4c04e7b1 P |
130 | L<EVP_KDF_derive(3)>, |
131 | L<EVP_KDF(3)/PARAMETERS> | |
6d8aba7b JB |
132 | |
133 | =head1 COPYRIGHT | |
134 | ||
fbd2ece1 | 135 | Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. |
6d8aba7b | 136 | |
3187791e | 137 | Licensed under the Apache License 2.0 (the "License"). You may not use |
6d8aba7b JB |
138 | this file except in compliance with the License. You can obtain a copy |
139 | in the file LICENSE in the source distribution or at | |
140 | L<https://www.openssl.org/source/license.html>. | |
141 | ||
142 | =cut |