From: Johannes Bauer Date: Mon, 7 Aug 2017 22:21:30 +0000 (+0200) Subject: Add documentation for the scrypt PKEY_METHOD X-Git-Tag: OpenSSL_1_1_1-pre1~881 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=6d8aba7b8c5dc63bd8f4592538af3d41a274659b;p=oweals%2Fopenssl.git Add documentation for the scrypt PKEY_METHOD Added manpage for the new scrypt EVP_PKEY_METHOD KDF interface. Reviewed-by: Paul Dale Reviewed-by: Stephen Henson (Merged from https://github.com/openssl/openssl/pull/4026) --- diff --git a/doc/man7/scrypt.pod b/doc/man7/scrypt.pod new file mode 100644 index 0000000000..4de0c7236b --- /dev/null +++ b/doc/man7/scrypt.pod @@ -0,0 +1,158 @@ +=pod + +=head1 NAME + +scrypt - EVP_PKEY scrypt KDF support + +=head1 SYNOPSIS + + #include + + int EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass, + int passlen); + + int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt, + int saltlen); + + int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N); + + int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r); + + int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p); + + int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx, uint64_t maxmem); + +=head1 DESCRIPTION + +The EVP_PKEY_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 default amount of RAM that +may be used by scrypt defaults to 1025 MiB. + +EVP_PKEY_CTX_set1_pbe_pass() sets the B bytes long password. + +EVP_PKEY_CTX_set1_scrypt_salt() sets the B bytes long salt value. + +EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and +EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p. + +EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key derivation may +maximally use, given in bytes. If RAM is exceeded because the load factors are +chosen too high, the key derivation will fail. + +=head1 STRING CTRLS + +scrypt also supports string based control operations via +L. +The B can be directly specified using the B parameter "pass" or +given in hex encoding using the "hexpass" parameter. Similarly, the B can +either be specified using the B parameter "salt" or in hex encoding by +using the "hexsalt" parameter. The work factors B, B and B

as well as +B can be set by using the parameters "N", "r", "p" and +"maxmem_bytes", respectively. + +=head1 NOTES + +All these functions are implemented as macros. + +A context for scrypt can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_SCRYPT, NULL); + +The output length of an scrypt key derivation is specified via the length +parameter to the L function. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLE + +This example derives a 64-byte long test vector using scrypt using the password +"password", salt "NaCl" and N = 1024, r = 8, p = 16. + + EVP_PKEY_CTX *pctx; + unsigned char out[64]; + + size_t outlen = sizeof(out); + pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL); + + if (EVP_PKEY_derive_init(pctx) <= 0) { + error("EVP_PKEY_derive_init"); + } + if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) { + error("EVP_PKEY_CTX_set1_pbe_pass"); + } + if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) { + error("EVP_PKEY_CTX_set1_scrypt_salt"); + } + if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) { + error("EVP_PKEY_CTX_set_scrypt_N"); + } + if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) { + error("EVP_PKEY_CTX_set_scrypt_r"); + } + if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) { + error("EVP_PKEY_CTX_set_scrypt_p"); + } + if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) { + error("EVP_PKEY_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_PKEY_CTX_free(pctx); + +=head1 CONFORMING TO + +RFC 7914 + +=head1 SEE ALSO + +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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. + +=cut