2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 #ifndef BR_BEARSSL_BLOCK_H__
26 #define BR_BEARSSL_BLOCK_H__
31 /** \file bearssl_block.h
33 * # Block Ciphers and Symmetric Ciphers
35 * This file documents the API for block ciphers and other symmetric
41 * For a block cipher implementation, up to three separate sets of
42 * functions are provided, for CBC encryption, CBC decryption, and CTR
43 * encryption/decryption. Each set has its own context structure,
44 * initialised with the encryption key.
46 * For CBC encryption and decryption, the data to encrypt or decrypt is
47 * referenced as a sequence of blocks. The implementations assume that
48 * there is no partial block; no padding is applied or removed. The
49 * caller is responsible for handling any kind of padding.
51 * Function for CTR encryption are defined only for block ciphers with
52 * blocks of 16 bytes or more (i.e. AES, but not DES/3DES).
54 * Each implemented block cipher is identified by an "internal name"
55 * from which are derived the names of structures and functions that
56 * implement the cipher. For the block cipher of internal name "`xxx`",
57 * the following are defined:
59 * - `br_xxx_BLOCK_SIZE`
61 * A macro that evaluates to the block size (in bytes) of the
62 * cipher. For all implemented block ciphers, this value is a
65 * - `br_xxx_cbcenc_keys`
67 * Context structure that contains the subkeys resulting from the key
68 * expansion. These subkeys are appropriate for CBC encryption. The
69 * structure first field is called `vtable` and points to the
70 * appropriate OOP structure.
72 * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
74 * Perform key expansion: subkeys for CBC encryption are computed and
75 * written in the provided context structure. The key length MUST be
76 * adequate for the implemented block cipher. This function also sets
79 * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)`
81 * Perform CBC encryption of `len` bytes, in place. The encrypted data
82 * replaces the cleartext. `len` MUST be a multiple of the block length
83 * (if it is not, the function may loop forever or overflow a buffer).
84 * The IV is provided with the `iv` pointer; it is also updated with
85 * a copy of the last encrypted block.
87 * - `br_xxx_cbcdec_keys`
89 * Context structure that contains the subkeys resulting from the key
90 * expansion. These subkeys are appropriate for CBC decryption. The
91 * structure first field is called `vtable` and points to the
92 * appropriate OOP structure.
94 * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
96 * Perform key expansion: subkeys for CBC decryption are computed and
97 * written in the provided context structure. The key length MUST be
98 * adequate for the implemented block cipher. This function also sets
101 * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)`
103 * Perform CBC decryption of `len` bytes, in place. The decrypted data
104 * replaces the ciphertext. `len` MUST be a multiple of the block length
105 * (if it is not, the function may loop forever or overflow a buffer).
106 * The IV is provided with the `iv` pointer; it is also updated with
107 * a copy of the last _encrypted_ block.
109 * - `br_xxx_ctr_keys`
111 * Context structure that contains the subkeys resulting from the key
112 * expansion. These subkeys are appropriate for CTR encryption and
113 * decryption. The structure first field is called `vtable` and
114 * points to the appropriate OOP structure.
116 * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)`
118 * Perform key expansion: subkeys for CTR encryption and decryption
119 * are computed and written in the provided context structure. The
120 * key length MUST be adequate for the implemented block cipher. This
121 * function also sets the `vtable` field.
123 * - `br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len)` (returns `uint32_t`)
125 * Perform CTR encryption/decryption of some data. Processing is done
126 * "in place" (the output data replaces the input data). This function
127 * implements the "standard incrementing function" from NIST SP800-38A,
128 * annex B: the IV length shall be 4 bytes less than the block size
129 * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting
130 * with `cc`. The data length (`len`) is not necessarily a multiple of
131 * the block size. The new counter value is returned, which supports
132 * chunked processing, provided that each chunk length (except possibly
133 * the last one) is a multiple of the block size.
136 * It shall be noted that the key expansion functions return `void`. If
137 * the provided key length is not allowed, then there will be no error
138 * reporting; implementations need not validate the key length, thus an
139 * invalid key length may result in undefined behaviour (e.g. buffer
142 * Subkey structures contain no interior pointer, and no external
143 * resources are allocated upon key expansion. They can thus be
144 * discarded without any explicit deallocation.
147 * ## Object-Oriented API
149 * Each context structure begins with a field (called `vtable`) that
150 * points to an instance of a structure that references the relevant
151 * functions through pointers. Each such structure contains the
156 * The size (in bytes) of the context structure for subkeys.
160 * The cipher block size (in bytes).
164 * The base-2 logarithm of cipher block size (e.g. 4 for blocks
169 * Pointer to the key expansion function.
173 * Pointer to the encryption/decryption function.
176 * For block cipher "`xxx`", static, constant instances of these
177 * structures are defined, under the names:
179 * - `br_xxx_cbcenc_vtable`
180 * - `br_xxx_cbcdec_vtable`
181 * - `br_xxx_ctr_vtable`
184 * ## Implemented Block Ciphers
186 * Provided implementations are:
188 * | Name | Function | Block Size (bytes) | Key lengths (bytes) |
189 * | :-------- | :------- | :----------------: | :-----------------: |
190 * | aes_big | AES | 16 | 16, 24 and 32 |
191 * | aes_small | AES | 16 | 16, 24 and 32 |
192 * | aes_ct | AES | 16 | 16, 24 and 32 |
193 * | aes_ct64 | AES | 16 | 16, 24 and 32 |
194 * | aes_x86ni | AES | 16 | 16, 24 and 32 |
195 * | des_ct | DES/3DES | 8 | 8, 16 and 24 |
196 * | des_tab | DES/3DES | 8 | 8, 16 and 24 |
198 * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8,
199 * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so
200 * the _effective_ key lengths, from a security point of view, are 56,
201 * 112 and 168 bits, respectively.
203 * `aes_big` is a "classical" AES implementation, using tables. It
204 * is fast but not constant-time, since it makes data-dependent array
207 * `aes_small` is an AES implementation optimized for code size. It
208 * is substantially slower than `aes_big`; it is not constant-time
211 * `aes_ct` is a constant-time implementation of AES; its code is about
212 * as big as that of `aes_big`, while its performance is comparable to
213 * that of `aes_small`. However, it is constant-time. This
214 * implementation should thus be considered to be the "default" AES in
215 * BearSSL, to be used unless the operational context guarantees that a
216 * non-constant-time implementation is safe, or an architecture-specific
217 * constant-time implementation can be used (e.g. using dedicated
220 * `aes_ct64` is another constant-time implementation of AES. It is
221 * similar to `aes_ct` but uses 64-bit values. On 32-bit machines,
222 * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has
223 * a larger footprint; however, on 64-bit architectures, `aes_ct64`
224 * is typically twice faster than `aes_ct` for modes that allow parallel
225 * operations (i.e. CTR, and CBC decryption, but not CBC encryption).
227 * `aes_x86ni` exists only on x86 architectures (32-bit and 64-bit). It
228 * uses the AES-NI opcodes when available; if the opcodes are not present,
229 * then it automatically fall backs on an appropriate constant-time
230 * implementation (`aes_ct` for 32-bit, `aes_ct64` for 64-bit).
232 * `des_tab` is a classic, table-based implementation of DES/3DES. It
233 * is not constant-time.
235 * `des_ct` is an constant-time implementation of DES/3DES. It is
236 * substantially slower than `des_tab`.
238 * ## ChaCha20 and Poly1305
240 * ChaCha20 is a stream cipher. Poly1305 is a MAC algorithm. They
241 * are described in [RFC 7539](https://tools.ietf.org/html/rfc7539).
243 * Two function pointer types are defined:
245 * - `br_chacha20_run` describes a function that implements ChaCha20
248 * - `br_poly1305_run` describes an implementation of Poly1305,
249 * in the AEAD combination with ChaCha20 specified in RFC 7539
250 * (the ChaCha20 implementation is provided as a function pointer).
252 * `chacha20_ct` is a straightforward implementation of ChaCha20 in
253 * plain C; it is constant-time, small, and reasonably fast.
255 * `poly1305_ctmul` is an implementation of the ChaCha20+Poly1305 AEAD
256 * construction, where the Poly1305 part is performed with mixed 32-bit
257 * multiplications (operands are 32-bit, result is 64-bit).
261 * \brief Class type for CBC encryption implementations.
263 * A `br_block_cbcenc_class` instance points to the functions implementing
264 * a specific block cipher, when used in CBC mode for encrypting data.
266 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class
;
267 struct br_block_cbcenc_class_
{
269 * \brief Size (in bytes) of the context structure appropriate
270 * for containing subkeys.
275 * \brief Size of individual blocks (in bytes).
280 * \brief Base-2 logarithm of the size of individual blocks,
281 * expressed in bytes.
283 unsigned log_block_size
;
286 * \brief Initialisation function.
288 * This function sets the `vtable` field in the context structure.
289 * The key length MUST be one of the key lengths supported by
290 * the implementation.
292 * \param ctx context structure to initialise.
293 * \param key secret key.
294 * \param key_len key length (in bytes).
296 void (*init
)(const br_block_cbcenc_class
**ctx
,
297 const void *key
, size_t key_len
);
300 * \brief Run the CBC encryption.
302 * The `iv` parameter points to the IV for this run; it is
303 * updated with a copy of the last encrypted block. The data
304 * is encrypted "in place"; its length (`len`) MUST be a
305 * multiple of the block size.
307 * \param ctx context structure (already initialised).
308 * \param iv IV for CBC encryption (updated).
309 * \param data data to encrypt.
310 * \param len data length (in bytes, multiple of block size).
312 void (*run
)(const br_block_cbcenc_class
*const *ctx
,
313 void *iv
, void *data
, size_t len
);
317 * \brief Class type for CBC decryption implementations.
319 * A `br_block_cbcdec_class` instance points to the functions implementing
320 * a specific block cipher, when used in CBC mode for decrypting data.
322 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class
;
323 struct br_block_cbcdec_class_
{
325 * \brief Size (in bytes) of the context structure appropriate
326 * for containing subkeys.
331 * \brief Size of individual blocks (in bytes).
336 * \brief Base-2 logarithm of the size of individual blocks,
337 * expressed in bytes.
339 unsigned log_block_size
;
342 * \brief Initialisation function.
344 * This function sets the `vtable` field in the context structure.
345 * The key length MUST be one of the key lengths supported by
346 * the implementation.
348 * \param ctx context structure to initialise.
349 * \param key secret key.
350 * \param key_len key length (in bytes).
352 void (*init
)(const br_block_cbcdec_class
**ctx
,
353 const void *key
, size_t key_len
);
356 * \brief Run the CBC decryption.
358 * The `iv` parameter points to the IV for this run; it is
359 * updated with a copy of the last encrypted block. The data
360 * is decrypted "in place"; its length (`len`) MUST be a
361 * multiple of the block size.
363 * \param ctx context structure (already initialised).
364 * \param iv IV for CBC decryption (updated).
365 * \param data data to decrypt.
366 * \param len data length (in bytes, multiple of block size).
368 void (*run
)(const br_block_cbcdec_class
*const *ctx
,
369 void *iv
, void *data
, size_t len
);
373 * \brief Class type for CTR encryption/decryption implementations.
375 * A `br_block_ctr_class` instance points to the functions implementing
376 * a specific block cipher, when used in CTR mode for encrypting or
379 typedef struct br_block_ctr_class_ br_block_ctr_class
;
380 struct br_block_ctr_class_
{
382 * \brief Size (in bytes) of the context structure appropriate
383 * for containing subkeys.
388 * \brief Size of individual blocks (in bytes).
393 * \brief Base-2 logarithm of the size of individual blocks,
394 * expressed in bytes.
396 unsigned log_block_size
;
399 * \brief Initialisation function.
401 * This function sets the `vtable` field in the context structure.
402 * The key length MUST be one of the key lengths supported by
403 * the implementation.
405 * \param ctx context structure to initialise.
406 * \param key secret key.
407 * \param key_len key length (in bytes).
409 void (*init
)(const br_block_ctr_class
**ctx
,
410 const void *key
, size_t key_len
);
413 * \brief Run the CTR encryption or decryption.
415 * The `iv` parameter points to the IV for this run; its
416 * length is exactly 4 bytes less than the block size (e.g.
417 * 12 bytes for AES/CTR). The IV is combined with a 32-bit
418 * block counter to produce the block value which is processed
419 * with the block cipher.
421 * The data to encrypt or decrypt is updated "in place". Its
422 * length (`len` bytes) is not required to be a multiple of
423 * the block size; if the final block is partial, then the
424 * corresponding key stream bits are dropped.
426 * The resulting counter value is returned.
428 * \param ctx context structure (already initialised).
429 * \param iv IV for CTR encryption/decryption.
430 * \param cc initial value for the block counter.
431 * \param data data to encrypt or decrypt.
432 * \param len data length (in bytes).
433 * \return the new block counter value.
435 uint32_t (*run
)(const br_block_ctr_class
*const *ctx
,
436 const void *iv
, uint32_t cc
, void *data
, size_t len
);
440 * Traditional, table-based AES implementation. It is fast, but uses
441 * internal tables (in particular a 1 kB table for encryption, another
442 * 1 kB table for decryption, and a 256-byte table for key schedule),
443 * and it is not constant-time. In contexts where cache-timing attacks
444 * apply, this implementation may leak the secret key.
447 /** \brief AES block size (16 bytes). */
448 #define br_aes_big_BLOCK_SIZE 16
451 * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption).
453 * First field is a pointer to the vtable; it is set by the initialisation
454 * function. Other fields are not supposed to be accessed by user code.
457 /** \brief Pointer to vtable for this context. */
458 const br_block_cbcenc_class
*vtable
;
459 #ifndef BR_DOXYGEN_IGNORE
463 } br_aes_big_cbcenc_keys
;
466 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption).
468 * First field is a pointer to the vtable; it is set by the initialisation
469 * function. Other fields are not supposed to be accessed by user code.
472 /** \brief Pointer to vtable for this context. */
473 const br_block_cbcdec_class
*vtable
;
474 #ifndef BR_DOXYGEN_IGNORE
478 } br_aes_big_cbcdec_keys
;
481 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption
484 * First field is a pointer to the vtable; it is set by the initialisation
485 * function. Other fields are not supposed to be accessed by user code.
488 /** \brief Pointer to vtable for this context. */
489 const br_block_ctr_class
*vtable
;
490 #ifndef BR_DOXYGEN_IGNORE
494 } br_aes_big_ctr_keys
;
497 * \brief Class instance for AES CBC encryption (`aes_big` implementation).
499 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable
;
502 * \brief Class instance for AES CBC decryption (`aes_big` implementation).
504 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable
;
507 * \brief Class instance for AES CTR encryption and decryption
508 * (`aes_big` implementation).
510 extern const br_block_ctr_class br_aes_big_ctr_vtable
;
513 * \brief Context initialisation (key schedule) for AES CBC encryption
514 * (`aes_big` implementation).
516 * \param ctx context to initialise.
517 * \param key secret key.
518 * \param len secret key length (in bytes).
520 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys
*ctx
,
521 const void *key
, size_t len
);
524 * \brief Context initialisation (key schedule) for AES CBC decryption
525 * (`aes_big` implementation).
527 * \param ctx context to initialise.
528 * \param key secret key.
529 * \param len secret key length (in bytes).
531 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys
*ctx
,
532 const void *key
, size_t len
);
535 * \brief Context initialisation (key schedule) for AES CTR encryption
536 * and decryption (`aes_big` implementation).
538 * \param ctx context to initialise.
539 * \param key secret key.
540 * \param len secret key length (in bytes).
542 void br_aes_big_ctr_init(br_aes_big_ctr_keys
*ctx
,
543 const void *key
, size_t len
);
546 * \brief CBC encryption with AES (`aes_big` implementation).
548 * \param ctx context (already initialised).
549 * \param iv IV (updated).
550 * \param data data to encrypt (updated).
551 * \param len data length (in bytes, MUST be multiple of 16).
553 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys
*ctx
, void *iv
,
554 void *data
, size_t len
);
557 * \brief CBC decryption with AES (`aes_big` implementation).
559 * \param ctx context (already initialised).
560 * \param iv IV (updated).
561 * \param data data to decrypt (updated).
562 * \param len data length (in bytes, MUST be multiple of 16).
564 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys
*ctx
, void *iv
,
565 void *data
, size_t len
);
568 * \brief CTR encryption and decryption with AES (`aes_big` implementation).
570 * \param ctx context (already initialised).
571 * \param iv IV (constant, 12 bytes).
572 * \param cc initial block counter value.
573 * \param data data to decrypt (updated).
574 * \param len data length (in bytes).
575 * \return new block counter value.
577 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys
*ctx
,
578 const void *iv
, uint32_t cc
, void *data
, size_t len
);
581 * AES implementation optimized for size. It is slower than the
582 * traditional table-based AES implementation, but requires much less
583 * code. It still uses data-dependent table accesses (albeit within a
584 * much smaller 256-byte table), which makes it conceptually vulnerable
585 * to cache-timing attacks.
588 /** \brief AES block size (16 bytes). */
589 #define br_aes_small_BLOCK_SIZE 16
592 * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption).
594 * First field is a pointer to the vtable; it is set by the initialisation
595 * function. Other fields are not supposed to be accessed by user code.
598 /** \brief Pointer to vtable for this context. */
599 const br_block_cbcenc_class
*vtable
;
600 #ifndef BR_DOXYGEN_IGNORE
604 } br_aes_small_cbcenc_keys
;
607 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption).
609 * First field is a pointer to the vtable; it is set by the initialisation
610 * function. Other fields are not supposed to be accessed by user code.
613 /** \brief Pointer to vtable for this context. */
614 const br_block_cbcdec_class
*vtable
;
615 #ifndef BR_DOXYGEN_IGNORE
619 } br_aes_small_cbcdec_keys
;
622 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption
625 * First field is a pointer to the vtable; it is set by the initialisation
626 * function. Other fields are not supposed to be accessed by user code.
629 /** \brief Pointer to vtable for this context. */
630 const br_block_ctr_class
*vtable
;
631 #ifndef BR_DOXYGEN_IGNORE
635 } br_aes_small_ctr_keys
;
638 * \brief Class instance for AES CBC encryption (`aes_small` implementation).
640 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable
;
643 * \brief Class instance for AES CBC decryption (`aes_small` implementation).
645 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable
;
648 * \brief Class instance for AES CTR encryption and decryption
649 * (`aes_small` implementation).
651 extern const br_block_ctr_class br_aes_small_ctr_vtable
;
654 * \brief Context initialisation (key schedule) for AES CBC encryption
655 * (`aes_small` implementation).
657 * \param ctx context to initialise.
658 * \param key secret key.
659 * \param len secret key length (in bytes).
661 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys
*ctx
,
662 const void *key
, size_t len
);
665 * \brief Context initialisation (key schedule) for AES CBC decryption
666 * (`aes_small` implementation).
668 * \param ctx context to initialise.
669 * \param key secret key.
670 * \param len secret key length (in bytes).
672 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys
*ctx
,
673 const void *key
, size_t len
);
676 * \brief Context initialisation (key schedule) for AES CTR encryption
677 * and decryption (`aes_small` implementation).
679 * \param ctx context to initialise.
680 * \param key secret key.
681 * \param len secret key length (in bytes).
683 void br_aes_small_ctr_init(br_aes_small_ctr_keys
*ctx
,
684 const void *key
, size_t len
);
687 * \brief CBC encryption with AES (`aes_small` implementation).
689 * \param ctx context (already initialised).
690 * \param iv IV (updated).
691 * \param data data to encrypt (updated).
692 * \param len data length (in bytes, MUST be multiple of 16).
694 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys
*ctx
, void *iv
,
695 void *data
, size_t len
);
698 * \brief CBC decryption with AES (`aes_small` implementation).
700 * \param ctx context (already initialised).
701 * \param iv IV (updated).
702 * \param data data to decrypt (updated).
703 * \param len data length (in bytes, MUST be multiple of 16).
705 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys
*ctx
, void *iv
,
706 void *data
, size_t len
);
709 * \brief CTR encryption and decryption with AES (`aes_small` implementation).
711 * \param ctx context (already initialised).
712 * \param iv IV (constant, 12 bytes).
713 * \param cc initial block counter value.
714 * \param data data to decrypt (updated).
715 * \param len data length (in bytes).
716 * \return new block counter value.
718 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys
*ctx
,
719 const void *iv
, uint32_t cc
, void *data
, size_t len
);
722 * Constant-time AES implementation. Its size is similar to that of
723 * 'aes_big', and its performance is similar to that of 'aes_small' (faster
724 * decryption, slower encryption). However, it is constant-time, i.e.
725 * immune to cache-timing and similar attacks.
728 /** \brief AES block size (16 bytes). */
729 #define br_aes_ct_BLOCK_SIZE 16
732 * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption).
734 * First field is a pointer to the vtable; it is set by the initialisation
735 * function. Other fields are not supposed to be accessed by user code.
738 /** \brief Pointer to vtable for this context. */
739 const br_block_cbcenc_class
*vtable
;
740 #ifndef BR_DOXYGEN_IGNORE
744 } br_aes_ct_cbcenc_keys
;
747 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption).
749 * First field is a pointer to the vtable; it is set by the initialisation
750 * function. Other fields are not supposed to be accessed by user code.
753 /** \brief Pointer to vtable for this context. */
754 const br_block_cbcdec_class
*vtable
;
755 #ifndef BR_DOXYGEN_IGNORE
759 } br_aes_ct_cbcdec_keys
;
762 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption
765 * First field is a pointer to the vtable; it is set by the initialisation
766 * function. Other fields are not supposed to be accessed by user code.
769 /** \brief Pointer to vtable for this context. */
770 const br_block_ctr_class
*vtable
;
771 #ifndef BR_DOXYGEN_IGNORE
775 } br_aes_ct_ctr_keys
;
778 * \brief Class instance for AES CBC encryption (`aes_ct` implementation).
780 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable
;
783 * \brief Class instance for AES CBC decryption (`aes_ct` implementation).
785 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable
;
788 * \brief Class instance for AES CTR encryption and decryption
789 * (`aes_ct` implementation).
791 extern const br_block_ctr_class br_aes_ct_ctr_vtable
;
794 * \brief Context initialisation (key schedule) for AES CBC encryption
795 * (`aes_ct` implementation).
797 * \param ctx context to initialise.
798 * \param key secret key.
799 * \param len secret key length (in bytes).
801 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys
*ctx
,
802 const void *key
, size_t len
);
805 * \brief Context initialisation (key schedule) for AES CBC decryption
806 * (`aes_ct` implementation).
808 * \param ctx context to initialise.
809 * \param key secret key.
810 * \param len secret key length (in bytes).
812 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys
*ctx
,
813 const void *key
, size_t len
);
816 * \brief Context initialisation (key schedule) for AES CTR encryption
817 * and decryption (`aes_ct` implementation).
819 * \param ctx context to initialise.
820 * \param key secret key.
821 * \param len secret key length (in bytes).
823 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys
*ctx
,
824 const void *key
, size_t len
);
827 * \brief CBC encryption with AES (`aes_ct` implementation).
829 * \param ctx context (already initialised).
830 * \param iv IV (updated).
831 * \param data data to encrypt (updated).
832 * \param len data length (in bytes, MUST be multiple of 16).
834 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys
*ctx
, void *iv
,
835 void *data
, size_t len
);
838 * \brief CBC decryption with AES (`aes_ct` implementation).
840 * \param ctx context (already initialised).
841 * \param iv IV (updated).
842 * \param data data to decrypt (updated).
843 * \param len data length (in bytes, MUST be multiple of 16).
845 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys
*ctx
, void *iv
,
846 void *data
, size_t len
);
849 * \brief CTR encryption and decryption with AES (`aes_ct` implementation).
851 * \param ctx context (already initialised).
852 * \param iv IV (constant, 12 bytes).
853 * \param cc initial block counter value.
854 * \param data data to decrypt (updated).
855 * \param len data length (in bytes).
856 * \return new block counter value.
858 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys
*ctx
,
859 const void *iv
, uint32_t cc
, void *data
, size_t len
);
862 * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
863 * but uses 64-bit registers, making it about twice faster than 'aes_ct'
864 * on 64-bit platforms, while remaining constant-time and with a similar
865 * code size. (The doubling in performance is only for CBC decryption
866 * and CTR mode; CBC encryption is non-parallel and cannot benefit from
867 * the larger registers.)
870 /** \brief AES block size (16 bytes). */
871 #define br_aes_ct64_BLOCK_SIZE 16
874 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption).
876 * First field is a pointer to the vtable; it is set by the initialisation
877 * function. Other fields are not supposed to be accessed by user code.
880 /** \brief Pointer to vtable for this context. */
881 const br_block_cbcenc_class
*vtable
;
882 #ifndef BR_DOXYGEN_IGNORE
886 } br_aes_ct64_cbcenc_keys
;
889 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption).
891 * First field is a pointer to the vtable; it is set by the initialisation
892 * function. Other fields are not supposed to be accessed by user code.
895 /** \brief Pointer to vtable for this context. */
896 const br_block_cbcdec_class
*vtable
;
897 #ifndef BR_DOXYGEN_IGNORE
901 } br_aes_ct64_cbcdec_keys
;
904 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption
907 * First field is a pointer to the vtable; it is set by the initialisation
908 * function. Other fields are not supposed to be accessed by user code.
911 /** \brief Pointer to vtable for this context. */
912 const br_block_ctr_class
*vtable
;
913 #ifndef BR_DOXYGEN_IGNORE
917 } br_aes_ct64_ctr_keys
;
920 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation).
922 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable
;
925 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation).
927 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable
;
930 * \brief Class instance for AES CTR encryption and decryption
931 * (`aes_ct64` implementation).
933 extern const br_block_ctr_class br_aes_ct64_ctr_vtable
;
936 * \brief Context initialisation (key schedule) for AES CBC encryption
937 * (`aes_ct64` implementation).
939 * \param ctx context to initialise.
940 * \param key secret key.
941 * \param len secret key length (in bytes).
943 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys
*ctx
,
944 const void *key
, size_t len
);
947 * \brief Context initialisation (key schedule) for AES CBC decryption
948 * (`aes_ct64` implementation).
950 * \param ctx context to initialise.
951 * \param key secret key.
952 * \param len secret key length (in bytes).
954 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys
*ctx
,
955 const void *key
, size_t len
);
958 * \brief Context initialisation (key schedule) for AES CTR encryption
959 * and decryption (`aes_ct64` implementation).
961 * \param ctx context to initialise.
962 * \param key secret key.
963 * \param len secret key length (in bytes).
965 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys
*ctx
,
966 const void *key
, size_t len
);
969 * \brief CBC encryption with AES (`aes_ct64` implementation).
971 * \param ctx context (already initialised).
972 * \param iv IV (updated).
973 * \param data data to encrypt (updated).
974 * \param len data length (in bytes, MUST be multiple of 16).
976 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys
*ctx
, void *iv
,
977 void *data
, size_t len
);
980 * \brief CBC decryption with AES (`aes_ct64` implementation).
982 * \param ctx context (already initialised).
983 * \param iv IV (updated).
984 * \param data data to decrypt (updated).
985 * \param len data length (in bytes, MUST be multiple of 16).
987 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys
*ctx
, void *iv
,
988 void *data
, size_t len
);
991 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation).
993 * \param ctx context (already initialised).
994 * \param iv IV (constant, 12 bytes).
995 * \param cc initial block counter value.
996 * \param data data to decrypt (updated).
997 * \param len data length (in bytes).
998 * \return new block counter value.
1000 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys
*ctx
,
1001 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1004 * AES implementation using AES-NI opcode (x86 platform). When the
1005 * opcodes are not present, this falls back to "ct" or "ct64" (depending
1009 /** \brief AES block size (16 bytes). */
1010 #define br_aes_x86ni_BLOCK_SIZE 16
1013 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC encryption).
1015 * First field is a pointer to the vtable; it is set by the initialisation
1016 * function. Other fields are not supposed to be accessed by user code.
1019 /** \brief Pointer to vtable for this context. */
1020 const br_block_cbcenc_class
*vtable
;
1021 #ifndef BR_DOXYGEN_IGNORE
1023 unsigned char skni
[16 * 15];
1031 unsigned num_rounds
;
1033 } br_aes_x86ni_cbcenc_keys
;
1036 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC decryption).
1038 * First field is a pointer to the vtable; it is set by the initialisation
1039 * function. Other fields are not supposed to be accessed by user code.
1042 /** \brief Pointer to vtable for this context. */
1043 const br_block_cbcdec_class
*vtable
;
1044 #ifndef BR_DOXYGEN_IGNORE
1046 unsigned char skni
[16 * 15];
1054 unsigned num_rounds
;
1056 } br_aes_x86ni_cbcdec_keys
;
1059 * \brief Context for AES subkeys (`aes_x86ni` implementation, CTR encryption
1062 * First field is a pointer to the vtable; it is set by the initialisation
1063 * function. Other fields are not supposed to be accessed by user code.
1066 /** \brief Pointer to vtable for this context. */
1067 const br_block_ctr_class
*vtable
;
1068 #ifndef BR_DOXYGEN_IGNORE
1070 unsigned char skni
[16 * 15];
1078 unsigned num_rounds
;
1080 } br_aes_x86ni_ctr_keys
;
1083 * \brief Class instance for AES CBC encryption (`aes_x86ni` implementation).
1085 * Since this implementation might be omitted from the library, or the
1086 * AES opcode unavailable on the current CPU, a pointer to this class
1087 * instance should be obtained through `br_aes_x86ni_cbcenc_get_vtable()`.
1089 extern const br_block_cbcenc_class br_aes_x86ni_cbcenc_vtable
;
1092 * \brief Class instance for AES CBC decryption (`aes_x86ni` implementation).
1094 * Since this implementation might be omitted from the library, or the
1095 * AES opcode unavailable on the current CPU, a pointer to this class
1096 * instance should be obtained through `br_aes_x86ni_cbcdec_get_vtable()`.
1098 extern const br_block_cbcdec_class br_aes_x86ni_cbcdec_vtable
;
1101 * \brief Class instance for AES CTR encryption and decryption
1102 * (`aes_x86ni` implementation).
1104 * Since this implementation might be omitted from the library, or the
1105 * AES opcode unavailable on the current CPU, a pointer to this class
1106 * instance should be obtained through `br_aes_x86ni_ctr_get_vtable()`.
1108 extern const br_block_ctr_class br_aes_x86ni_ctr_vtable
;
1111 * \brief Context initialisation (key schedule) for AES CBC encryption
1112 * (`aes_x86ni` implementation).
1114 * \param ctx context to initialise.
1115 * \param key secret key.
1116 * \param len secret key length (in bytes).
1118 void br_aes_x86ni_cbcenc_init(br_aes_x86ni_cbcenc_keys
*ctx
,
1119 const void *key
, size_t len
);
1122 * \brief Context initialisation (key schedule) for AES CBC decryption
1123 * (`aes_x86ni` implementation).
1125 * \param ctx context to initialise.
1126 * \param key secret key.
1127 * \param len secret key length (in bytes).
1129 void br_aes_x86ni_cbcdec_init(br_aes_x86ni_cbcdec_keys
*ctx
,
1130 const void *key
, size_t len
);
1133 * \brief Context initialisation (key schedule) for AES CTR encryption
1134 * and decryption (`aes_x86ni` implementation).
1136 * \param ctx context to initialise.
1137 * \param key secret key.
1138 * \param len secret key length (in bytes).
1140 void br_aes_x86ni_ctr_init(br_aes_x86ni_ctr_keys
*ctx
,
1141 const void *key
, size_t len
);
1144 * \brief CBC encryption with AES (`aes_x86ni` implementation).
1146 * \param ctx context (already initialised).
1147 * \param iv IV (updated).
1148 * \param data data to encrypt (updated).
1149 * \param len data length (in bytes, MUST be multiple of 16).
1151 void br_aes_x86ni_cbcenc_run(const br_aes_x86ni_cbcenc_keys
*ctx
, void *iv
,
1152 void *data
, size_t len
);
1155 * \brief CBC decryption with AES (`aes_x86ni` implementation).
1157 * \param ctx context (already initialised).
1158 * \param iv IV (updated).
1159 * \param data data to decrypt (updated).
1160 * \param len data length (in bytes, MUST be multiple of 16).
1162 void br_aes_x86ni_cbcdec_run(const br_aes_x86ni_cbcdec_keys
*ctx
, void *iv
,
1163 void *data
, size_t len
);
1166 * \brief CTR encryption and decryption with AES (`aes_x86ni` implementation).
1168 * \param ctx context (already initialised).
1169 * \param iv IV (constant, 12 bytes).
1170 * \param cc initial block counter value.
1171 * \param data data to decrypt (updated).
1172 * \param len data length (in bytes).
1173 * \return new block counter value.
1175 uint32_t br_aes_x86ni_ctr_run(const br_aes_x86ni_ctr_keys
*ctx
,
1176 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1179 * \brief Obtain the `aes_x86ni` AES-CBC (encryption) implementation, if
1182 * This function returns a pointer to `br_aes_x86ni_cbcenc_vtable`, if
1183 * that implementation was compiled in the library _and_ the x86 AES
1184 * opcodes are available on the currently running CPU. If either of
1185 * these conditions is not met, then this function returns `NULL`.
1187 * \return the `aes_x868ni` AES-CBC (encryption) implementation, or `NULL`.
1189 const br_block_cbcenc_class
*br_aes_x86ni_cbcenc_get_vtable(void);
1192 * \brief Obtain the `aes_x86ni` AES-CBC (decryption) implementation, if
1195 * This function returns a pointer to `br_aes_x86ni_cbcdec_vtable`, if
1196 * that implementation was compiled in the library _and_ the x86 AES
1197 * opcodes are available on the currently running CPU. If either of
1198 * these conditions is not met, then this function returns `NULL`.
1200 * \return the `aes_x868ni` AES-CBC (decryption) implementation, or `NULL`.
1202 const br_block_cbcdec_class
*br_aes_x86ni_cbcdec_get_vtable(void);
1205 * \brief Obtain the `aes_x86ni` AES-CTR implementation, if available.
1207 * This function returns a pointer to `br_aes_x86ni_ctr_vtable`, if
1208 * that implementation was compiled in the library _and_ the x86 AES
1209 * opcodes are available on the currently running CPU. If either of
1210 * these conditions is not met, then this function returns `NULL`.
1212 * \return the `aes_x868ni` AES-CTR implementation, or `NULL`.
1214 const br_block_ctr_class
*br_aes_x86ni_ctr_get_vtable(void);
1217 * \brief Aggregate structure large enough to be used as context for
1218 * subkeys (CBC encryption) for all AES implementations.
1221 const br_block_cbcenc_class
*vtable
;
1222 br_aes_big_cbcenc_keys c_big
;
1223 br_aes_small_cbcenc_keys c_small
;
1224 br_aes_ct_cbcenc_keys c_ct
;
1225 br_aes_ct64_cbcenc_keys c_ct64
;
1226 br_aes_x86ni_cbcenc_keys c_x86ni
;
1227 } br_aes_gen_cbcenc_keys
;
1230 * \brief Aggregate structure large enough to be used as context for
1231 * subkeys (CBC decryption) for all AES implementations.
1234 const br_block_cbcdec_class
*vtable
;
1235 br_aes_big_cbcdec_keys c_big
;
1236 br_aes_small_cbcdec_keys c_small
;
1237 br_aes_ct_cbcdec_keys c_ct
;
1238 br_aes_ct64_cbcdec_keys c_ct64
;
1239 br_aes_x86ni_cbcdec_keys c_x86ni
;
1240 } br_aes_gen_cbcdec_keys
;
1243 * \brief Aggregate structure large enough to be used as context for
1244 * subkeys (CTR encryption and decryption) for all AES implementations.
1247 const br_block_ctr_class
*vtable
;
1248 br_aes_big_ctr_keys c_big
;
1249 br_aes_small_ctr_keys c_small
;
1250 br_aes_ct_ctr_keys c_ct
;
1251 br_aes_ct64_ctr_keys c_ct64
;
1252 br_aes_x86ni_ctr_keys c_x86ni
;
1253 } br_aes_gen_ctr_keys
;
1256 * Traditional, table-based implementation for DES/3DES. Since tables are
1257 * used, cache-timing attacks are conceptually possible.
1260 /** \brief DES/3DES block size (8 bytes). */
1261 #define br_des_tab_BLOCK_SIZE 8
1264 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption).
1266 * First field is a pointer to the vtable; it is set by the initialisation
1267 * function. Other fields are not supposed to be accessed by user code.
1270 /** \brief Pointer to vtable for this context. */
1271 const br_block_cbcenc_class
*vtable
;
1272 #ifndef BR_DOXYGEN_IGNORE
1274 unsigned num_rounds
;
1276 } br_des_tab_cbcenc_keys
;
1279 * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption).
1281 * First field is a pointer to the vtable; it is set by the initialisation
1282 * function. Other fields are not supposed to be accessed by user code.
1285 /** \brief Pointer to vtable for this context. */
1286 const br_block_cbcdec_class
*vtable
;
1287 #ifndef BR_DOXYGEN_IGNORE
1289 unsigned num_rounds
;
1291 } br_des_tab_cbcdec_keys
;
1294 * \brief Class instance for DES CBC encryption (`des_tab` implementation).
1296 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable
;
1299 * \brief Class instance for DES CBC decryption (`des_tab` implementation).
1301 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable
;
1304 * \brief Context initialisation (key schedule) for DES CBC encryption
1305 * (`des_tab` implementation).
1307 * \param ctx context to initialise.
1308 * \param key secret key.
1309 * \param len secret key length (in bytes).
1311 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys
*ctx
,
1312 const void *key
, size_t len
);
1315 * \brief Context initialisation (key schedule) for DES CBC decryption
1316 * (`des_tab` implementation).
1318 * \param ctx context to initialise.
1319 * \param key secret key.
1320 * \param len secret key length (in bytes).
1322 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys
*ctx
,
1323 const void *key
, size_t len
);
1326 * \brief CBC encryption with DES (`des_tab` implementation).
1328 * \param ctx context (already initialised).
1329 * \param iv IV (updated).
1330 * \param data data to encrypt (updated).
1331 * \param len data length (in bytes, MUST be multiple of 8).
1333 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys
*ctx
, void *iv
,
1334 void *data
, size_t len
);
1337 * \brief CBC decryption with DES (`des_tab` implementation).
1339 * \param ctx context (already initialised).
1340 * \param iv IV (updated).
1341 * \param data data to decrypt (updated).
1342 * \param len data length (in bytes, MUST be multiple of 8).
1344 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys
*ctx
, void *iv
,
1345 void *data
, size_t len
);
1348 * Constant-time implementation for DES/3DES. It is substantially slower
1349 * (by a factor of about 4x), but also immune to cache-timing attacks.
1352 /** \brief DES/3DES block size (8 bytes). */
1353 #define br_des_ct_BLOCK_SIZE 8
1356 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption).
1358 * First field is a pointer to the vtable; it is set by the initialisation
1359 * function. Other fields are not supposed to be accessed by user code.
1362 /** \brief Pointer to vtable for this context. */
1363 const br_block_cbcenc_class
*vtable
;
1364 #ifndef BR_DOXYGEN_IGNORE
1366 unsigned num_rounds
;
1368 } br_des_ct_cbcenc_keys
;
1371 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption).
1373 * First field is a pointer to the vtable; it is set by the initialisation
1374 * function. Other fields are not supposed to be accessed by user code.
1377 /** \brief Pointer to vtable for this context. */
1378 const br_block_cbcdec_class
*vtable
;
1379 #ifndef BR_DOXYGEN_IGNORE
1381 unsigned num_rounds
;
1383 } br_des_ct_cbcdec_keys
;
1386 * \brief Class instance for DES CBC encryption (`des_ct` implementation).
1388 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable
;
1391 * \brief Class instance for DES CBC decryption (`des_ct` implementation).
1393 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable
;
1396 * \brief Context initialisation (key schedule) for DES CBC encryption
1397 * (`des_ct` implementation).
1399 * \param ctx context to initialise.
1400 * \param key secret key.
1401 * \param len secret key length (in bytes).
1403 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys
*ctx
,
1404 const void *key
, size_t len
);
1407 * \brief Context initialisation (key schedule) for DES CBC decryption
1408 * (`des_ct` implementation).
1410 * \param ctx context to initialise.
1411 * \param key secret key.
1412 * \param len secret key length (in bytes).
1414 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys
*ctx
,
1415 const void *key
, size_t len
);
1418 * \brief CBC encryption with DES (`des_ct` implementation).
1420 * \param ctx context (already initialised).
1421 * \param iv IV (updated).
1422 * \param data data to encrypt (updated).
1423 * \param len data length (in bytes, MUST be multiple of 8).
1425 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys
*ctx
, void *iv
,
1426 void *data
, size_t len
);
1429 * \brief CBC decryption with DES (`des_ct` implementation).
1431 * \param ctx context (already initialised).
1432 * \param iv IV (updated).
1433 * \param data data to decrypt (updated).
1434 * \param len data length (in bytes, MUST be multiple of 8).
1436 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys
*ctx
, void *iv
,
1437 void *data
, size_t len
);
1440 * These structures are large enough to accommodate subkeys for all
1441 * DES/3DES implementations.
1445 * \brief Aggregate structure large enough to be used as context for
1446 * subkeys (CBC encryption) for all DES implementations.
1449 const br_block_cbcenc_class
*vtable
;
1450 br_des_tab_cbcenc_keys tab
;
1451 br_des_ct_cbcenc_keys ct
;
1452 } br_des_gen_cbcenc_keys
;
1455 * \brief Aggregate structure large enough to be used as context for
1456 * subkeys (CBC decryption) for all DES implementations.
1459 const br_block_cbcdec_class
*vtable
;
1460 br_des_tab_cbcdec_keys c_tab
;
1461 br_des_ct_cbcdec_keys c_ct
;
1462 } br_des_gen_cbcdec_keys
;
1465 * \brief Type for a ChaCha20 implementation.
1467 * An implementation follows the description in RFC 7539:
1469 * - Key is 256 bits (`key` points to exactly 32 bytes).
1471 * - IV is 96 bits (`iv` points to exactly 12 bytes).
1473 * - Block counter is over 32 bits and starts at value `cc`; the
1474 * resulting value is returned.
1476 * Data (pointed to by `data`, of length `len`) is encrypted/decrypted
1477 * in place. If `len` is not a multiple of 64, then the excess bytes from
1478 * the last block processing are dropped (therefore, "chunked" processing
1479 * works only as long as each non-final chunk has a length multiple of 64).
1481 * \param key secret key (32 bytes).
1482 * \param iv IV (12 bytes).
1483 * \param cc initial counter value.
1484 * \param data data to encrypt or decrypt.
1485 * \param len data length (in bytes).
1487 typedef uint32_t (*br_chacha20_run
)(const void *key
,
1488 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1491 * \brief ChaCha20 implementation (straightforward C code, constant-time).
1493 * \see br_chacha20_run
1495 * \param key secret key (32 bytes).
1496 * \param iv IV (12 bytes).
1497 * \param cc initial counter value.
1498 * \param data data to encrypt or decrypt.
1499 * \param len data length (in bytes).
1501 uint32_t br_chacha20_ct_run(const void *key
,
1502 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1505 * \brief Type for a ChaCha20+Poly1305 AEAD implementation.
1507 * The provided data is encrypted or decrypted with ChaCha20. The
1508 * authentication tag is computed on the concatenation of the
1509 * additional data and the ciphertext, with the padding and lengths
1510 * as described in RFC 7539 (section 2.8).
1512 * After decryption, the caller is responsible for checking that the
1513 * computed tag matches the expected value.
1515 * \param key secret key (32 bytes).
1516 * \param iv nonce (12 bytes).
1517 * \param data data to encrypt or decrypt.
1518 * \param len data length (in bytes).
1519 * \param aad additional authenticated data.
1520 * \param aad_len length of additional authenticated data (in bytes).
1521 * \param tag output buffer for the authentication tag.
1522 * \param ichacha implementation of ChaCha20.
1523 * \param encrypt non-zero for encryption, zero for decryption.
1525 typedef void (*br_poly1305_run
)(const void *key
, const void *iv
,
1526 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1527 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1530 * \brief ChaCha20+Poly1305 AEAD implementation (mixed 32-bit multiplications).
1532 * \see br_poly1305_run
1534 * \param key secret key (32 bytes).
1535 * \param iv nonce (12 bytes).
1536 * \param data data to encrypt or decrypt.
1537 * \param len data length (in bytes).
1538 * \param aad additional authenticated data.
1539 * \param aad_len length of additional authenticated data (in bytes).
1540 * \param tag output buffer for the authentication tag.
1541 * \param ichacha implementation of ChaCha20.
1542 * \param encrypt non-zero for encryption, zero for decryption.
1544 void br_poly1305_ctmul_run(const void *key
, const void *iv
,
1545 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1546 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1549 * \brief ChaCha20+Poly1305 AEAD implementation (pure 32-bit multiplications).
1551 * \see br_poly1305_run
1553 * \param key secret key (32 bytes).
1554 * \param iv nonce (12 bytes).
1555 * \param data data to encrypt or decrypt.
1556 * \param len data length (in bytes).
1557 * \param aad additional authenticated data.
1558 * \param aad_len length of additional authenticated data (in bytes).
1559 * \param tag output buffer for the authentication tag.
1560 * \param ichacha implementation of ChaCha20.
1561 * \param encrypt non-zero for encryption, zero for decryption.
1563 void br_poly1305_ctmul32_run(const void *key
, const void *iv
,
1564 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1565 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1568 * \brief ChaCha20+Poly1305 AEAD implementation (i15).
1570 * This implementation relies on the generic big integer code "i15"
1571 * (which uses pure 32-bit multiplications). As such, it may save a
1572 * little code footprint in a context where "i15" is already included
1573 * (e.g. for elliptic curves or for RSA); however, it is also
1574 * substantially slower than the ctmul and ctmul32 implementations.
1576 * \see br_poly1305_run
1578 * \param key secret key (32 bytes).
1579 * \param iv nonce (12 bytes).
1580 * \param data data to encrypt or decrypt.
1581 * \param len data length (in bytes).
1582 * \param aad additional authenticated data.
1583 * \param aad_len length of additional authenticated data (in bytes).
1584 * \param tag output buffer for the authentication tag.
1585 * \param ichacha implementation of ChaCha20.
1586 * \param encrypt non-zero for encryption, zero for decryption.
1588 void br_poly1305_i15_run(const void *key
, const void *iv
,
1589 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1590 void *tag
, br_chacha20_run ichacha
, int encrypt
);