5 * (c) 2015 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
12 * Catacomb is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Library General Public License as
14 * published by the Free Software Foundation; either version 2 of the
15 * License, or (at your option) any later version.
17 * Catacomb is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with Catacomb; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
28 #ifndef CATACOMB_CHACHA_H
29 #define CATACOMB_CHACHA_H
35 /*----- Header files ------------------------------------------------------*/
37 #include <mLib/bits.h>
39 #ifndef CATACOMB_GCIPHER_H
43 #ifndef CATACOMB_GRAND_H
47 /*----- Constants ---------------------------------------------------------*/
49 #define CHACHA_NONCESZ 8u
50 #define CHACHA_IETF_NONCESZ 12u
51 #define CHACHA_KEYSZ 32u
52 #define CHACHA_OUTSZ 64u
54 #define HCHACHA_INSZ 16u
55 #define HCHACHA_OUTSZ 32u
57 #define XCHACHA_NONCESZ 24u
58 #define XCHACHA_KEYSZ CHACHA_KEYSZ
59 #define XCHACHA_OUTSZ CHACHA_OUTSZ
61 /*----- Data structures ---------------------------------------------------*/
63 typedef uint32 chacha_matrix[16];
65 typedef struct chacha_ctx {
67 octet buf[CHACHA_OUTSZ];
71 #define XCHACHA_DEFCTX(name) \
72 typedef struct name { chacha_ctx s; chacha_matrix k; } name
73 XCHACHA_DEFCTX(xchacha20_ctx);
74 XCHACHA_DEFCTX(xchacha12_ctx);
75 XCHACHA_DEFCTX(xchacha8_ctx);
77 /*----- The ChaCha stream cipher ------------------------------------------*/
79 /* --- @chacha_init@ --- *
81 * Arguments: @chacha_ctx *ctx@ = context to fill in
82 * @const void *key@ = pointer to key material
83 * @size_t ksz@ = size of key (either 32 or 16)
84 * @const void *nonce@ = initial nonce, or null
88 * Use: Initializes a ChaCha context ready for use.
91 extern void chacha_init(chacha_ctx */*ctx*/,
92 const void */*key*/, size_t /*ksz*/,
93 const void */*nonce*/);
95 /* --- @chacha_setnonce{,_ietf}@ --- *
97 * Arguments: @chacha_ctx *ctx@ = pointer to context
98 * @const void *nonce@ = the nonce (@CHACHA_NONCESZ@ or
99 * @CHACHA_IETF_NONCESZ@ bytes)
103 * Use: Set a new nonce in the context @ctx@, e.g., for processing a
104 * different message. The stream position is reset to zero (see
105 * @chacha_seek@ etc.).
108 extern void chacha_setnonce(chacha_ctx */*ctx*/, const void */*nonce*/);
109 extern void chacha_setnonce_ietf(chacha_ctx */*ctx*/, const void */*nonce*/);
111 /* --- @chacha_seek{,u64,_ietf}@ --- *
113 * Arguments: @chacha_ctx *ctx@ = pointer to context
114 * @unsigned long i@, @kludge64 i@, @uint32 i@ = new position
118 * Use: Sets a new stream position, in units of Chacha output
119 * blocks, which are @CHACHA_OUTSZ@ bytes each. Byte
120 * granularity can be achieved by calling @chachaR_encrypt@
124 extern void chacha_seek(chacha_ctx */*ctx*/, unsigned long /*i*/);
125 extern void chacha_seeku64(chacha_ctx */*ctx*/, kludge64 /*i*/);
126 extern void chacha_seek_ietf(chacha_ctx */*ctx*/, uint32 /*i*/);
128 /* --- @chacha_tell{,u64,_ietf}@ --- *
130 * Arguments: @chacha_ctx *ctx@ = pointer to context
132 * Returns: The current position in the output stream, in blocks,
136 extern unsigned long chacha_tell(chacha_ctx */*ctx*/);
137 extern kludge64 chacha_tellu64(chacha_ctx */*ctx*/);
138 extern uint32 chacha_tell_ietf(chacha_ctx */*ctx*/);
140 /* --- @chacha{20,12,8}_encrypt@ --- *
142 * Arguments: @chacha_ctx *ctx@ = pointer to context
143 * @const void *src@ = source buffer (or null)
144 * @void *dest@ = destination buffer (or null)
145 * @size_t sz@ = size of the buffers
149 * Use: Encrypts or decrypts @sz@ bytes of data from @src@ to @dest@.
150 * ChaCha works by XORing plaintext with a keystream, so
151 * encryption and decryption are the same operation. If @dest@
152 * is null then ignore @src@ and skip @sz@ bytes of the
153 * keystream. If @src@ is null, then just write the keystream
157 extern void chacha20_encrypt(chacha_ctx */*ctx*/,
158 const void */*src*/, void */*dest*/,
160 extern void chacha12_encrypt(chacha_ctx */*ctx*/,
161 const void */*src*/, void */*dest*/,
163 extern void chacha8_encrypt(chacha_ctx */*ctx*/,
164 const void */*src*/, void */*dest*/,
167 /*----- The HChaCha pseudorandom function ---------------------------------*/
169 /* --- @hchacha{20,12,8}_prf@ --- *
171 * Arguments: @chacha_ctx *ctx@ = pointer to context
172 * @const void *src@ = the input (@HCHACHA_INSZ@ bytes)
173 * @void *dest@ = the output (@HCHACHA_OUTSZ@ bytes)
177 * Use: Apply the HChaCha/r pseudorandom function to @src@, writing
178 * the result to @out@.
181 extern void hchacha20_prf(chacha_ctx */*ctx*/,
182 const void */*src*/, void */*dest*/);
183 extern void hchacha12_prf(chacha_ctx */*ctx*/,
184 const void */*src*/, void */*dest*/);
185 extern void hchacha8_prf(chacha_ctx */*ctx*/,
186 const void */*src*/, void */*dest*/);
188 /*----- The XChaCha stream cipher ----------------------------------------*/
190 /* --- @xchacha{20,12,8}_init@ --- *
192 * Arguments: @xchachaR_ctx *ctx@ = the context to fill in
193 * @const void *key@ = pointer to key material
194 * @size_t ksz@ = size of key (either 32 or 16)
195 * @const void *nonce@ = initial nonce, or null
199 * Use: Initializes an XChaCha/r context ready for use.
201 * There is a different function for each number of rounds,
202 * unlike for plain ChaCha.
205 extern void xchacha20_init(xchacha20_ctx */*ctx*/,
206 const void */*key*/, size_t /*ksz*/,
207 const void */*nonce*/);
208 extern void xchacha12_init(xchacha12_ctx */*ctx*/,
209 const void */*key*/, size_t /*ksz*/,
210 const void */*nonce*/);
211 extern void xchacha8_init(xchacha8_ctx */*ctx*/,
212 const void */*key*/, size_t /*ksz*/,
213 const void */*nonce*/);
215 /* --- @xchacha{20,12,8}_setnonce@ --- *
217 * Arguments: @xchachaR_ctx *ctx@ = pointer to context
218 * @const void *nonce@ = the nonce (@XCHACHA_NONCESZ@ bytes)
222 * Use: Set a new nonce in the context @ctx@, e.g., for processing a
223 * different message. The stream position is reset to zero (see
224 * @chacha_seek@ etc.).
226 * There is a different function for each number of rounds,
227 * unlike for plain ChaCha.
230 extern void xchacha20_setnonce(xchacha20_ctx */*ctx*/,
231 const void */*nonce*/);
232 extern void xchacha12_setnonce(xchacha12_ctx */*ctx*/,
233 const void */*nonce*/);
234 extern void xchacha8_setnonce(xchacha8_ctx */*ctx*/,
235 const void */*nonce*/);
237 /* --- @xchacha{20,12,8}_seek{,u64}@ --- *
239 * Arguments: @xchachaR_ctx *ctx@ = pointer to context
240 * @unsigned long i@, @kludge64 i@ = new position to set
244 * Use: Sets a new stream position, in units of ChaCha output
245 * blocks, which are @XCHACHA_OUTSZ@ bytes each. Byte
246 * granularity can be achieved by calling @xchachaR_encrypt@
249 * There is a different function for each number of rounds,
250 * unlike for plain ChaCha, because the context structures are
254 extern void xchacha20_seek(xchacha20_ctx */*ctx*/, unsigned long /*i*/);
255 extern void xchacha12_seek(xchacha12_ctx */*ctx*/, unsigned long /*i*/);
256 extern void xchacha8_seek(xchacha8_ctx */*ctx*/, unsigned long /*i*/);
257 extern void xchacha20_seeku64(xchacha20_ctx */*ctx*/, kludge64 /*i*/);
258 extern void xchacha12_seeku64(xchacha12_ctx */*ctx*/, kludge64 /*i*/);
259 extern void xchacha8_seeku64(xchacha8_ctx */*ctx*/, kludge64 /*i*/);
261 /* --- @xchacha{20,12,8}_tell{,u64}@ --- *
263 * Arguments: @chacha_ctx *ctx@ = pointer to context
265 * Returns: The current position in the output stream, in blocks,
268 * There is a different function for each number of rounds,
269 * unlike for plain ChaCha, because the context structures are
273 extern unsigned long xchacha20_tell(xchacha20_ctx */*ctx*/);
274 extern unsigned long xchacha12_tell(xchacha12_ctx */*ctx*/);
275 extern unsigned long xchacha8_tell(xchacha8_ctx */*ctx*/);
276 extern kludge64 xchacha20_tellu64(xchacha20_ctx */*ctx*/);
277 extern kludge64 xchacha12_tellu64(xchacha12_ctx */*ctx*/);
278 extern kludge64 xchacha8_tellu64(xchacha8_ctx */*ctx*/);
280 /* --- @xchacha{20,12,8}_encrypt@ --- *
282 * Arguments: @xchachaR_ctx *ctx@ = pointer to context
283 * @const void *src@ = source buffer (or null)
284 * @void *dest@ = destination buffer (or null)
285 * @size_t sz@ = size of the buffers
289 * Use: Encrypts or decrypts @sz@ bytes of data from @src@ to @dest@.
290 * XChaCha works by XORing plaintext with a keystream, so
291 * encryption and decryption are the same operation. If @dest@
292 * is null then ignore @src@ and skip @sz@ bytes of the
293 * keystream. If @src@ is null, then just write the keystream
297 extern void xchacha20_encrypt(xchacha20_ctx */*ctx*/,
298 const void */*src*/, void */*dest*/,
300 extern void xchacha12_encrypt(xchacha12_ctx */*ctx*/,
301 const void */*src*/, void */*dest*/,
303 extern void xchacha8_encrypt(xchacha8_ctx */*ctx*/,
304 const void */*src*/, void */*dest*/,
307 /*----- Generic cipher interface ------------------------------------------*/
309 extern const octet chacha_keysz[];
310 #define chacha20_keysz chacha_keysz
311 #define chacha12_keysz chacha_keysz
312 #define chacha8_keysz chacha_keysz
313 #define chacha_ietf_keysz chacha_keysz
314 #define chacha20_ietf_keysz chacha_keysz
315 #define chacha12_ietf_keysz chacha_keysz
316 #define chacha8_ietf_keysz chacha_keysz
317 #define xchacha_keysz chacha_keysz
318 #define xchacha20_keysz chacha_keysz
319 #define xchacha12_keysz chacha_keysz
320 #define xchacha8_keysz chacha_keysz
322 const gccipher chacha20, chacha12, chacha8;
323 const gccipher chacha20_ietf, chacha12_ietf, chacha8_ietf;
324 const gccipher xchacha20, xchacha12, xchacha8;
326 /*----- Generic random number generator interface -------------------------*/
328 /* --- @chacha{20,12,8}{,_ietf}_rand@, @xchacha{20,12,8}_rand@ --- *
330 * Arguments: @const void *k@ = pointer to key material
331 * @size_t ksz@ = size of key material
332 * @const void *n@ = pointer to nonce or null
333 * (@CHACHA_NONCESZ@, @CHACHA_IETF_NONCESZ@, or
336 * Returns: Pointer to generic random number generator instance.
338 * Use: Creates a random number interface wrapper around
339 * the ChaCha or XChaCha stream ciphers.
342 extern grand *chacha20_rand(const void */*k*/, size_t /*ksz*/,
344 extern grand *chacha12_rand(const void */*k*/, size_t /*ksz*/,
346 extern grand *chacha8_rand(const void */*k*/, size_t /*ksz*/,
348 extern grand *chacha20_ietf_rand(const void */*k*/, size_t /*ksz*/,
350 extern grand *chacha12_ietf_rand(const void */*k*/, size_t /*ksz*/,
352 extern grand *chacha8_ietf_rand(const void */*k*/, size_t /*ksz*/,
354 extern grand *xchacha20_rand(const void */*k*/, size_t /*ksz*/,
356 extern grand *xchacha12_rand(const void */*k*/, size_t /*ksz*/,
358 extern grand *xchacha8_rand(const void */*k*/, size_t /*ksz*/,
362 CHACHA_SEEK = GRAND_SPECIFIC('S'), /* @unsigned long pos@ */
363 CHACHA_SEEKU64, /* @kludge64 pos@ */
364 CHACHA_TELL, /* @unsigned long *pos@ */
365 CHACHA_TELLU64 /* @kludge64 *pos@ */
368 /*----- That's all, folks -------------------------------------------------*/