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 * | des_ct | DES/3DES | 8 | 8, 16 and 24 |
195 * | des_tab | DES/3DES | 8 | 8, 16 and 24 |
197 * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8,
198 * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so
199 * the _effective_ key lengths, from a security point of view, are 56,
200 * 112 and 168 bits, respectively.
202 * `aes_big` is a "classical" AES implementation, using tables. It
203 * is fast but not constant-time, since it makes data-dependent array
206 * `aes_small` is an AES implementation optimized for code size. It
207 * is substantially slower than `aes_big`; it is not constant-time
210 * `aes_ct` is a constant-time implementation of AES; its code is about
211 * as big as that of `aes_big`, while its performance is comparable to
212 * that of `aes_small`. However, it is constant-time. This
213 * implementation should thus be considered to be the "default" AES in
214 * BearSSL, to be used unless the operational context guarantees that a
215 * non-constant-time implementation is safe, or an architecture-specific
216 * constant-time implementation can be used (e.g. using dedicated
219 * `aes_ct64` is another constant-time implementation of AES. It is
220 * similar to `aes_ct` but uses 64-bit values. On 32-bit machines,
221 * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has
222 * a larger footprint; however, on 64-bit architectures, `aes_ct64`
223 * is typically twice faster than `aes_ct` for modes that allow parallel
224 * operations (i.e. CTR, and CBC decryption, but not CBC encryption).
226 * `des_tab` is a classic, table-based implementation of DES/3DES. It
227 * is not constant-time.
229 * `des_ct` is an constant-time implementation of DES/3DES. It is
230 * substantially slower than `des_tab`.
232 * ## ChaCha20 and Poly1305
234 * ChaCha20 is a stream cipher. Poly1305 is a MAC algorithm. They
235 * are described in [RFC 7539](https://tools.ietf.org/html/rfc7539).
237 * Two function pointer types are defined:
239 * - `br_chacha20_run` describes a function that implements ChaCha20
242 * - `br_poly1305_run` describes an implementation of Poly1305,
243 * in the AEAD combination with ChaCha20 specified in RFC 7539
244 * (the ChaCha20 implementation is provided as a function pointer).
246 * `chacha20_ct` is a straightforward implementation of ChaCha20 in
247 * plain C; it is constant-time, small, and reasonably fast.
249 * `poly1305_ctmul` is an implementation of the ChaCha20+Poly1305 AEAD
250 * construction, where the Poly1305 part is performed with mixed 32-bit
251 * multiplications (operands are 32-bit, result is 64-bit).
255 * \brief Class type for CBC encryption implementations.
257 * A `br_block_cbcenc_class` instance points to the functions implementing
258 * a specific block cipher, when used in CBC mode for encrypting data.
260 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class
;
261 struct br_block_cbcenc_class_
{
263 * \brief Size (in bytes) of the context structure appropriate
264 * for containing subkeys.
269 * \brief Size of individual blocks (in bytes).
274 * \brief Base-2 logarithm of the size of individual blocks,
275 * expressed in bytes.
277 unsigned log_block_size
;
280 * \brief Initialisation function.
282 * This function sets the `vtable` field in the context structure.
283 * The key length MUST be one of the key lengths supported by
284 * the implementation.
286 * \param ctx context structure to initialise.
287 * \param key secret key.
288 * \param key_len key length (in bytes).
290 void (*init
)(const br_block_cbcenc_class
**ctx
,
291 const void *key
, size_t key_len
);
294 * \brief Run the CBC encryption.
296 * The `iv` parameter points to the IV for this run; it is
297 * updated with a copy of the last encrypted block. The data
298 * is encrypted "in place"; its length (`len`) MUST be a
299 * multiple of the block size.
301 * \param ctx context structure (already initialised).
302 * \param iv IV for CBC encryption (updated).
303 * \param data data to encrypt.
304 * \param len data length (in bytes, multiple of block size).
306 void (*run
)(const br_block_cbcenc_class
*const *ctx
,
307 void *iv
, void *data
, size_t len
);
311 * \brief Class type for CBC decryption implementations.
313 * A `br_block_cbcdec_class` instance points to the functions implementing
314 * a specific block cipher, when used in CBC mode for decrypting data.
316 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class
;
317 struct br_block_cbcdec_class_
{
319 * \brief Size (in bytes) of the context structure appropriate
320 * for containing subkeys.
325 * \brief Size of individual blocks (in bytes).
330 * \brief Base-2 logarithm of the size of individual blocks,
331 * expressed in bytes.
333 unsigned log_block_size
;
336 * \brief Initialisation function.
338 * This function sets the `vtable` field in the context structure.
339 * The key length MUST be one of the key lengths supported by
340 * the implementation.
342 * \param ctx context structure to initialise.
343 * \param key secret key.
344 * \param key_len key length (in bytes).
346 void (*init
)(const br_block_cbcdec_class
**ctx
,
347 const void *key
, size_t key_len
);
350 * \brief Run the CBC decryption.
352 * The `iv` parameter points to the IV for this run; it is
353 * updated with a copy of the last encrypted block. The data
354 * is decrypted "in place"; its length (`len`) MUST be a
355 * multiple of the block size.
357 * \param ctx context structure (already initialised).
358 * \param iv IV for CBC decryption (updated).
359 * \param data data to decrypt.
360 * \param len data length (in bytes, multiple of block size).
362 void (*run
)(const br_block_cbcdec_class
*const *ctx
,
363 void *iv
, void *data
, size_t len
);
367 * \brief Class type for CTR encryption/decryption implementations.
369 * A `br_block_ctr_class` instance points to the functions implementing
370 * a specific block cipher, when used in CTR mode for encrypting or
373 typedef struct br_block_ctr_class_ br_block_ctr_class
;
374 struct br_block_ctr_class_
{
376 * \brief Size (in bytes) of the context structure appropriate
377 * for containing subkeys.
382 * \brief Size of individual blocks (in bytes).
387 * \brief Base-2 logarithm of the size of individual blocks,
388 * expressed in bytes.
390 unsigned log_block_size
;
393 * \brief Initialisation function.
395 * This function sets the `vtable` field in the context structure.
396 * The key length MUST be one of the key lengths supported by
397 * the implementation.
399 * \param ctx context structure to initialise.
400 * \param key secret key.
401 * \param key_len key length (in bytes).
403 void (*init
)(const br_block_ctr_class
**ctx
,
404 const void *key
, size_t key_len
);
407 * \brief Run the CTR encryption or decryption.
409 * The `iv` parameter points to the IV for this run; its
410 * length is exactly 4 bytes less than the block size (e.g.
411 * 12 bytes for AES/CTR). The IV is combined with a 32-bit
412 * block counter to produce the block value which is processed
413 * with the block cipher.
415 * The data to encrypt or decrypt is updated "in place". Its
416 * length (`len` bytes) is not required to be a multiple of
417 * the block size; if the final block is partial, then the
418 * corresponding key stream bits are dropped.
420 * The resulting counter value is returned.
422 * \param ctx context structure (already initialised).
423 * \param iv IV for CTR encryption/decryption.
424 * \param cc initial value for the block counter.
425 * \param data data to encrypt or decrypt.
426 * \param len data length (in bytes).
427 * \return the new block counter value.
429 uint32_t (*run
)(const br_block_ctr_class
*const *ctx
,
430 const void *iv
, uint32_t cc
, void *data
, size_t len
);
434 * Traditional, table-based AES implementation. It is fast, but uses
435 * internal tables (in particular a 1 kB table for encryption, another
436 * 1 kB table for decryption, and a 256-byte table for key schedule),
437 * and it is not constant-time. In contexts where cache-timing attacks
438 * apply, this implementation may leak the secret key.
441 /** \brief AES block size (16 bytes). */
442 #define br_aes_big_BLOCK_SIZE 16
445 * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption).
447 * First field is a pointer to the vtable; it is set by the initialisation
448 * function. Other fields are not supposed to be accessed by user code.
451 /** \brief Pointer to vtable for this context. */
452 const br_block_cbcenc_class
*vtable
;
453 #ifndef BR_DOXYGEN_IGNORE
457 } br_aes_big_cbcenc_keys
;
460 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption).
462 * First field is a pointer to the vtable; it is set by the initialisation
463 * function. Other fields are not supposed to be accessed by user code.
466 /** \brief Pointer to vtable for this context. */
467 const br_block_cbcdec_class
*vtable
;
468 #ifndef BR_DOXYGEN_IGNORE
472 } br_aes_big_cbcdec_keys
;
475 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption
478 * First field is a pointer to the vtable; it is set by the initialisation
479 * function. Other fields are not supposed to be accessed by user code.
482 /** \brief Pointer to vtable for this context. */
483 const br_block_ctr_class
*vtable
;
484 #ifndef BR_DOXYGEN_IGNORE
488 } br_aes_big_ctr_keys
;
491 * \brief Class instance for AES CBC encryption (`aes_big` implementation).
493 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable
;
496 * \brief Class instance for AES CBC decryption (`aes_big` implementation).
498 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable
;
501 * \brief Class instance for AES CTR encryption and decryption
502 * (`aes_big` implementation).
504 extern const br_block_ctr_class br_aes_big_ctr_vtable
;
507 * \brief Context initialisation (key schedule) for AES CBC encryption
508 * (`aes_big` implementation).
510 * \param ctx context to initialise.
511 * \param key secret key.
512 * \param len secret key length (in bytes).
514 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys
*ctx
,
515 const void *key
, size_t len
);
518 * \brief Context initialisation (key schedule) for AES CBC decryption
519 * (`aes_big` implementation).
521 * \param ctx context to initialise.
522 * \param key secret key.
523 * \param len secret key length (in bytes).
525 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys
*ctx
,
526 const void *key
, size_t len
);
529 * \brief Context initialisation (key schedule) for AES CTR encryption
530 * and decryption (`aes_big` implementation).
532 * \param ctx context to initialise.
533 * \param key secret key.
534 * \param len secret key length (in bytes).
536 void br_aes_big_ctr_init(br_aes_big_ctr_keys
*ctx
,
537 const void *key
, size_t len
);
540 * \brief CBC encryption with AES (`aes_big` implementation).
542 * \param ctx context (already initialised).
543 * \param iv IV (updated).
544 * \param data data to encrypt (updated).
545 * \param len data length (in bytes, MUST be multiple of 16).
547 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys
*ctx
, void *iv
,
548 void *data
, size_t len
);
551 * \brief CBC decryption with AES (`aes_big` implementation).
553 * \param ctx context (already initialised).
554 * \param iv IV (updated).
555 * \param data data to decrypt (updated).
556 * \param len data length (in bytes, MUST be multiple of 16).
558 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys
*ctx
, void *iv
,
559 void *data
, size_t len
);
562 * \brief CTR encryption and decryption with AES (`aes_big` implementation).
564 * \param ctx context (already initialised).
565 * \param iv IV (constant, 12 bytes).
566 * \param cc initial block counter value.
567 * \param data data to decrypt (updated).
568 * \param len data length (in bytes).
569 * \return new block counter value.
571 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys
*ctx
,
572 const void *iv
, uint32_t cc
, void *data
, size_t len
);
575 * AES implementation optimized for size. It is slower than the
576 * traditional table-based AES implementation, but requires much less
577 * code. It still uses data-dependent table accesses (albeit within a
578 * much smaller 256-byte table), which makes it conceptually vulnerable
579 * to cache-timing attacks.
582 /** \brief AES block size (16 bytes). */
583 #define br_aes_small_BLOCK_SIZE 16
586 * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption).
588 * First field is a pointer to the vtable; it is set by the initialisation
589 * function. Other fields are not supposed to be accessed by user code.
592 /** \brief Pointer to vtable for this context. */
593 const br_block_cbcenc_class
*vtable
;
594 #ifndef BR_DOXYGEN_IGNORE
598 } br_aes_small_cbcenc_keys
;
601 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption).
603 * First field is a pointer to the vtable; it is set by the initialisation
604 * function. Other fields are not supposed to be accessed by user code.
607 /** \brief Pointer to vtable for this context. */
608 const br_block_cbcdec_class
*vtable
;
609 #ifndef BR_DOXYGEN_IGNORE
613 } br_aes_small_cbcdec_keys
;
616 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption
619 * First field is a pointer to the vtable; it is set by the initialisation
620 * function. Other fields are not supposed to be accessed by user code.
623 /** \brief Pointer to vtable for this context. */
624 const br_block_ctr_class
*vtable
;
625 #ifndef BR_DOXYGEN_IGNORE
629 } br_aes_small_ctr_keys
;
632 * \brief Class instance for AES CBC encryption (`aes_small` implementation).
634 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable
;
637 * \brief Class instance for AES CBC decryption (`aes_small` implementation).
639 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable
;
642 * \brief Class instance for AES CTR encryption and decryption
643 * (`aes_small` implementation).
645 extern const br_block_ctr_class br_aes_small_ctr_vtable
;
648 * \brief Context initialisation (key schedule) for AES CBC encryption
649 * (`aes_small` implementation).
651 * \param ctx context to initialise.
652 * \param key secret key.
653 * \param len secret key length (in bytes).
655 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys
*ctx
,
656 const void *key
, size_t len
);
659 * \brief Context initialisation (key schedule) for AES CBC decryption
660 * (`aes_small` implementation).
662 * \param ctx context to initialise.
663 * \param key secret key.
664 * \param len secret key length (in bytes).
666 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys
*ctx
,
667 const void *key
, size_t len
);
670 * \brief Context initialisation (key schedule) for AES CTR encryption
671 * and decryption (`aes_small` implementation).
673 * \param ctx context to initialise.
674 * \param key secret key.
675 * \param len secret key length (in bytes).
677 void br_aes_small_ctr_init(br_aes_small_ctr_keys
*ctx
,
678 const void *key
, size_t len
);
681 * \brief CBC encryption with AES (`aes_small` implementation).
683 * \param ctx context (already initialised).
684 * \param iv IV (updated).
685 * \param data data to encrypt (updated).
686 * \param len data length (in bytes, MUST be multiple of 16).
688 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys
*ctx
, void *iv
,
689 void *data
, size_t len
);
692 * \brief CBC decryption with AES (`aes_small` implementation).
694 * \param ctx context (already initialised).
695 * \param iv IV (updated).
696 * \param data data to decrypt (updated).
697 * \param len data length (in bytes, MUST be multiple of 16).
699 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys
*ctx
, void *iv
,
700 void *data
, size_t len
);
703 * \brief CTR encryption and decryption with AES (`aes_small` implementation).
705 * \param ctx context (already initialised).
706 * \param iv IV (constant, 12 bytes).
707 * \param cc initial block counter value.
708 * \param data data to decrypt (updated).
709 * \param len data length (in bytes).
710 * \return new block counter value.
712 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys
*ctx
,
713 const void *iv
, uint32_t cc
, void *data
, size_t len
);
716 * Constant-time AES implementation. Its size is similar to that of
717 * 'aes_big', and its performance is similar to that of 'aes_small' (faster
718 * decryption, slower encryption). However, it is constant-time, i.e.
719 * immune to cache-timing and similar attacks.
722 /** \brief AES block size (16 bytes). */
723 #define br_aes_ct_BLOCK_SIZE 16
726 * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption).
728 * First field is a pointer to the vtable; it is set by the initialisation
729 * function. Other fields are not supposed to be accessed by user code.
732 /** \brief Pointer to vtable for this context. */
733 const br_block_cbcenc_class
*vtable
;
734 #ifndef BR_DOXYGEN_IGNORE
738 } br_aes_ct_cbcenc_keys
;
741 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption).
743 * First field is a pointer to the vtable; it is set by the initialisation
744 * function. Other fields are not supposed to be accessed by user code.
747 /** \brief Pointer to vtable for this context. */
748 const br_block_cbcdec_class
*vtable
;
749 #ifndef BR_DOXYGEN_IGNORE
753 } br_aes_ct_cbcdec_keys
;
756 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption
759 * First field is a pointer to the vtable; it is set by the initialisation
760 * function. Other fields are not supposed to be accessed by user code.
763 /** \brief Pointer to vtable for this context. */
764 const br_block_ctr_class
*vtable
;
765 #ifndef BR_DOXYGEN_IGNORE
769 } br_aes_ct_ctr_keys
;
772 * \brief Class instance for AES CBC encryption (`aes_ct` implementation).
774 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable
;
777 * \brief Class instance for AES CBC decryption (`aes_ct` implementation).
779 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable
;
782 * \brief Class instance for AES CTR encryption and decryption
783 * (`aes_ct` implementation).
785 extern const br_block_ctr_class br_aes_ct_ctr_vtable
;
788 * \brief Context initialisation (key schedule) for AES CBC encryption
789 * (`aes_ct` implementation).
791 * \param ctx context to initialise.
792 * \param key secret key.
793 * \param len secret key length (in bytes).
795 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys
*ctx
,
796 const void *key
, size_t len
);
799 * \brief Context initialisation (key schedule) for AES CBC decryption
800 * (`aes_ct` implementation).
802 * \param ctx context to initialise.
803 * \param key secret key.
804 * \param len secret key length (in bytes).
806 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys
*ctx
,
807 const void *key
, size_t len
);
810 * \brief Context initialisation (key schedule) for AES CTR encryption
811 * and decryption (`aes_ct` implementation).
813 * \param ctx context to initialise.
814 * \param key secret key.
815 * \param len secret key length (in bytes).
817 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys
*ctx
,
818 const void *key
, size_t len
);
821 * \brief CBC encryption with AES (`aes_ct` implementation).
823 * \param ctx context (already initialised).
824 * \param iv IV (updated).
825 * \param data data to encrypt (updated).
826 * \param len data length (in bytes, MUST be multiple of 16).
828 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys
*ctx
, void *iv
,
829 void *data
, size_t len
);
832 * \brief CBC decryption with AES (`aes_ct` implementation).
834 * \param ctx context (already initialised).
835 * \param iv IV (updated).
836 * \param data data to decrypt (updated).
837 * \param len data length (in bytes, MUST be multiple of 16).
839 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys
*ctx
, void *iv
,
840 void *data
, size_t len
);
843 * \brief CTR encryption and decryption with AES (`aes_ct` implementation).
845 * \param ctx context (already initialised).
846 * \param iv IV (constant, 12 bytes).
847 * \param cc initial block counter value.
848 * \param data data to decrypt (updated).
849 * \param len data length (in bytes).
850 * \return new block counter value.
852 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys
*ctx
,
853 const void *iv
, uint32_t cc
, void *data
, size_t len
);
856 * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
857 * but uses 64-bit registers, making it about twice faster than 'aes_ct'
858 * on 64-bit platforms, while remaining constant-time and with a similar
859 * code size. (The doubling in performance is only for CBC decryption
860 * and CTR mode; CBC encryption is non-parallel and cannot benefit from
861 * the larger registers.)
864 /** \brief AES block size (16 bytes). */
865 #define br_aes_ct64_BLOCK_SIZE 16
868 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption).
870 * First field is a pointer to the vtable; it is set by the initialisation
871 * function. Other fields are not supposed to be accessed by user code.
874 /** \brief Pointer to vtable for this context. */
875 const br_block_cbcenc_class
*vtable
;
876 #ifndef BR_DOXYGEN_IGNORE
880 } br_aes_ct64_cbcenc_keys
;
883 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption).
885 * First field is a pointer to the vtable; it is set by the initialisation
886 * function. Other fields are not supposed to be accessed by user code.
889 /** \brief Pointer to vtable for this context. */
890 const br_block_cbcdec_class
*vtable
;
891 #ifndef BR_DOXYGEN_IGNORE
895 } br_aes_ct64_cbcdec_keys
;
898 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption
901 * First field is a pointer to the vtable; it is set by the initialisation
902 * function. Other fields are not supposed to be accessed by user code.
905 /** \brief Pointer to vtable for this context. */
906 const br_block_ctr_class
*vtable
;
907 #ifndef BR_DOXYGEN_IGNORE
911 } br_aes_ct64_ctr_keys
;
914 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation).
916 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable
;
919 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation).
921 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable
;
924 * \brief Class instance for AES CTR encryption and decryption
925 * (`aes_ct64` implementation).
927 extern const br_block_ctr_class br_aes_ct64_ctr_vtable
;
930 * \brief Context initialisation (key schedule) for AES CBC encryption
931 * (`aes_ct64` implementation).
933 * \param ctx context to initialise.
934 * \param key secret key.
935 * \param len secret key length (in bytes).
937 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys
*ctx
,
938 const void *key
, size_t len
);
941 * \brief Context initialisation (key schedule) for AES CBC decryption
942 * (`aes_ct64` implementation).
944 * \param ctx context to initialise.
945 * \param key secret key.
946 * \param len secret key length (in bytes).
948 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys
*ctx
,
949 const void *key
, size_t len
);
952 * \brief Context initialisation (key schedule) for AES CTR encryption
953 * and decryption (`aes_ct64` implementation).
955 * \param ctx context to initialise.
956 * \param key secret key.
957 * \param len secret key length (in bytes).
959 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys
*ctx
,
960 const void *key
, size_t len
);
963 * \brief CBC encryption with AES (`aes_ct64` implementation).
965 * \param ctx context (already initialised).
966 * \param iv IV (updated).
967 * \param data data to encrypt (updated).
968 * \param len data length (in bytes, MUST be multiple of 16).
970 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys
*ctx
, void *iv
,
971 void *data
, size_t len
);
974 * \brief CBC decryption with AES (`aes_ct64` implementation).
976 * \param ctx context (already initialised).
977 * \param iv IV (updated).
978 * \param data data to decrypt (updated).
979 * \param len data length (in bytes, MUST be multiple of 16).
981 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys
*ctx
, void *iv
,
982 void *data
, size_t len
);
985 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation).
987 * \param ctx context (already initialised).
988 * \param iv IV (constant, 12 bytes).
989 * \param cc initial block counter value.
990 * \param data data to decrypt (updated).
991 * \param len data length (in bytes).
992 * \return new block counter value.
994 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys
*ctx
,
995 const void *iv
, uint32_t cc
, void *data
, size_t len
);
998 * \brief Aggregate structure large enough to be used as context for
999 * subkeys (CBC encryption) for all AES implementations.
1002 const br_block_cbcenc_class
*vtable
;
1003 br_aes_big_cbcenc_keys big
;
1004 br_aes_small_cbcenc_keys small
;
1005 br_aes_ct_cbcenc_keys ct
;
1006 br_aes_ct64_cbcenc_keys ct64
;
1007 } br_aes_gen_cbcenc_keys
;
1010 * \brief Aggregate structure large enough to be used as context for
1011 * subkeys (CBC decryption) for all AES implementations.
1014 const br_block_cbcdec_class
*vtable
;
1015 br_aes_big_cbcdec_keys big
;
1016 br_aes_small_cbcdec_keys small
;
1017 br_aes_ct_cbcdec_keys ct
;
1018 br_aes_ct64_cbcdec_keys ct64
;
1019 } br_aes_gen_cbcdec_keys
;
1022 * \brief Aggregate structure large enough to be used as context for
1023 * subkeys (CTR encryption and decryption) for all AES implementations.
1026 const br_block_ctr_class
*vtable
;
1027 br_aes_big_ctr_keys big
;
1028 br_aes_small_ctr_keys small
;
1029 br_aes_ct_ctr_keys ct
;
1030 br_aes_ct64_ctr_keys ct64
;
1031 } br_aes_gen_ctr_keys
;
1034 * Traditional, table-based implementation for DES/3DES. Since tables are
1035 * used, cache-timing attacks are conceptually possible.
1038 /** \brief DES/3DES block size (8 bytes). */
1039 #define br_des_tab_BLOCK_SIZE 8
1042 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption).
1044 * First field is a pointer to the vtable; it is set by the initialisation
1045 * function. Other fields are not supposed to be accessed by user code.
1048 /** \brief Pointer to vtable for this context. */
1049 const br_block_cbcenc_class
*vtable
;
1050 #ifndef BR_DOXYGEN_IGNORE
1052 unsigned num_rounds
;
1054 } br_des_tab_cbcenc_keys
;
1057 * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption).
1059 * First field is a pointer to the vtable; it is set by the initialisation
1060 * function. Other fields are not supposed to be accessed by user code.
1063 /** \brief Pointer to vtable for this context. */
1064 const br_block_cbcdec_class
*vtable
;
1065 #ifndef BR_DOXYGEN_IGNORE
1067 unsigned num_rounds
;
1069 } br_des_tab_cbcdec_keys
;
1072 * \brief Class instance for DES CBC encryption (`des_tab` implementation).
1074 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable
;
1077 * \brief Class instance for DES CBC decryption (`des_tab` implementation).
1079 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable
;
1082 * \brief Context initialisation (key schedule) for DES CBC encryption
1083 * (`des_tab` implementation).
1085 * \param ctx context to initialise.
1086 * \param key secret key.
1087 * \param len secret key length (in bytes).
1089 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys
*ctx
,
1090 const void *key
, size_t len
);
1093 * \brief Context initialisation (key schedule) for DES CBC decryption
1094 * (`des_tab` implementation).
1096 * \param ctx context to initialise.
1097 * \param key secret key.
1098 * \param len secret key length (in bytes).
1100 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys
*ctx
,
1101 const void *key
, size_t len
);
1104 * \brief CBC encryption with DES (`des_tab` implementation).
1106 * \param ctx context (already initialised).
1107 * \param iv IV (updated).
1108 * \param data data to encrypt (updated).
1109 * \param len data length (in bytes, MUST be multiple of 8).
1111 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys
*ctx
, void *iv
,
1112 void *data
, size_t len
);
1115 * \brief CBC decryption with DES (`des_tab` implementation).
1117 * \param ctx context (already initialised).
1118 * \param iv IV (updated).
1119 * \param data data to decrypt (updated).
1120 * \param len data length (in bytes, MUST be multiple of 8).
1122 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys
*ctx
, void *iv
,
1123 void *data
, size_t len
);
1126 * Constant-time implementation for DES/3DES. It is substantially slower
1127 * (by a factor of about 4x), but also immune to cache-timing attacks.
1130 /** \brief DES/3DES block size (8 bytes). */
1131 #define br_des_ct_BLOCK_SIZE 8
1134 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption).
1136 * First field is a pointer to the vtable; it is set by the initialisation
1137 * function. Other fields are not supposed to be accessed by user code.
1140 /** \brief Pointer to vtable for this context. */
1141 const br_block_cbcenc_class
*vtable
;
1142 #ifndef BR_DOXYGEN_IGNORE
1144 unsigned num_rounds
;
1146 } br_des_ct_cbcenc_keys
;
1149 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption).
1151 * First field is a pointer to the vtable; it is set by the initialisation
1152 * function. Other fields are not supposed to be accessed by user code.
1155 /** \brief Pointer to vtable for this context. */
1156 const br_block_cbcdec_class
*vtable
;
1157 #ifndef BR_DOXYGEN_IGNORE
1159 unsigned num_rounds
;
1161 } br_des_ct_cbcdec_keys
;
1164 * \brief Class instance for DES CBC encryption (`des_ct` implementation).
1166 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable
;
1169 * \brief Class instance for DES CBC decryption (`des_ct` implementation).
1171 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable
;
1174 * \brief Context initialisation (key schedule) for DES CBC encryption
1175 * (`des_ct` implementation).
1177 * \param ctx context to initialise.
1178 * \param key secret key.
1179 * \param len secret key length (in bytes).
1181 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys
*ctx
,
1182 const void *key
, size_t len
);
1185 * \brief Context initialisation (key schedule) for DES CBC decryption
1186 * (`des_ct` implementation).
1188 * \param ctx context to initialise.
1189 * \param key secret key.
1190 * \param len secret key length (in bytes).
1192 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys
*ctx
,
1193 const void *key
, size_t len
);
1196 * \brief CBC encryption with DES (`des_ct` implementation).
1198 * \param ctx context (already initialised).
1199 * \param iv IV (updated).
1200 * \param data data to encrypt (updated).
1201 * \param len data length (in bytes, MUST be multiple of 8).
1203 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys
*ctx
, void *iv
,
1204 void *data
, size_t len
);
1207 * \brief CBC decryption with DES (`des_ct` implementation).
1209 * \param ctx context (already initialised).
1210 * \param iv IV (updated).
1211 * \param data data to decrypt (updated).
1212 * \param len data length (in bytes, MUST be multiple of 8).
1214 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys
*ctx
, void *iv
,
1215 void *data
, size_t len
);
1218 * These structures are large enough to accommodate subkeys for all
1219 * DES/3DES implementations.
1223 * \brief Aggregate structure large enough to be used as context for
1224 * subkeys (CBC encryption) for all DES implementations.
1227 const br_block_cbcenc_class
*vtable
;
1228 br_des_tab_cbcenc_keys tab
;
1229 br_des_ct_cbcenc_keys ct
;
1230 } br_des_gen_cbcenc_keys
;
1233 * \brief Aggregate structure large enough to be used as context for
1234 * subkeys (CBC decryption) for all DES implementations.
1237 const br_block_cbcdec_class
*vtable
;
1238 br_des_tab_cbcdec_keys tab
;
1239 br_des_ct_cbcdec_keys ct
;
1240 } br_des_gen_cbcdec_keys
;
1243 * \brief Type for a ChaCha20 implementation.
1245 * An implementation follows the description in RFC 7539:
1247 * - Key is 256 bits (`key` points to exactly 32 bytes).
1249 * - IV is 96 bits (`iv` points to exactly 12 bytes).
1251 * - Block counter is over 32 bits and starts at value `cc`; the
1252 * resulting value is returned.
1254 * Data (pointed to by `data`, of length `len`) is encrypted/decrypted
1255 * in place. If `len` is not a multiple of 64, then the excess bytes from
1256 * the last block processing are dropped (therefore, "chunked" processing
1257 * works only as long as each non-final chunk has a length multiple of 64).
1259 * \param key secret key (32 bytes).
1260 * \param iv IV (12 bytes).
1261 * \param cc initial counter value.
1262 * \param data data to encrypt or decrypt.
1263 * \param len data length (in bytes).
1265 typedef uint32_t (*br_chacha20_run
)(const void *key
,
1266 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1269 * \brief ChaCha20 implementation (straightforward C code, constant-time).
1271 * \see br_chacha20_run
1273 * \param key secret key (32 bytes).
1274 * \param iv IV (12 bytes).
1275 * \param cc initial counter value.
1276 * \param data data to encrypt or decrypt.
1277 * \param len data length (in bytes).
1279 uint32_t br_chacha20_ct_run(const void *key
,
1280 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1283 * \brief Type for a ChaCha20+Poly1305 AEAD implementation.
1285 * The provided data is encrypted or decrypted with ChaCha20. The
1286 * authentication tag is computed on the concatenation of the
1287 * additional data and the ciphertext, with the padding and lengths
1288 * as described in RFC 7539 (section 2.8).
1290 * After decryption, the caller is responsible for checking that the
1291 * computed tag matches the expected value.
1293 * \param key secret key (32 bytes).
1294 * \param iv nonce (12 bytes).
1295 * \param data data to encrypt or decrypt.
1296 * \param len data length (in bytes).
1297 * \param aad additional authenticated data.
1298 * \param aad_len length of additional authenticated data (in bytes).
1299 * \param tag output buffer for the authentication tag.
1300 * \param ichacha implementation of ChaCha20.
1301 * \param encrypt non-zero for encryption, zero for decryption.
1303 typedef void (*br_poly1305_run
)(const void *key
, const void *iv
,
1304 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1305 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1308 * \brief ChaCha20+Poly1305 AEAD implementation (mixed 32-bit multiplications).
1310 * \see br_poly1305_run
1312 * \param key secret key (32 bytes).
1313 * \param iv nonce (12 bytes).
1314 * \param data data to encrypt or decrypt.
1315 * \param len data length (in bytes).
1316 * \param aad additional authenticated data.
1317 * \param aad_len length of additional authenticated data (in bytes).
1318 * \param tag output buffer for the authentication tag.
1319 * \param ichacha implementation of ChaCha20.
1320 * \param encrypt non-zero for encryption, zero for decryption.
1322 void br_poly1305_ctmul_run(const void *key
, const void *iv
,
1323 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1324 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1327 * \brief ChaCha20+Poly1305 AEAD implementation (pure 32-bit multiplications).
1329 * \see br_poly1305_run
1331 * \param key secret key (32 bytes).
1332 * \param iv nonce (12 bytes).
1333 * \param data data to encrypt or decrypt.
1334 * \param len data length (in bytes).
1335 * \param aad additional authenticated data.
1336 * \param aad_len length of additional authenticated data (in bytes).
1337 * \param tag output buffer for the authentication tag.
1338 * \param ichacha implementation of ChaCha20.
1339 * \param encrypt non-zero for encryption, zero for decryption.
1341 void br_poly1305_ctmul32_run(const void *key
, const void *iv
,
1342 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1343 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1346 * \brief ChaCha20+Poly1305 AEAD implementation (i15).
1348 * This implementation relies on the generic big integer code "i15"
1349 * (which uses pure 32-bit multiplications). As such, it may save a
1350 * little code footprint in a context where "i15" is already included
1351 * (e.g. for elliptic curves or for RSA); however, it is also
1352 * substantially slower than the ctmul and ctmul32 implementations.
1354 * \see br_poly1305_run
1356 * \param key secret key (32 bytes).
1357 * \param iv nonce (12 bytes).
1358 * \param data data to encrypt or decrypt.
1359 * \param len data length (in bytes).
1360 * \param aad additional authenticated data.
1361 * \param aad_len length of additional authenticated data (in bytes).
1362 * \param tag output buffer for the authentication tag.
1363 * \param ichacha implementation of ChaCha20.
1364 * \param encrypt non-zero for encryption, zero for decryption.
1366 void br_poly1305_i15_run(const void *key
, const void *iv
,
1367 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1368 void *tag
, br_chacha20_run ichacha
, int encrypt
);