aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_argon2i_general.html
blob: ea49288bc00311455e75935540bd0883f45c005c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <style>
    table.head, table.foot { width: 100%; }
    td.head-rtitle, td.foot-os { text-align: right; }
    td.head-vol { text-align: center; }
    div.Pp { margin: 1ex 0ex; }
  </style>
  <link rel="stylesheet" href="style.css" type="text/css" media="all"/>
  <title>CRYPTO_ARGON2I(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_ARGON2I(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_ARGON2I(3MONOCYPHER)</td>
  </tr>
</table>
<div class="manual-text">
<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1>
<b class="Nm" title="Nm">crypto_argon2i</b> &#x2014;
  <span class="Nd" title="Nd">password key derivation</span>
<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<b class="In" title="In">#include
  &lt;<a class="In" title="In">monocypher.h</a>&gt;</b>
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_argon2i</b>(<var class="Fa" title="Fa">uint8_t
  *hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>,
  <var class="Fa" title="Fa">void *work_area</var>,
  <var class="Fa" title="Fa">uint32_t nb_blocks</var>,
  <var class="Fa" title="Fa">uint32_t nb_iterations</var>,
  <var class="Fa" title="Fa">const uint8_t *password</var>,
  <var class="Fa" title="Fa">uint32_t password_size</var>,
  <var class="Fa" title="Fa">const uint8_t *salt</var>,
  <var class="Fa" title="Fa">uint32_t salt_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_argon2i_general</b>(<var class="Fa" title="Fa">uint8_t
  *hash</var>, <var class="Fa" title="Fa">uint32_t hash_size</var>,
  <var class="Fa" title="Fa">void *work_area</var>,
  <var class="Fa" title="Fa">uint32_t nb_blocks</var>,
  <var class="Fa" title="Fa">uint32_t nb_iterations</var>,
  <var class="Fa" title="Fa">const uint8_t *password</var>,
  <var class="Fa" title="Fa">uint32_t password_size</var>,
  <var class="Fa" title="Fa">const uint8_t *salt</var>,
  <var class="Fa" title="Fa">uint32_t salt_size</var>,
  <var class="Fa" title="Fa">const uint8_t *key</var>,
  <var class="Fa" title="Fa">uint32_t key_size</var>,
  <var class="Fa" title="Fa">const uint8_t *ad</var>,
  <var class="Fa" title="Fa">uint32_t ad_size</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
Argon2i is a resource intensive password key derivation scheme optimised for the
  typical x86-like processor. It runs in constant time with respect to the
  contents of the password.
<div class="Pp"></div>
Typical applications are password checking (for online services), and key
  derivation (for encryption). Derived keys can be used to encrypt, for example,
  private keys or password databases.
<div class="Pp"></div>
The version provided by Monocypher has no threading support, so the degree of
  parallelism is limited to 1. This is considered good enough for most purposes.
<div class="Pp"></div>
The arguments to <b class="Fn" title="Fn">crypto_argon2i</b>() are:
<dl class="Bl-tag">
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">hash</var></dt>
  <dd class="It-tag">The output hash.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">hash_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">hash</var>, in bytes.
      This argument should be set to 32 or 64 for compatibility with the
      <b class="Fn" title="Fn">crypto_verify*</b>() constant time comparison
      functions.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">work_area</var></dt>
  <dd class="It-tag">Temporary buffer for the algorithm, allocated by the
      caller. It must be <var class="Fa" title="Fa">nb_blocks</var> &#x00D7;
      1024 bytes big, and suitably aligned for 64-bit integers. If you are not
      sure how to allocate that buffer, just use
      <b class="Fn" title="Fn">malloc</b>().
    <div class="Pp"></div>
    The work area is automatically wiped by
      <b class="Fn" title="Fn">crypto_argon2i</b>().</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">nb_blocks</var></dt>
  <dd class="It-tag">The number of blocks for the work area. Must be at least 8.
      A value of 100000 (one hundred megabytes) is a good starting point. If the
      computation takes too long, reduce this number. If it is too fast,
      increase this number. If it is still too fast with all available memory,
      increase <var class="Fa" title="Fa">nb_iterations</var>.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">nb_iterations</var></dt>
  <dd class="It-tag">The number of iterations. It must be at least 1. A value of
      3 is <i class="Em" title="Em">strongly</i> recommended; any value lower
      than 3 enables significantly more efficient attacks.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">password</var></dt>
  <dd class="It-tag">The password to hash. It should be wiped with
      <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
      after being hashed.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">password_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">password</var>, in
      bytes.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">salt</var></dt>
  <dd class="It-tag">A password salt. This should be filled with random bytes,
      generated separately for each password to be hashed. See
      <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
      advice about generating random bytes (use the operating system's random
      number generator).</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">salt_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">salt</var>, in bytes.
      Must be at least 8. 16 is recommended.</dd>
</dl>
<div class="Pp"></div>
The output hash must not overlap with the work area, or it will be wiped along
  with it. Any other overlap is permitted.
<div class="Pp"></div>
Use
  <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>
  or
  <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>
  to compare password hashes to prevent timing attacks.
<div class="Pp"></div>
To select the <var class="Fa" title="Fa">nb_blocks</var> and
  <var class="Fa" title="Fa">nb_iterations</var> parameters, it should first be
  decided how long the computation should take. For user authentication, values
  somewhere between half a second (convenient) and several seconds (paranoid)
  are recommended. The computation should use as much memory as can be spared.
<div class="Pp"></div>
Since parameter selection depends on your hardware, some trial and error will be
  required in order to determine the ideal settings. Three iterations and 100000
  blocks (that is, one hundred megabytes of memory) is a good starting point.
  Adjust <var class="Fa" title="Fa">nb_blocks</var> first. If using all
  available memory is not slow enough, increase
  <var class="Fa" title="Fa">nb_iterations</var>.
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_argon2i_general</b>() is a variant of
  <b class="Fn" title="Fn">crypto_argon2i</b>() that supports keyed hashing and
  hashing of additional data. The additional arguments are:
<dl class="Bl-tag">
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt>
  <dd class="It-tag">A key to use in the hash. Can be
      <code class="Dv" title="Dv">NULL</code> if
      <var class="Fa" title="Fa">key_size</var> is zero. The key is generally
      not needed, but it does have some uses. In the context of password
      derivation, it would be stored separately from the password database, and
      would remain secret even if an attacker were to steal the database. Note
      that changing the key requires rehashing the user's password, which is
      only possible upon user login.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes.
      Must be zero if there is no key.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">ad</var></dt>
  <dd class="It-tag">Additional data. This is additional data that goes into the
      hash, similar to the authenticated encryption with authenticated data
      (AEAD) construction in
      <a class="Xr" title="Xr" href="crypto_lock_aead.html">crypto_lock_aead(3monocypher)</a>.
      This most likely has no practical application but is exposed for the sake
      of completeness. This parameter may be
      <code class="Dv" title="Dv">NULL</code> if
      <var class="Fa" title="Fa">ad_size</var> is zero.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">ad_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">ad</var>, in bytes.
      Must be zero if there is no additional data.</dd>
</dl>
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
  VALUES</a></h1>
These functions return nothing.
<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
The following example assumes the existence of
  <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer
  with cryptographically secure random bytes. If
  <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system,
  see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
  advice about how to generate cryptographically secure random bytes.
<div class="Pp"></div>
This example shows how to hash a password with the recommended baseline
  parameters:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t        hash[32];                    /* Output hash     */ 
char          *password = &quot;Okay Password!&quot;; /* User's password */ 
uint32_t       password_size = 14;          /* Password length */ 
uint8_t        salt[16];                    /* Random salt     */ 
const uint32_t nb_blocks = 100000;          /* 100 megabytes   */ 
const uint32_t nb_iterations = 3;           /* 3 iterations    */ 
void *work_area = malloc(nb_blocks * 1024); /* Work area       */ 
if (work_area == NULL) { 
    /* Handle malloc() failure */ 
    /* Wipe secrets if they are no longer needed */ 
    crypto_wipe(password, password_size); 
} else { 
    arc4random_buf(salt, 16); 
    crypto_argon2i(hash, 32, 
                   work_area, nb_blocks, nb_iterations, 
                   (uint8_t *)password, password_size, 
                   salt, 16); 
    /* Wipe secrets if they are no longer needed */ 
    crypto_wipe(password, password_size); 
    free(work_area); 
}
</pre>
</div>
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>,
  <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a>
<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1>
These functions implement Argon2i. An RFC draft is being maintained.
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
The <b class="Fn" title="Fn">crypto_argon2i_general</b>() function first
  appeared in Monocypher 0.1 but was called
  <b class="Fn" title="Fn">crypto_argon2i</b>(); it was renamed to its current
  name in Monocypher 1.1.0. The current
  <b class="Fn" title="Fn">crypto_argon2i</b>() first appeared in Monocypher
  1.1.0.
<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1>
Any deviation from the specified input and output length ranges results in
  <b class="Sy" title="Sy">undefined behaviour</b>. Make sure your inputs are
  correct.</div>
<table class="foot">
  <tr>
    <td class="foot-date">April 8, 2020</td>
    <td class="foot-os">Linux 4.15.0-106-generic</td>
  </tr>
</table>
</body>
</html>