aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_chacha20.html
blob: a3c0ec74fbcff0bdb131067961850f0eb9e539f8 (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
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
<!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_CHACHA20(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_CHACHA20(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_CHACHA20(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_chacha20</b>,
  <b class="Nm" title="Nm">crypto_chacha20_ctr</b>,
  <b class="Nm" title="Nm">crypto_xchacha20</b>,
  <b class="Nm" title="Nm">crypto_xchacha20_ctr</b> &#x2014;
  <span class="Nd" title="Nd">Chacha20 and XChacha20 encryption functions</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_chacha20</b>(<var class="Fa" title="Fa">uint8_t
  *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t
  *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>,
  <var class="Fa" title="Fa">const uint8_t key[32]</var>,
  <var class="Fa" title="Fa">const uint8_t nonce[8]</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_xchacha20</b>(<var class="Fa" title="Fa">uint8_t
  *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t
  *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>,
  <var class="Fa" title="Fa">const uint8_t key[32]</var>,
  <var class="Fa" title="Fa">const uint8_t nonce[24]</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">uint64_t</var>
<br/>
<b class="Fn" title="Fn">crypto_chacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t
  *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t
  *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>,
  <var class="Fa" title="Fa">const uint8_t key[32]</var>,
  <var class="Fa" title="Fa">const uint8_t nonce[8]</var>,
  <var class="Fa" title="Fa">uint64_t ctr</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">uint64_t</var>
<br/>
<b class="Fn" title="Fn">crypto_xchacha20_ctr</b>(<var class="Fa" title="Fa">uint8_t
  *cipher_text</var>, <var class="Fa" title="Fa">const uint8_t
  *plain_text</var>, <var class="Fa" title="Fa">size_t text_size</var>,
  <var class="Fa" title="Fa">const uint8_t key[32]</var>,
  <var class="Fa" title="Fa">const uint8_t nonce[24]</var>,
  <var class="Fa" title="Fa">uint64_t ctr</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
These functions provide an interface for the Chacha20 encryption primitive.
<div class="Pp"></div>
Chacha20 is a low-level primitive. Consider using authenticated encryption,
  implemented by
  <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>.
<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 32-byte secret key.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">nonce</var></dt>
  <dd class="It-tag">An 8-byte or 24-byte number, used only once with any given
      key. It does not need to be secret or random, but it does have to be
      unique. Repeating a nonce with the same key reveals the XOR of two
      different messages, which allows decryption. 24-byte nonces can be
      selected at random. 8-byte nonces <i class="Em" title="Em">cannot</i>.
      They are too small, and the same nonce may be selected twice by accident.
      See <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
      advice about generating random numbers (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">plain_text</var></dt>
  <dd class="It-tag">The message to encrypt. It is allowed to be
      <code class="Dv" title="Dv">NULL</code>, in which case it will be
      interpreted as an all zero input.
      <var class="Fa" title="Fa">cipher_text</var> will then contain the raw
      Chacha20 stream.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">cipher_text</var></dt>
  <dd class="It-tag">The encrypted message.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">text_size</var></dt>
  <dd class="It-tag">Length of both <var class="Fa" title="Fa">plain_text</var>
      and <var class="Fa" title="Fa">cipher_text</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">ctr</var></dt>
  <dd class="It-tag">The number of 64-byte blocks since the beginning of the
      stream.</dd>
</dl>
<div class="Pp"></div>
The <var class="Fa" title="Fa">key</var> and
  <var class="Fa" title="Fa">nonce</var> buffers may overlap.
  <var class="Fa" title="Fa">plain_text</var> and
  <var class="Fa" title="Fa">cipher_text</var> must either be the same buffer
  (for in-place encryption), or non-overlapping.
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_chacha20</b>() performs a Chacha20 operation. It
  uses an 8-byte nonce, which is too small to be selected at random. Use a
  message counter as a nonce instead.
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_xchacha20</b>() performs an XChacha20 operation.
  It uses a 24-byte nonce, which is large enough to be selected at random.
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_xchacha20</b>() is recommended over
  <b class="Fn" title="Fn">crypto_chacha20</b>(). The ability to use random
  nonces makes it easier to use securely, and the performance hit is often
  negligible in practice.
<div class="Pp"></div>
The <b class="Fn" title="Fn">crypto_chacha20</b>() and
  <b class="Fn" title="Fn">crypto_xchacha20</b>() encrypt
  <var class="Fa" title="Fa">plain_text</var> by XORing it with a pseudo-random
  stream of numbers, seeded by the provided <var class="Fa" title="Fa">key</var>
  and <var class="Fa" title="Fa">nonce</var>.
<div class="Pp"></div>
Since XOR is its own inverse, decryption is the same operation as encryption. To
  decrypt the cipher text, &#x201C;encrypt&#x201D; it again with the same key
  and nonce. You will likely want to wipe the key when you are done with
  encryption or decryption. Use
  <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
  to wipe them.
<div class="Pp"></div>
The <var class="Fa" title="Fa">plain_text</var> pointer is allowed to be
  <code class="Dv" title="Dv">NULL</code>, in which case it will be interpreted
  as an all zero input. This is useful as a user space random number generator.
  While <b class="Sy" title="Sy">this should not be used as a random number
  generator for secrets</b>, for which the operating system random number
  generator should be preferred, it can be handy outside of a security context.
  Deterministic procedural generation and reproducible property-based tests come
  to mind. Additionally, it <i class="Em" title="Em">can</i> be used to generate
  large amounts of random-looking data quickly, for example to generate padding.
<div class="Pp"></div>
The <b class="Fn" title="Fn">crypto_chacha20_ctr</b>() and
  <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() perform a Chacha20 or
  XChacha20 encryption, respectively, starting the stream at the block
  <var class="Fa" title="Fa">ctr</var> (which is the byte
  &#x2018;<code class="Li">ctr &#x00D7; 64</code>&#x2019;). This can be used to
  encrypt (or decrypt) part of a long message, or to implement some AEAD
  constructions such as the one described in RFC 8439. Be careful when using
  this not to accidentally reuse parts of the random stream as that would
  destroy confidentiality.
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
  VALUES</a></h1>
<b class="Fn" title="Fn">crypto_chacha20</b>() and
  <b class="Fn" title="Fn">crypto_xchacha20</b>() return nothing.
  <b class="Fn" title="Fn">crypto_chacha20_ctr</b>() and
  <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() functions return the next
  <var class="Fa" title="Fa">ctr</var> to use with the same key and nonce
  values; this is always <var class="Fa" title="Fa">text_size</var> divided by
  64; plus one if there was a remainder.
<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>
Simple encryption:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t key        [ 32]; /* Secret random key              */ 
uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */ 
uint8_t plain_text [500] = {1}; /* Secret message           */ 
uint8_t cipher_text[500]; /* Encrypted message              */ 
arc4random_buf(key,   32); 
arc4random_buf(nonce, 24); 
crypto_xchacha20(cipher_text, plain_text, 500, key, nonce); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(key,        32); 
crypto_wipe(plain_text, 500);
</pre>
</div>
<div class="Pp"></div>
To decrypt the above:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t       key        [ 32]; /* Same key as above        */ 
const uint8_t nonce      [ 24]; /* Same nonce as above      */ 
uint8_t       plain_text [500]; /* Message to decrypt       */ 
uint8_t       cipher_text[500]; /* Secret message           */ 
crypto_xchacha20(cipher_text, plain_text, 500, key, nonce); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(key,        32); 
/* The plain text likely needs to be processed before you wipe it */ 
crypto_wipe(plain_text, 12);
</pre>
</div>
<div class="Pp"></div>
Incremental encryption (in blocks of 64 bytes):
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t  key        [ 32]; /* Secret random key              */ 
uint8_t  nonce      [ 24]; /* Unique nonce (possibly random) */ 
uint8_t  plain_text [500]; /* Secret message                 */ 
uint8_t  cipher_text[500]; /* Encrypted message              */ 
uint64_t ctr = 0;          /* Block counter                  */ 
unsigned int i; 
arc4random_buf(key,   32); 
arc4random_buf(nonce, 24); 
for(i = 0; i &lt; 500; i += 64) { 
    ctr = crypto_xchacha20_ctr(cipher_text+i, plain_text+i, 64, 
                               key, nonce, ctr); 
} 
/* Process data that didn't fit into 64 byte pieces */ 
crypto_xchacha20_ctr(cipher_text+500-(i-64), 
                     plain_text+500-(i-64), 
                     500-(i-64), 
                     key, nonce, ctr); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(key,        32); 
crypto_wipe(plain_text, 500);
</pre>
</div>
<div class="Pp"></div>
Encryption by jumping around (do not do that, this is only meant to show how
  <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() works):
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t key        [ 32]; /* Secret random key              */ 
uint8_t nonce      [ 24]; /* Unique nonce (possibly random) */ 
uint8_t plain_text [500] = {1}; /* Message to be encrypted  */ 
uint8_t cipher_text[500]; /* Will be the encrypted message  */ 
arc4random_buf(key,   32); 
arc4random_buf(nonce, 24); 
/* Encrypt the second part of the message first... */ 
crypto_xchacha20_ctr(cipher_text + (3 * 64), 
                     plain_text  + (3 * 64), 
                     500         - (3 * 64), 
                     key, nonce, 3); 
/* ...then encrypt the first part */ 
crypto_xchacha20_ctr(cipher_text, plain_text, 3 * 64, key, nonce, 0); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(key,        32); 
crypto_wipe(plain_text, 500);
</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_ietf_chacha20.html">crypto_ietf_chacha20(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(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 Chacha20 and XChacha20. Chacha20 is described in:
  <cite class="Rs" title="Rs"><span class="RsA">Daniel J. Bernstein</span>,
  <span class="RsT">ChaCha, a variant of Salsa20</span>, <i class="RsJ">SASC
  2008 &#x2013; The State of the Art of Stream Ciphers</i>,
  <span class="RsP">pp. 273&#x2013;278</span>.</cite> The nonce and counter
  sizes were modified in RFC 8439. XChacha20 derives from Chacha20 the same way
  XSalsa20 derives from Salsa20, and benefits from the same security reduction
  (proven secure as long as Chacha20 itself is secure).
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
<b class="Fn" title="Fn">crypto_chacha20</b>(),
  <b class="Fn" title="Fn">crypto_chacha20_ctr</b>(),
  <b class="Fn" title="Fn">crypto_xchacha20</b>(), and
  <b class="Fn" title="Fn">crypto_xchacha20_ctr</b>() were added in Monocypher
  3.0.0. They replace <b class="Fn" title="Fn">crypto_chacha20_encrypt</b>(),
  <b class="Fn" title="Fn">crypto_chacha20_init</b>(),
  <b class="Fn" title="Fn">crypto_chacha20_stream</b>(),
  <b class="Fn" title="Fn">crypto_chacha20_x_init</b>(), and
  <b class="Fn" title="Fn">crypto_chacha20_set_ctr</b>() that were deprecated in
  Monocypher 3.0.0.
<h1 class="Sh" title="Sh" id="SECURITY_CONSIDERATIONS"><a class="selflink" href="#SECURITY_CONSIDERATIONS">SECURITY
  CONSIDERATIONS</a></h1>
<h2 class="Ss" title="Ss" id="Encrypted_does_not_mean_secure"><a class="selflink" href="#Encrypted_does_not_mean_secure">Encrypted
  does not mean secure</a></h2>
Chacha20 only protects against eavesdropping, not forgeries. Most applications
  need protection against forgeries to be properly secure. To ensure the
  integrity of a message, use Blake2b in keyed mode, or authenticated
  encryption; see
  <a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>
  and
  <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>.
<h2 class="Ss" title="Ss" id="Nonce_reuse"><a class="selflink" href="#Nonce_reuse">Nonce
  reuse</a></h2>
Repeating a nonce with the same key exposes the XOR of two or more plain text
  messages, effectively destroying confidentiality.
<div class="Pp"></div>
For the same reason, <b class="Sy" title="Sy">do not select small nonces at
  random</b>. The <b class="Fn" title="Fn">crypto_chacha20</b>() nonce spans
  only 64 bits, which is small enough to trigger accidental reuses. A message
  counter should be used instead. If multiple parties send out messages, Each
  can start with an initial nonce of 0, 1 .. n-1 respectively, and increment
  them by n for each new message. Make sure the counters never wrap around.
<h2 class="Ss" title="Ss" id="Secure_random_number_generation"><a class="selflink" href="#Secure_random_number_generation">Secure
  random number generation</a></h2>
Do not use these functions as a cryptographic random number generator. Always
  use the operating system's random number generator for cryptographic purposes,
  see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a>.
<h2 class="Ss" title="Ss" id="Protection_against_side_channels"><a class="selflink" href="#Protection_against_side_channels">Protection
  against side channels</a></h2>
Secrets should not dwell in memory longer than needed. Use
  <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
  to erase secrets you no longer need. For Chacha20, this means the key and in
  some cases the plain text itself.</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>