aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_hchacha20.html
blob: 04177b6d4951174dc4b32fe9cb8b031fecf6b6fa (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
<!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_HCHACHA20(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_HCHACHA20(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_HCHACHA20(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_hchacha20</b> &#x2014;
  <span class="Nd" title="Nd">HChacha20 special-purpose 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_hchacha20</b>(<var class="Fa" title="Fa">uint8_t
  out[32]</var>, <var class="Fa" title="Fa">const uint8_t key[32]</var>,
  <var class="Fa" title="Fa">const uint8_t in[16]</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<b class="Fn" title="Fn">crypto_hchacha20</b>() provides a not-so-cryptographic
  hash. It may be used for some specific purposes, such as X25519 key
  derivation, or XChacha20 initialisation. If in doubt, do not use directly. Use
  <a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
  instead.
<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">key</var></dt>
  <dd class="It-tag">A sufficiently random key, such as the output of
      <a class="Xr" title="Xr" href="crypto_x25519.html">crypto_x25519(3monocypher)</a>.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">in</var></dt>
  <dd class="It-tag">The space reserved for the Chacha20 nonce and counter. It
      does not have to be random.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">out</var></dt>
  <dd class="It-tag">A cryptographically secure random number
      <i class="Em" title="Em">if</i> there is enough entropy in
      <var class="Fa" title="Fa">key</var>. X25519 shared secrets have enough
      entropy.</dd>
</dl>
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
  VALUES</a></h1>
This function returns 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>
Simple hash:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t key[32]; /* Must have enough entropy           */ 
uint8_t in [16]; /* Does not have to be random         */ 
uint8_t out[32]; /* Will be random iff the above holds */ 
arc4random_buf(key, 32); 
crypto_hchacha20(out, key, in); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(key, 32); 
crypto_wipe(in , 16);
</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_chacha20_encrypt.html">crypto_chacha20_encrypt(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_key_exchange.html">crypto_key_exchange(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>
This function implements HChacha20. HChacha20 derives from Chacha20 the same way
  HSalsa20 derives from Salsa20.
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
The <b class="Fn" title="Fn">crypto_hchacha20</b>() function first appeared in
  Monocypher 0.1 as <b class="Fn" title="Fn">crypto_chacha20_H</b>(). It was
  renamed to <b class="Fn" title="Fn">crypto_hchacha20</b>() in Monocypher
  3.0.0.
<h1 class="Sh" title="Sh" id="CAVEATS"><a class="selflink" href="#CAVEATS">CAVEATS</a></h1>
<b class="Sy" title="Sy">This is not a general-purpose cryptographic hash
  function</b>.</div>
<table class="foot">
  <tr>
    <td class="foot-date">March 2, 2020</td>
    <td class="foot-os">Linux 4.15.0-106-generic</td>
  </tr>
</table>
</body>
</html>