aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_blake2b_general.html
blob: 727a74853bd32e42bc7894961489311c5d0ea6e9 (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
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
<!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_BLAKE2B(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_BLAKE2B(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_BLAKE2B(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_blake2b</b>,
  <b class="Nm" title="Nm">crypto_blake2b_general</b>,
  <b class="Nm" title="Nm">crypto_blake2b_general_init</b>,
  <b class="Nm" title="Nm">crypto_blake2b_init</b>,
  <b class="Nm" title="Nm">crypto_blake2b_update</b>,
  <b class="Nm" title="Nm">crypto_blake2b_final</b> &#x2014;
  <span class="Nd" title="Nd">cryptographic hashing</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_blake2b</b>(<var class="Fa" title="Fa">uint8_t
  hash[64]</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
  <var class="Fa" title="Fa">size_t message_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_blake2b_general</b>(<var class="Fa" title="Fa">uint8_t
  *hash</var>, <var class="Fa" title="Fa">size_t hash_size</var>,
  <var class="Fa" title="Fa">const uint8_t *key</var>,
  <var class="Fa" title="Fa">size_t key_size</var>,
  <var class="Fa" title="Fa">const uint8_t *message</var>,
  <var class="Fa" title="Fa">size_t message_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_blake2b_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx
  *ctx</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_blake2b_general_init</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx
  *ctx</var>, <var class="Fa" title="Fa">size_t hash_size</var>,
  <var class="Fa" title="Fa">const uint8_t *key</var>,
  <var class="Fa" title="Fa">size_t key_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_blake2b_update</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx
  *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
  <var class="Fa" title="Fa">size_t message_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_blake2b_final</b>(<var class="Fa" title="Fa">crypto_blake2b_ctx
  *ctx</var>, <var class="Fa" title="Fa">uint8_t *hash</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
BLAKE2b is a fast cryptographically secure hash, based on the ideas of Chacha20.
  It is faster than MD5, yet just as secure as SHA-3.
<div class="Pp"></div>
Note that BLAKE2b itself is not suitable for hashing passwords and deriving keys
  from them; use the
  <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a>
  family of functions for that purpose instead.
<div class="Pp"></div>
BLAKE2b is immune to length extension attacks, and as such does not require any
  specific precautions, such as using the HMAC algorithm.
<div class="Pp"></div>
The 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">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.
      Must be between 1 and 64. Anything below 32 is discouraged when using
      Blake2b as a general-purpose hash function; anything below 16 is
      discouraged when using Blake2b as a message authentication code.</dd>
  <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">Some secret key. One cannot predict the final hash without
      it. May be <code class="Dv" title="Dv">NULL</code> if
      <var class="Fa" title="Fa">key_size</var> is 0, in which case no key is
      used. Keys can be used to create a message authentication code (MAC). 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 MACs created this way. Choose the size of the hash accordingly.
      Users may want to wipe the key with
      <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
      once they are done with it.</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 between 0 and 64. 32 is a good default.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt>
  <dd class="It-tag">The message to hash. May overlap with
      <var class="Fa" title="Fa">hash</var>. May be
      <code class="Dv" title="Dv">NULL</code> if
      <var class="Fa" title="Fa">message_size</var> is 0.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in
      bytes.</dd>
</dl>
<h2 class="Ss" title="Ss" id="Direct_interface"><a class="selflink" href="#Direct_interface">Direct
  interface</a></h2>
The direct interface has two functions,
  <b class="Fn" title="Fn">crypto_blake2b</b>() and
  <b class="Fn" title="Fn">crypto_blake2b_general</b>().
  <b class="Fn" title="Fn">crypto_blake2b</b>() is provided for convenience, and
  is equivalent to calling <b class="Fn" title="Fn">crypto_blake2b_general</b>()
  with no key and a 64-byte hash.
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_blake2b_general</b>() users can specify the size
  of the hash, and use a secret key to make the hash unpredictable &#x2013;
  useful for message authentication codes. Even when using a key, you do not
  have to wipe the context struct with
  <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>.
<h2 class="Ss" title="Ss" id="Incremental_interface"><a class="selflink" href="#Incremental_interface">Incremental
  interface</a></h2>
The incremental interface is useful for handling streams of data or large files
  without using too much memory. This interface uses three steps:
<ul class="Bl-bullet">
  <li class="It-bullet">initialisation with
      <b class="Fn" title="Fn">crypto_blake2b_general_init</b>() or
      <b class="Fn" title="Fn">crypto_blake2b_init</b>(), which sets up a
      context with the hashing parameters;</li>
  <li class="It-bullet">update with
      <b class="Fn" title="Fn">crypto_blake2b_update</b>(), which hashes the
      message chunk by chunk, and keep the intermediary result in the
    context;</li>
  <li class="It-bullet">and finalisation with
      <b class="Fn" title="Fn">crypto_blake2b_final</b>(), which produces the
      final hash. The <var class="Ft" title="Ft">crypto_blake2b_ctx</var> is
      automatically wiped upon finalisation.</li>
</ul>
<div class="Pp"></div>
The invariants of the parameters are the same as for
  <b class="Fn" title="Fn">crypto_blake2b_general</b>().
  <b class="Fn" title="Fn">crypto_blake2b_init</b>() is a convenience
  initialisation function that specifies a 64-byte hash and no key. This is
  considered a good default.
<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 examples assume 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>
Hashing a message all at once:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t hash   [64]; /* Output hash (64 bytes)          */ 
uint8_t message[12] = &quot;Lorem ipsum&quot;; /* Message to hash */ 
crypto_blake2b(hash, message, 12);
</pre>
</div>
<div class="Pp"></div>
Computing a message authentication code all at once:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t hash   [16]; 
uint8_t key    [32]; 
uint8_t message[11] = &quot;Lorem ipsu&quot;; /* Message to authenticate */ 
arc4random_buf(key, 32); 
crypto_blake2b_general(hash, 16, key, 32, message, 11); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(message, 11); 
crypto_wipe(key, 32);
</pre>
</div>
<div class="Pp"></div>
Hashing a message incrementally (without a key):
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t hash   [ 64]; /* Output hash (64 bytes) */ 
uint8_t message[500] = {1}; /* Message to hash  */ 
crypto_blake2b_ctx ctx; 
crypto_blake2b_init(&amp;ctx); 
for (size_t i = 0; i &lt; 500; i += 100) { 
    crypto_blake2b_update(&amp;ctx, message + i, 100); 
} 
crypto_blake2b_final(&amp;ctx, hash);
</pre>
</div>
<div class="Pp"></div>
Computing a message authentication code incrementally:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t hash   [ 16]; 
uint8_t key    [ 32]; 
uint8_t message[500] = {1}; /* Message to authenticate         */ 
crypto_blake2b_ctx ctx; 
arc4random_buf(key, 32); 
crypto_blake2b_general_init(&amp;ctx, 16, key, 32); 
/* Wipe the key */ 
crypto_wipe(key, 32); 
for (size_t i = 0; i &lt; 500; i += 100) { 
    crypto_blake2b_update(&amp;ctx, message + i, 100); 
    /* Wipe secrets if they are no longer needed */ 
    crypto_wipe(message + i, 100); 
} 
crypto_blake2b_final(&amp;ctx, hash);
</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_key_exchange.html">crypto_key_exchange(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(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 BLAKE2b, described in RFC 7693.
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
The <b class="Fn" title="Fn">crypto_blake2b</b>(),
  <b class="Fn" title="Fn">crypto_blake2b_general</b>(),
  <b class="Fn" title="Fn">crypto_blake2b_general_init</b>(),
  <b class="Fn" title="Fn">crypto_blake2b_init</b>(),
  <b class="Fn" title="Fn">crypto_blake2b_update</b>(), and
  <b class="Fn" title="Fn">crypto_blake2b_final</b>() functions first appeared
  in Monocypher 0.1.
<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1>
Monocypher does not perform any input validation. 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.
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
  CONSIDERATIONS</a></h1>
BLAKE2b is a general-purpose cryptographic hash function; this means that it is
  not suited for hashing passwords and deriving cryptographic keys from
  passwords in particular. While cryptographic keys usually have hundreds of
  bits of entropy, passwords are often much less complex. When storing passwords
  as hashes or when deriving keys from them, the goal is normally to prevent
  attackers from quickly iterating all possible passwords. Because passwords
  tend to be simple, it is important to artificially slow down attackers by
  using especially computationally difficult hashing algorithms. Monocypher
  therefore provides
  <a class="Xr" title="Xr" href="crypto_argon2i.html">crypto_argon2i(3monocypher)</a>
  for password hashing and deriving keys from passwords.</div>
<table class="foot">
  <tr>
    <td class="foot-date">March 31, 2020</td>
    <td class="foot-os">Linux 4.15.0-106-generic</td>
  </tr>
</table>
</body>
</html>