secure/lib/libcrypto/man/man7/scrypt.7

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SCRYPT 7"
 136 .TH SCRYPT 7 "2020-04-21" "1.1.1g" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 scrypt \- EVP_PKEY scrypt KDF support
 143 .SH "DESCRIPTION"
 144 .IX Header "DESCRIPTION"
 145 The \s-1EVP_PKEY_SCRYPT\s0 algorithm implements the scrypt password based key
 146 derivation function, as described in \s-1RFC 7914.\s0  It is memory-hard in the sense
 147 that it deliberately requires a significant amount of \s-1RAM\s0 for efficient
 148 computation. The intention of this is to render brute forcing of passwords on
 149 systems that lack large amounts of main memory (such as GPUs or ASICs)
 150 computationally infeasible.
 151 .PP
 152 scrypt provides three work factors that can be customized: N, r and p. N, which
 153 has to be a positive power of two, is the general work factor and scales \s-1CPU\s0
 154 time in an approximately linear fashion. r is the block size of the internally
 155 used hash function and p is the parallelization factor. Both r and p need to be
 156 greater than zero. The amount of \s-1RAM\s0 that scrypt requires for its computation
 157 is roughly (128 * N * r * p) bytes.
 158 .PP
 159 In the original paper of Colin Percival (\*(L"Stronger Key Derivation via
 160 Sequential Memory-Hard Functions\*(R", 2009), the suggested values that give a
 161 computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
 162 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
 163 this computation is roughly 1 GiB. On a more recent \s-1CPU\s0 (Intel i7\-5930K at 3.5
 164 GHz), this computation takes about 3 seconds. When N, r or p are not specified,
 165 they default to 1048576, 8, and 1, respectively. The default amount of \s-1RAM\s0 that
 166 may be used by scrypt defaults to 1025 MiB.
 167 .SH "NOTES"
 168 .IX Header "NOTES"
 169 A context for scrypt can be obtained by calling:
 170 .PP
 171 .Vb 1
 172 \& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
 173 .Ve
 174 .PP
 175 The output length of an scrypt key derivation is specified via the
 176 length parameter to the \fBEVP_PKEY_derive\fR\|(3) function.
 177 .SH "EXAMPLES"
 178 .IX Header "EXAMPLES"
 179 This example derives a 64\-byte long test vector using scrypt using the password
 180 \&\*(L"password\*(R", salt \*(L"NaCl\*(R" and N = 1024, r = 8, p = 16.
 181 .PP
 182 .Vb 2
 183 \& EVP_PKEY_CTX *pctx;
 184 \& unsigned char out[64];
 185 \&
 186 \& size_t outlen = sizeof(out);
 187 \& pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
 188 \&
 189 \& if (EVP_PKEY_derive_init(pctx) <= 0) {
 190 \&     error("EVP_PKEY_derive_init");
 191 \& }
 192 \& if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) {
 193 \&     error("EVP_PKEY_CTX_set1_pbe_pass");
 194 \& }
 195 \& if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) {
 196 \&     error("EVP_PKEY_CTX_set1_scrypt_salt");
 197 \& }
 198 \& if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) {
 199 \&     error("EVP_PKEY_CTX_set_scrypt_N");
 200 \& }
 201 \& if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) {
 202 \&     error("EVP_PKEY_CTX_set_scrypt_r");
 203 \& }
 204 \& if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) {
 205 \&     error("EVP_PKEY_CTX_set_scrypt_p");
 206 \& }
 207 \& if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) {
 208 \&     error("EVP_PKEY_derive");
 209 \& }
 210 \&
 211 \& {
 212 \&     const unsigned char expected[sizeof(out)] = {
 213 \&         0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
 214 \&         0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
 215 \&         0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
 216 \&         0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
 217 \&         0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
 218 \&         0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
 219 \&         0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
 220 \&         0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
 221 \&     };
 222 \&
 223 \&     assert(!memcmp(out, expected, sizeof(out)));
 224 \& }
 225 \&
 226 \& EVP_PKEY_CTX_free(pctx);
 227 .Ve
 228 .SH "CONFORMING TO"
 229 .IX Header "CONFORMING TO"
 230 \&\s-1RFC 7914\s0
 231 .SH "SEE ALSO"
 232 .IX Header "SEE ALSO"
 233 \&\fBEVP_PKEY_CTX_set1_scrypt_salt\fR\|(3),
 234 \&\fBEVP_PKEY_CTX_set_scrypt_N\fR\|(3),
 235 \&\fBEVP_PKEY_CTX_set_scrypt_r\fR\|(3),
 236 \&\fBEVP_PKEY_CTX_set_scrypt_p\fR\|(3),
 237 \&\fBEVP_PKEY_CTX_set_scrypt_maxmem_bytes\fR\|(3),
 238 \&\fBEVP_PKEY_CTX_new\fR\|(3),
 239 \&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3),
 240 \&\fBEVP_PKEY_derive\fR\|(3)
 241 .SH "COPYRIGHT"
 242 .IX Header "COPYRIGHT"
 243 Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved.
 244 .PP
 245 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 246 this file except in compliance with the License.  You can obtain a copy
 247 in the file \s-1LICENSE\s0 in the source distribution or at
 248 <https://www.openssl.org/source/license.html>.