1=pod 2 3=head1 NAME 4 5EVP_KDF-SCRYPT - The scrypt EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF> 10API. 11 12The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key 13derivation function, as described in RFC 7914. It is memory-hard in the sense 14that it deliberately requires a significant amount of RAM for efficient 15computation. The intention of this is to render brute forcing of passwords on 16systems that lack large amounts of main memory (such as GPUs or ASICs) 17computationally infeasible. 18 19scrypt provides three work factors that can be customized: N, r and p. N, which 20has to be a positive power of two, is the general work factor and scales CPU 21time in an approximately linear fashion. r is the block size of the internally 22used hash function and p is the parallelization factor. Both r and p need to be 23greater than zero. The amount of RAM that scrypt requires for its computation 24is roughly (128 * N * r * p) bytes. 25 26In the original paper of Colin Percival ("Stronger Key Derivation via 27Sequential Memory-Hard Functions", 2009), the suggested values that give a 28computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N = 292^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for 30this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5 31GHz), this computation takes about 3 seconds. When N, r or p are not specified, 32they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that 33may be used by scrypt defaults to 1025 MiB. 34 35=head2 Identity 36 37"SCRYPT" is the name for this implementation; it 38can be used with the EVP_KDF_fetch() function. 39 40=head2 Supported parameters 41 42The 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 50These 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 60These parameters configure the scrypt work factors N, r, maxmem and p. 61Both N and maxmem_bytes are parameters of type B<uint64_t>. 62Both r and p are parameters of type B<uint32_t>. 63 64=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 65 66This can be used to set the property query string when fetching the 67fixed digest internally. NULL is used if this value is not set. 68 69=back 70 71=head1 NOTES 72 73A 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 78The 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 83This 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 126RFC 7914 127 128=head1 SEE ALSO 129 130L<EVP_KDF(3)>, 131L<EVP_KDF_CTX_new(3)>, 132L<EVP_KDF_CTX_free(3)>, 133L<EVP_KDF_CTX_set_params(3)>, 134L<EVP_KDF_derive(3)>, 135L<EVP_KDF(3)/PARAMETERS> 136 137=head1 HISTORY 138 139This functionality was added in OpenSSL 3.0. 140 141=head1 COPYRIGHT 142 143Copyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved. 144 145Licensed under the Apache License 2.0 (the "License"). You may not use 146this file except in compliance with the License. You can obtain a copy 147in the file LICENSE in the source distribution or at 148L<https://www.openssl.org/source/license.html>. 149 150=cut 151
