]>
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 | |
ccd7115a P |
37 | "ID-SCRYPT" is the name for this implementation; it |
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 | ||
ccd7115a | 46 | =item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string> |
5a285add | 47 | |
ccd7115a | 48 | =item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string> |
5a285add | 49 | |
ccd7115a | 50 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. |
5a285add | 51 | |
ccd7115a | 52 | =item B<OSSL_KDF_PARAM_SCRYPT_N> ("n") <int> |
5a285add | 53 | |
ccd7115a | 54 | =item B<OSSL_KDF_PARAM_SCRYPT_R> ("r") <int> |
5a285add | 55 | |
ccd7115a | 56 | =item B<OSSL_KDF_PARAM_SCRYPT_P> ("p") <int> |
5a285add | 57 | |
ccd7115a P |
58 | These parameters configure the scrypt work factors N, r and p. |
59 | N is a parameter of type uint64_t. | |
60 | Both r and p are parameters of type 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 | ||
ccd7115a P |
68 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL); |
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 |
ccd7115a | 72 | B<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 | ||
84 | kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL); | |
85 | kctx = EVP_KDF_CTX_new(kdf); | |
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(); | |
a218770d P |
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 | ||
5a285add | 118 | EVP_KDF_CTX_free(kctx); |
6d8aba7b JB |
119 | |
120 | =head1 CONFORMING TO | |
121 | ||
122 | RFC 7914 | |
123 | ||
124 | =head1 SEE ALSO | |
125 | ||
ccd7115a P |
126 | L<EVP_KDF>, |
127 | L<EVP_KDF-CTX_new_id(3)>, | |
128 | L<EVP_KDF-CTX_free(3)>, | |
129 | L<EVP_KDF-ctrl(3)>, | |
130 | L<EVP_KDF-derive(3)>, | |
131 | L<EVP_KDF-CTX(3)/PARAMETERS> | |
6d8aba7b JB |
132 | |
133 | =head1 COPYRIGHT | |
134 | ||
a8ca496d | 135 | Copyright 2017-2018 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 |