diff options
Diffstat (limited to 'upstream/archlinux/man7/EVP_KDF-SCRYPT.7ssl')
| -rw-r--r-- | upstream/archlinux/man7/EVP_KDF-SCRYPT.7ssl | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/upstream/archlinux/man7/EVP_KDF-SCRYPT.7ssl b/upstream/archlinux/man7/EVP_KDF-SCRYPT.7ssl new file mode 100644 index 00000000..a8614199 --- /dev/null +++ b/upstream/archlinux/man7/EVP_KDF-SCRYPT.7ssl @@ -0,0 +1,199 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_KDF-SCRYPT 7ssl" +.TH EVP_KDF-SCRYPT 7ssl 2024-01-30 3.2.1 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +EVP_KDF\-SCRYPT \- The scrypt EVP_KDF implementation +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Support for computing the \fBscrypt\fR password-based KDF through the \fBEVP_KDF\fR +API. +.PP +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. +.PP +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. +.PP +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. +.SS Identity +.IX Subsection "Identity" +"SCRYPT" is the name for this implementation; it +can be used with the \fBEVP_KDF_fetch()\fR function. +.SS "Supported parameters" +.IX Subsection "Supported parameters" +The supported parameters are: +.IP """pass"" (\fBOSSL_KDF_PARAM_PASSWORD\fR) <octet string>" 4 +.IX Item """pass"" (OSSL_KDF_PARAM_PASSWORD) <octet string>" +.PD 0 +.IP """salt"" (\fBOSSL_KDF_PARAM_SALT\fR) <octet string>" 4 +.IX Item """salt"" (OSSL_KDF_PARAM_SALT) <octet string>" +.PD +These parameters work as described in "PARAMETERS" in \fBEVP_KDF\fR\|(3). +.IP """n"" (\fBOSSL_KDF_PARAM_SCRYPT_N\fR) <unsigned integer>" 4 +.IX Item """n"" (OSSL_KDF_PARAM_SCRYPT_N) <unsigned integer>" +.PD 0 +.IP """r"" (\fBOSSL_KDF_PARAM_SCRYPT_R\fR) <unsigned integer>" 4 +.IX Item """r"" (OSSL_KDF_PARAM_SCRYPT_R) <unsigned integer>" +.IP """p"" (\fBOSSL_KDF_PARAM_SCRYPT_P\fR) <unsigned integer>" 4 +.IX Item """p"" (OSSL_KDF_PARAM_SCRYPT_P) <unsigned integer>" +.IP """maxmem_bytes"" (\fBOSSL_KDF_PARAM_SCRYPT_MAXMEM\fR) <unsigned integer>" 4 +.IX Item """maxmem_bytes"" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>" +.PD +These parameters configure the scrypt work factors N, r, maxmem and p. +Both N and maxmem_bytes are parameters of type \fBuint64_t\fR. +Both r and p are parameters of type \fBuint32_t\fR. +.IP """properties"" (\fBOSSL_KDF_PARAM_PROPERTIES\fR) <UTF8 string>" 4 +.IX Item """properties"" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>" +This can be used to set the property query string when fetching the +fixed digest internally. NULL is used if this value is not set. +.SH NOTES +.IX Header "NOTES" +A context for scrypt can be obtained by calling: +.PP +.Vb 2 +\& EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); +\& EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); +.Ve +.PP +The output length of an scrypt key derivation is specified via the +"keylen" parameter to the \fBEVP_KDF_derive\fR\|(3) function. +.SH EXAMPLES +.IX Header "EXAMPLES" +This example derives a 64\-byte long test vector using scrypt with the password +"password", salt "NaCl" and N = 1024, r = 8, p = 16. +.PP +.Vb 4 +\& EVP_KDF *kdf; +\& EVP_KDF_CTX *kctx; +\& unsigned char out[64]; +\& OSSL_PARAM params[6], *p = params; +\& +\& kdf = EVP_KDF_fetch(NULL, "SCRYPT", NULL); +\& kctx = EVP_KDF_CTX_new(kdf); +\& EVP_KDF_free(kdf); +\& +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD, +\& "password", (size_t)8); +\& *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, +\& "NaCl", (size_t)4); +\& *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8); +\& *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16); +\& *p = OSSL_PARAM_construct_end(); +\& if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 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); +.Ve +.SH "CONFORMING TO" +.IX Header "CONFORMING TO" +RFC 7914 +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_KDF\fR\|(3), +\&\fBEVP_KDF_CTX_new\fR\|(3), +\&\fBEVP_KDF_CTX_free\fR\|(3), +\&\fBEVP_KDF_CTX_set_params\fR\|(3), +\&\fBEVP_KDF_derive\fR\|(3), +"PARAMETERS" in \fBEVP_KDF\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.0. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 +<https://www.openssl.org/source/license.html>. |