--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_KDF_SCRYPT - The scrypt EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF>
+API.
+
+The EVP_KDF_SCRYPT algorithm implements the scrypt password-based key
+derivation function, as described in RFC 7914. It is memory-hard in the sense
+that it deliberately requires a significant amount of RAM for efficient
+computation. The intention of this is to render brute forcing of passwords on
+systems that lack large amounts of main memory (such as GPUs or ASICs)
+computationally infeasible.
+
+scrypt provides three work factors that can be customized: N, r and p. N, which
+has to be a positive power of two, is the general work factor and scales CPU
+time in an approximately linear fashion. r is the block size of the internally
+used hash function and p is the parallelization factor. Both r and p need to be
+greater than zero. The amount of RAM that scrypt requires for its computation
+is roughly (128 * N * r * p) bytes.
+
+In the original paper of Colin Percival ("Stronger Key Derivation via
+Sequential Memory-Hard Functions", 2009), the suggested values that give a
+computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
+2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
+this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
+GHz), this computation takes about 3 seconds. When N, r or p are not specified,
+they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that
+may be used by scrypt defaults to 1025 MiB.
+
+=head2 Numeric identity
+
+B<EVP_KDF_SCRYPT> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_PASS>
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_N>
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_R>
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_P>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_N> expects one argument: C<uint64_t N>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_R> expects one argument: C<uint32_t r>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_P> expects one argument: C<uint32_t p>
+
+These controls configure the scrypt work factors N, r and p.
+
+EVP_KDF_ctrl_str() type strings: "N", "r" and "p", respectively.
+
+The corresponding value strings are expected to be decimal numbers.
+
+=back
+
+=head1 NOTES
+
+A context for scrypt can be obtained by calling:
+
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
+
+The output length of an scrypt key derivation is specified via the
+B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
+
+=head1 EXAMPLE
+
+This example derives a 64-byte long test vector using scrypt with the password
+"password", salt "NaCl" and N = 1024, r = 8, p = 16.
+
+ EVP_KDF_CTX *kctx;
+ unsigned char out[64];
+
+ kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
+
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_PASS, "password", (size_t)8) <= 0) {
+ error("EVP_KDF_CTRL_SET_PASS");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "NaCl", (size_t)4) <= 0) {
+ error("EVP_KDF_CTRL_SET_SALT");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_N, (uint64_t)1024) <= 0) {
+ error("EVP_KDF_CTRL_SET_SCRYPT_N");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_R, (uint32_t)8) <= 0) {
+ error("EVP_KDF_CTRL_SET_SCRYPT_R");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_P, (uint32_t)16) <= 0) {
+ error("EVP_KDF_CTRL_SET_SCRYPT_P");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+ error("EVP_KDF_derive");
+ }
+
+ {
+ const unsigned char expected[sizeof(out)] = {
+ 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
+ 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
+ 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
+ 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
+ 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
+ 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
+ 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
+ 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
+ };
+
+ assert(!memcmp(out, expected, sizeof(out)));
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+RFC 7914
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
projects / openssl.git / blobdiff