| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | EVP_KDF-SCRYPT - The scrypt EVP_KDF implementation
|
|---|
| 6 |
|
|---|
| 7 | =head1 DESCRIPTION
|
|---|
| 8 |
|
|---|
| 9 | Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF>
|
|---|
| 10 | API.
|
|---|
| 11 |
|
|---|
| 12 | The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key
|
|---|
| 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,
|
|---|
| 32 | they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that
|
|---|
| 33 | may be used by scrypt defaults to 1025 MiB.
|
|---|
| 34 |
|
|---|
| 35 | =head2 Identity
|
|---|
| 36 |
|
|---|
| 37 | "SCRYPT" is the name for this implementation; it
|
|---|
| 38 | can be used with the EVP_KDF_fetch() function.
|
|---|
| 39 |
|
|---|
| 40 | =head2 Supported parameters
|
|---|
| 41 |
|
|---|
| 42 | The supported parameters are:
|
|---|
| 43 |
|
|---|
| 44 | =over 4
|
|---|
| 45 |
|
|---|
| 46 | =item "pass" (B<OSSL_KDF_PARAM_PASSWORD>) <octet string>
|
|---|
| 47 |
|
|---|
| 48 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
|
|---|
| 49 |
|
|---|
| 50 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
|
|---|
| 51 |
|
|---|
| 52 | =item "n" (B<OSSL_KDF_PARAM_SCRYPT_N>) <unsigned integer>
|
|---|
| 53 |
|
|---|
| 54 | =item "r" (B<OSSL_KDF_PARAM_SCRYPT_R>) <unsigned integer>
|
|---|
| 55 |
|
|---|
| 56 | =item "p" (B<OSSL_KDF_PARAM_SCRYPT_P>) <unsigned integer>
|
|---|
| 57 |
|
|---|
| 58 | =item "maxmem_bytes" (B<OSSL_KDF_PARAM_SCRYPT_MAXMEM>) <unsigned integer>
|
|---|
| 59 |
|
|---|
| 60 | These parameters configure the scrypt work factors N, r, maxmem and p.
|
|---|
| 61 | Both N and maxmem_bytes are parameters of type B<uint64_t>.
|
|---|
| 62 | Both r and p are parameters of type B<uint32_t>.
|
|---|
| 63 |
|
|---|
| 64 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
|
|---|
| 65 |
|
|---|
| 66 | This can be used to set the property query string when fetching the
|
|---|
| 67 | fixed digest internally. NULL is used if this value is not set.
|
|---|
| 68 |
|
|---|
| 69 | =back
|
|---|
| 70 |
|
|---|
| 71 | =head1 NOTES
|
|---|
| 72 |
|
|---|
| 73 | A context for scrypt can be obtained by calling:
|
|---|
| 74 |
|
|---|
| 75 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
|
|---|
| 76 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
|
|---|
| 77 |
|
|---|
| 78 | The output length of an scrypt key derivation is specified via the
|
|---|
| 79 | "keylen" parameter to the L<EVP_KDF_derive(3)> function.
|
|---|
| 80 |
|
|---|
| 81 | =head1 EXAMPLES
|
|---|
| 82 |
|
|---|
| 83 | This example derives a 64-byte long test vector using scrypt with the password
|
|---|
| 84 | "password", salt "NaCl" and N = 1024, r = 8, p = 16.
|
|---|
| 85 |
|
|---|
| 86 | EVP_KDF *kdf;
|
|---|
| 87 | EVP_KDF_CTX *kctx;
|
|---|
| 88 | unsigned char out[64];
|
|---|
| 89 | OSSL_PARAM params[6], *p = params;
|
|---|
| 90 |
|
|---|
| 91 | kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL);
|
|---|
| 92 | kctx = EVP_KDF_CTX_new(kdf);
|
|---|
| 93 | EVP_KDF_free(kdf);
|
|---|
| 94 |
|
|---|
| 95 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
|
|---|
| 96 | "password", (size_t)8);
|
|---|
| 97 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
|
|---|
| 98 | "NaCl", (size_t)4);
|
|---|
| 99 | *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024);
|
|---|
| 100 | *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8);
|
|---|
| 101 | *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16);
|
|---|
| 102 | *p = OSSL_PARAM_construct_end();
|
|---|
| 103 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
|
|---|
| 104 | error("EVP_KDF_derive");
|
|---|
| 105 | }
|
|---|
| 106 |
|
|---|
| 107 | {
|
|---|
| 108 | const unsigned char expected[sizeof(out)] = {
|
|---|
| 109 | 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
|
|---|
| 110 | 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
|
|---|
| 111 | 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
|
|---|
| 112 | 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
|
|---|
| 113 | 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
|
|---|
| 114 | 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
|
|---|
| 115 | 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
|
|---|
| 116 | 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
|
|---|
| 117 | };
|
|---|
| 118 |
|
|---|
| 119 | assert(!memcmp(out, expected, sizeof(out)));
|
|---|
| 120 | }
|
|---|
| 121 |
|
|---|
| 122 | EVP_KDF_CTX_free(kctx);
|
|---|
| 123 |
|
|---|
| 124 | =head1 CONFORMING TO
|
|---|
| 125 |
|
|---|
| 126 | RFC 7914
|
|---|
| 127 |
|
|---|
| 128 | =head1 SEE ALSO
|
|---|
| 129 |
|
|---|
| 130 | L<EVP_KDF(3)>,
|
|---|
| 131 | L<EVP_KDF_CTX_new(3)>,
|
|---|
| 132 | L<EVP_KDF_CTX_free(3)>,
|
|---|
| 133 | L<EVP_KDF_CTX_set_params(3)>,
|
|---|
| 134 | L<EVP_KDF_derive(3)>,
|
|---|
| 135 | L<EVP_KDF(3)/PARAMETERS>
|
|---|
| 136 |
|
|---|
| 137 | =head1 COPYRIGHT
|
|---|
| 138 |
|
|---|
| 139 | Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 140 |
|
|---|
| 141 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 142 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 143 | in the file LICENSE in the source distribution or at
|
|---|
| 144 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 145 |
|
|---|
| 146 | =cut
|
|---|
