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__
35 /** \file bearssl_block.h
37 * # Block Ciphers and Symmetric Ciphers
39 * This file documents the API for block ciphers and other symmetric
45 * For a block cipher implementation, up to three separate sets of
46 * functions are provided, for CBC encryption, CBC decryption, and CTR
47 * encryption/decryption. Each set has its own context structure,
48 * initialised with the encryption key.
50 * For CBC encryption and decryption, the data to encrypt or decrypt is
51 * referenced as a sequence of blocks. The implementations assume that
52 * there is no partial block; no padding is applied or removed. The
53 * caller is responsible for handling any kind of padding.
55 * Function for CTR encryption are defined only for block ciphers with
56 * blocks of 16 bytes or more (i.e. AES, but not DES/3DES).
58 * Each implemented block cipher is identified by an "internal name"
59 * from which are derived the names of structures and functions that
60 * implement the cipher. For the block cipher of internal name "`xxx`",
61 * the following are defined:
63 * - `br_xxx_BLOCK_SIZE`
65 * A macro that evaluates to the block size (in bytes) of the
66 * cipher. For all implemented block ciphers, this value is a
69 * - `br_xxx_cbcenc_keys`
71 * Context structure that contains the subkeys resulting from the key
72 * expansion. These subkeys are appropriate for CBC encryption. The
73 * structure first field is called `vtable` and points to the
74 * appropriate OOP structure.
76 * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
78 * Perform key expansion: subkeys for CBC encryption are computed and
79 * written in the provided context structure. The key length MUST be
80 * adequate for the implemented block cipher. This function also sets
83 * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)`
85 * Perform CBC encryption of `len` bytes, in place. The encrypted data
86 * replaces the cleartext. `len` MUST be a multiple of the block length
87 * (if it is not, the function may loop forever or overflow a buffer).
88 * The IV is provided with the `iv` pointer; it is also updated with
89 * a copy of the last encrypted block.
91 * - `br_xxx_cbcdec_keys`
93 * Context structure that contains the subkeys resulting from the key
94 * expansion. These subkeys are appropriate for CBC decryption. The
95 * structure first field is called `vtable` and points to the
96 * appropriate OOP structure.
98 * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
100 * Perform key expansion: subkeys for CBC decryption are computed and
101 * written in the provided context structure. The key length MUST be
102 * adequate for the implemented block cipher. This function also sets
103 * the `vtable` field.
105 * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)`
107 * Perform CBC decryption of `len` bytes, in place. The decrypted data
108 * replaces the ciphertext. `len` MUST be a multiple of the block length
109 * (if it is not, the function may loop forever or overflow a buffer).
110 * The IV is provided with the `iv` pointer; it is also updated with
111 * a copy of the last _encrypted_ block.
113 * - `br_xxx_ctr_keys`
115 * Context structure that contains the subkeys resulting from the key
116 * expansion. These subkeys are appropriate for CTR encryption and
117 * decryption. The structure first field is called `vtable` and
118 * points to the appropriate OOP structure.
120 * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)`
122 * Perform key expansion: subkeys for CTR encryption and decryption
123 * are computed and written in the provided context structure. The
124 * key length MUST be adequate for the implemented block cipher. This
125 * function also sets the `vtable` field.
127 * - `br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len)` (returns `uint32_t`)
129 * Perform CTR encryption/decryption of some data. Processing is done
130 * "in place" (the output data replaces the input data). This function
131 * implements the "standard incrementing function" from NIST SP800-38A,
132 * annex B: the IV length shall be 4 bytes less than the block size
133 * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting
134 * with `cc`. The data length (`len`) is not necessarily a multiple of
135 * the block size. The new counter value is returned, which supports
136 * chunked processing, provided that each chunk length (except possibly
137 * the last one) is a multiple of the block size.
140 * It shall be noted that the key expansion functions return `void`. If
141 * the provided key length is not allowed, then there will be no error
142 * reporting; implementations need not validate the key length, thus an
143 * invalid key length may result in undefined behaviour (e.g. buffer
146 * Subkey structures contain no interior pointer, and no external
147 * resources are allocated upon key expansion. They can thus be
148 * discarded without any explicit deallocation.
151 * ## Object-Oriented API
153 * Each context structure begins with a field (called `vtable`) that
154 * points to an instance of a structure that references the relevant
155 * functions through pointers. Each such structure contains the
160 * The size (in bytes) of the context structure for subkeys.
164 * The cipher block size (in bytes).
168 * The base-2 logarithm of cipher block size (e.g. 4 for blocks
173 * Pointer to the key expansion function.
177 * Pointer to the encryption/decryption function.
180 * For block cipher "`xxx`", static, constant instances of these
181 * structures are defined, under the names:
183 * - `br_xxx_cbcenc_vtable`
184 * - `br_xxx_cbcdec_vtable`
185 * - `br_xxx_ctr_vtable`
188 * ## Implemented Block Ciphers
190 * Provided implementations are:
192 * | Name | Function | Block Size (bytes) | Key lengths (bytes) |
193 * | :-------- | :------- | :----------------: | :-----------------: |
194 * | aes_big | AES | 16 | 16, 24 and 32 |
195 * | aes_small | AES | 16 | 16, 24 and 32 |
196 * | aes_ct | AES | 16 | 16, 24 and 32 |
197 * | aes_ct64 | AES | 16 | 16, 24 and 32 |
198 * | aes_x86ni | AES | 16 | 16, 24 and 32 |
199 * | aes_pwr8 | AES | 16 | 16, 24 and 32 |
200 * | des_ct | DES/3DES | 8 | 8, 16 and 24 |
201 * | des_tab | DES/3DES | 8 | 8, 16 and 24 |
203 * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8,
204 * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so
205 * the _effective_ key lengths, from a security point of view, are 56,
206 * 112 and 168 bits, respectively.
208 * `aes_big` is a "classical" AES implementation, using tables. It
209 * is fast but not constant-time, since it makes data-dependent array
212 * `aes_small` is an AES implementation optimized for code size. It
213 * is substantially slower than `aes_big`; it is not constant-time
216 * `aes_ct` is a constant-time implementation of AES; its code is about
217 * as big as that of `aes_big`, while its performance is comparable to
218 * that of `aes_small`. However, it is constant-time. This
219 * implementation should thus be considered to be the "default" AES in
220 * BearSSL, to be used unless the operational context guarantees that a
221 * non-constant-time implementation is safe, or an architecture-specific
222 * constant-time implementation can be used (e.g. using dedicated
225 * `aes_ct64` is another constant-time implementation of AES. It is
226 * similar to `aes_ct` but uses 64-bit values. On 32-bit machines,
227 * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has
228 * a larger footprint; however, on 64-bit architectures, `aes_ct64`
229 * is typically twice faster than `aes_ct` for modes that allow parallel
230 * operations (i.e. CTR, and CBC decryption, but not CBC encryption).
232 * `aes_x86ni` exists only on x86 architectures (32-bit and 64-bit). It
233 * uses the AES-NI opcodes when available.
235 * `aes_pwr8` exists only on PowerPC / POWER architectures (32-bit and
236 * 64-bit, both little-endian and big-endian). It uses the AES opcodes
237 * present in POWER8 and later.
239 * `des_tab` is a classic, table-based implementation of DES/3DES. It
240 * is not constant-time.
242 * `des_ct` is an constant-time implementation of DES/3DES. It is
243 * substantially slower than `des_tab`.
245 * ## ChaCha20 and Poly1305
247 * ChaCha20 is a stream cipher. Poly1305 is a MAC algorithm. They
248 * are described in [RFC 7539](https://tools.ietf.org/html/rfc7539).
250 * Two function pointer types are defined:
252 * - `br_chacha20_run` describes a function that implements ChaCha20
255 * - `br_poly1305_run` describes an implementation of Poly1305,
256 * in the AEAD combination with ChaCha20 specified in RFC 7539
257 * (the ChaCha20 implementation is provided as a function pointer).
259 * `chacha20_ct` is a straightforward implementation of ChaCha20 in
260 * plain C; it is constant-time, small, and reasonably fast.
262 * `poly1305_ctmul` is an implementation of the ChaCha20+Poly1305 AEAD
263 * construction, where the Poly1305 part is performed with mixed 32-bit
264 * multiplications (operands are 32-bit, result is 64-bit).
268 * \brief Class type for CBC encryption implementations.
270 * A `br_block_cbcenc_class` instance points to the functions implementing
271 * a specific block cipher, when used in CBC mode for encrypting data.
273 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class
;
274 struct br_block_cbcenc_class_
{
276 * \brief Size (in bytes) of the context structure appropriate
277 * for containing subkeys.
282 * \brief Size of individual blocks (in bytes).
287 * \brief Base-2 logarithm of the size of individual blocks,
288 * expressed in bytes.
290 unsigned log_block_size
;
293 * \brief Initialisation function.
295 * This function sets the `vtable` field in the context structure.
296 * The key length MUST be one of the key lengths supported by
297 * the implementation.
299 * \param ctx context structure to initialise.
300 * \param key secret key.
301 * \param key_len key length (in bytes).
303 void (*init
)(const br_block_cbcenc_class
**ctx
,
304 const void *key
, size_t key_len
);
307 * \brief Run the CBC encryption.
309 * The `iv` parameter points to the IV for this run; it is
310 * updated with a copy of the last encrypted block. The data
311 * is encrypted "in place"; its length (`len`) MUST be a
312 * multiple of the block size.
314 * \param ctx context structure (already initialised).
315 * \param iv IV for CBC encryption (updated).
316 * \param data data to encrypt.
317 * \param len data length (in bytes, multiple of block size).
319 void (*run
)(const br_block_cbcenc_class
*const *ctx
,
320 void *iv
, void *data
, size_t len
);
324 * \brief Class type for CBC decryption implementations.
326 * A `br_block_cbcdec_class` instance points to the functions implementing
327 * a specific block cipher, when used in CBC mode for decrypting data.
329 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class
;
330 struct br_block_cbcdec_class_
{
332 * \brief Size (in bytes) of the context structure appropriate
333 * for containing subkeys.
338 * \brief Size of individual blocks (in bytes).
343 * \brief Base-2 logarithm of the size of individual blocks,
344 * expressed in bytes.
346 unsigned log_block_size
;
349 * \brief Initialisation function.
351 * This function sets the `vtable` field in the context structure.
352 * The key length MUST be one of the key lengths supported by
353 * the implementation.
355 * \param ctx context structure to initialise.
356 * \param key secret key.
357 * \param key_len key length (in bytes).
359 void (*init
)(const br_block_cbcdec_class
**ctx
,
360 const void *key
, size_t key_len
);
363 * \brief Run the CBC decryption.
365 * The `iv` parameter points to the IV for this run; it is
366 * updated with a copy of the last encrypted block. The data
367 * is decrypted "in place"; its length (`len`) MUST be a
368 * multiple of the block size.
370 * \param ctx context structure (already initialised).
371 * \param iv IV for CBC decryption (updated).
372 * \param data data to decrypt.
373 * \param len data length (in bytes, multiple of block size).
375 void (*run
)(const br_block_cbcdec_class
*const *ctx
,
376 void *iv
, void *data
, size_t len
);
380 * \brief Class type for CTR encryption/decryption implementations.
382 * A `br_block_ctr_class` instance points to the functions implementing
383 * a specific block cipher, when used in CTR mode for encrypting or
386 typedef struct br_block_ctr_class_ br_block_ctr_class
;
387 struct br_block_ctr_class_
{
389 * \brief Size (in bytes) of the context structure appropriate
390 * for containing subkeys.
395 * \brief Size of individual blocks (in bytes).
400 * \brief Base-2 logarithm of the size of individual blocks,
401 * expressed in bytes.
403 unsigned log_block_size
;
406 * \brief Initialisation function.
408 * This function sets the `vtable` field in the context structure.
409 * The key length MUST be one of the key lengths supported by
410 * the implementation.
412 * \param ctx context structure to initialise.
413 * \param key secret key.
414 * \param key_len key length (in bytes).
416 void (*init
)(const br_block_ctr_class
**ctx
,
417 const void *key
, size_t key_len
);
420 * \brief Run the CTR encryption or decryption.
422 * The `iv` parameter points to the IV for this run; its
423 * length is exactly 4 bytes less than the block size (e.g.
424 * 12 bytes for AES/CTR). The IV is combined with a 32-bit
425 * block counter to produce the block value which is processed
426 * with the block cipher.
428 * The data to encrypt or decrypt is updated "in place". Its
429 * length (`len` bytes) is not required to be a multiple of
430 * the block size; if the final block is partial, then the
431 * corresponding key stream bits are dropped.
433 * The resulting counter value is returned.
435 * \param ctx context structure (already initialised).
436 * \param iv IV for CTR encryption/decryption.
437 * \param cc initial value for the block counter.
438 * \param data data to encrypt or decrypt.
439 * \param len data length (in bytes).
440 * \return the new block counter value.
442 uint32_t (*run
)(const br_block_ctr_class
*const *ctx
,
443 const void *iv
, uint32_t cc
, void *data
, size_t len
);
447 * Traditional, table-based AES implementation. It is fast, but uses
448 * internal tables (in particular a 1 kB table for encryption, another
449 * 1 kB table for decryption, and a 256-byte table for key schedule),
450 * and it is not constant-time. In contexts where cache-timing attacks
451 * apply, this implementation may leak the secret key.
454 /** \brief AES block size (16 bytes). */
455 #define br_aes_big_BLOCK_SIZE 16
458 * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption).
460 * First field is a pointer to the vtable; it is set by the initialisation
461 * function. Other fields are not supposed to be accessed by user code.
464 /** \brief Pointer to vtable for this context. */
465 const br_block_cbcenc_class
*vtable
;
466 #ifndef BR_DOXYGEN_IGNORE
470 } br_aes_big_cbcenc_keys
;
473 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption).
475 * First field is a pointer to the vtable; it is set by the initialisation
476 * function. Other fields are not supposed to be accessed by user code.
479 /** \brief Pointer to vtable for this context. */
480 const br_block_cbcdec_class
*vtable
;
481 #ifndef BR_DOXYGEN_IGNORE
485 } br_aes_big_cbcdec_keys
;
488 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption
491 * First field is a pointer to the vtable; it is set by the initialisation
492 * function. Other fields are not supposed to be accessed by user code.
495 /** \brief Pointer to vtable for this context. */
496 const br_block_ctr_class
*vtable
;
497 #ifndef BR_DOXYGEN_IGNORE
501 } br_aes_big_ctr_keys
;
504 * \brief Class instance for AES CBC encryption (`aes_big` implementation).
506 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable
;
509 * \brief Class instance for AES CBC decryption (`aes_big` implementation).
511 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable
;
514 * \brief Class instance for AES CTR encryption and decryption
515 * (`aes_big` implementation).
517 extern const br_block_ctr_class br_aes_big_ctr_vtable
;
520 * \brief Context initialisation (key schedule) for AES CBC encryption
521 * (`aes_big` implementation).
523 * \param ctx context to initialise.
524 * \param key secret key.
525 * \param len secret key length (in bytes).
527 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys
*ctx
,
528 const void *key
, size_t len
);
531 * \brief Context initialisation (key schedule) for AES CBC decryption
532 * (`aes_big` implementation).
534 * \param ctx context to initialise.
535 * \param key secret key.
536 * \param len secret key length (in bytes).
538 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys
*ctx
,
539 const void *key
, size_t len
);
542 * \brief Context initialisation (key schedule) for AES CTR encryption
543 * and decryption (`aes_big` implementation).
545 * \param ctx context to initialise.
546 * \param key secret key.
547 * \param len secret key length (in bytes).
549 void br_aes_big_ctr_init(br_aes_big_ctr_keys
*ctx
,
550 const void *key
, size_t len
);
553 * \brief CBC encryption with AES (`aes_big` implementation).
555 * \param ctx context (already initialised).
556 * \param iv IV (updated).
557 * \param data data to encrypt (updated).
558 * \param len data length (in bytes, MUST be multiple of 16).
560 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys
*ctx
, void *iv
,
561 void *data
, size_t len
);
564 * \brief CBC decryption with AES (`aes_big` implementation).
566 * \param ctx context (already initialised).
567 * \param iv IV (updated).
568 * \param data data to decrypt (updated).
569 * \param len data length (in bytes, MUST be multiple of 16).
571 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys
*ctx
, void *iv
,
572 void *data
, size_t len
);
575 * \brief CTR encryption and decryption with AES (`aes_big` implementation).
577 * \param ctx context (already initialised).
578 * \param iv IV (constant, 12 bytes).
579 * \param cc initial block counter value.
580 * \param data data to decrypt (updated).
581 * \param len data length (in bytes).
582 * \return new block counter value.
584 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys
*ctx
,
585 const void *iv
, uint32_t cc
, void *data
, size_t len
);
588 * AES implementation optimized for size. It is slower than the
589 * traditional table-based AES implementation, but requires much less
590 * code. It still uses data-dependent table accesses (albeit within a
591 * much smaller 256-byte table), which makes it conceptually vulnerable
592 * to cache-timing attacks.
595 /** \brief AES block size (16 bytes). */
596 #define br_aes_small_BLOCK_SIZE 16
599 * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption).
601 * First field is a pointer to the vtable; it is set by the initialisation
602 * function. Other fields are not supposed to be accessed by user code.
605 /** \brief Pointer to vtable for this context. */
606 const br_block_cbcenc_class
*vtable
;
607 #ifndef BR_DOXYGEN_IGNORE
611 } br_aes_small_cbcenc_keys
;
614 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption).
616 * First field is a pointer to the vtable; it is set by the initialisation
617 * function. Other fields are not supposed to be accessed by user code.
620 /** \brief Pointer to vtable for this context. */
621 const br_block_cbcdec_class
*vtable
;
622 #ifndef BR_DOXYGEN_IGNORE
626 } br_aes_small_cbcdec_keys
;
629 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption
632 * First field is a pointer to the vtable; it is set by the initialisation
633 * function. Other fields are not supposed to be accessed by user code.
636 /** \brief Pointer to vtable for this context. */
637 const br_block_ctr_class
*vtable
;
638 #ifndef BR_DOXYGEN_IGNORE
642 } br_aes_small_ctr_keys
;
645 * \brief Class instance for AES CBC encryption (`aes_small` implementation).
647 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable
;
650 * \brief Class instance for AES CBC decryption (`aes_small` implementation).
652 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable
;
655 * \brief Class instance for AES CTR encryption and decryption
656 * (`aes_small` implementation).
658 extern const br_block_ctr_class br_aes_small_ctr_vtable
;
661 * \brief Context initialisation (key schedule) for AES CBC encryption
662 * (`aes_small` implementation).
664 * \param ctx context to initialise.
665 * \param key secret key.
666 * \param len secret key length (in bytes).
668 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys
*ctx
,
669 const void *key
, size_t len
);
672 * \brief Context initialisation (key schedule) for AES CBC decryption
673 * (`aes_small` implementation).
675 * \param ctx context to initialise.
676 * \param key secret key.
677 * \param len secret key length (in bytes).
679 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys
*ctx
,
680 const void *key
, size_t len
);
683 * \brief Context initialisation (key schedule) for AES CTR encryption
684 * and decryption (`aes_small` implementation).
686 * \param ctx context to initialise.
687 * \param key secret key.
688 * \param len secret key length (in bytes).
690 void br_aes_small_ctr_init(br_aes_small_ctr_keys
*ctx
,
691 const void *key
, size_t len
);
694 * \brief CBC encryption with AES (`aes_small` implementation).
696 * \param ctx context (already initialised).
697 * \param iv IV (updated).
698 * \param data data to encrypt (updated).
699 * \param len data length (in bytes, MUST be multiple of 16).
701 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys
*ctx
, void *iv
,
702 void *data
, size_t len
);
705 * \brief CBC decryption with AES (`aes_small` implementation).
707 * \param ctx context (already initialised).
708 * \param iv IV (updated).
709 * \param data data to decrypt (updated).
710 * \param len data length (in bytes, MUST be multiple of 16).
712 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys
*ctx
, void *iv
,
713 void *data
, size_t len
);
716 * \brief CTR encryption and decryption with AES (`aes_small` implementation).
718 * \param ctx context (already initialised).
719 * \param iv IV (constant, 12 bytes).
720 * \param cc initial block counter value.
721 * \param data data to decrypt (updated).
722 * \param len data length (in bytes).
723 * \return new block counter value.
725 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys
*ctx
,
726 const void *iv
, uint32_t cc
, void *data
, size_t len
);
729 * Constant-time AES implementation. Its size is similar to that of
730 * 'aes_big', and its performance is similar to that of 'aes_small' (faster
731 * decryption, slower encryption). However, it is constant-time, i.e.
732 * immune to cache-timing and similar attacks.
735 /** \brief AES block size (16 bytes). */
736 #define br_aes_ct_BLOCK_SIZE 16
739 * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption).
741 * First field is a pointer to the vtable; it is set by the initialisation
742 * function. Other fields are not supposed to be accessed by user code.
745 /** \brief Pointer to vtable for this context. */
746 const br_block_cbcenc_class
*vtable
;
747 #ifndef BR_DOXYGEN_IGNORE
751 } br_aes_ct_cbcenc_keys
;
754 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption).
756 * First field is a pointer to the vtable; it is set by the initialisation
757 * function. Other fields are not supposed to be accessed by user code.
760 /** \brief Pointer to vtable for this context. */
761 const br_block_cbcdec_class
*vtable
;
762 #ifndef BR_DOXYGEN_IGNORE
766 } br_aes_ct_cbcdec_keys
;
769 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption
772 * First field is a pointer to the vtable; it is set by the initialisation
773 * function. Other fields are not supposed to be accessed by user code.
776 /** \brief Pointer to vtable for this context. */
777 const br_block_ctr_class
*vtable
;
778 #ifndef BR_DOXYGEN_IGNORE
782 } br_aes_ct_ctr_keys
;
785 * \brief Class instance for AES CBC encryption (`aes_ct` implementation).
787 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable
;
790 * \brief Class instance for AES CBC decryption (`aes_ct` implementation).
792 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable
;
795 * \brief Class instance for AES CTR encryption and decryption
796 * (`aes_ct` implementation).
798 extern const br_block_ctr_class br_aes_ct_ctr_vtable
;
801 * \brief Context initialisation (key schedule) for AES CBC encryption
802 * (`aes_ct` implementation).
804 * \param ctx context to initialise.
805 * \param key secret key.
806 * \param len secret key length (in bytes).
808 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys
*ctx
,
809 const void *key
, size_t len
);
812 * \brief Context initialisation (key schedule) for AES CBC decryption
813 * (`aes_ct` implementation).
815 * \param ctx context to initialise.
816 * \param key secret key.
817 * \param len secret key length (in bytes).
819 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys
*ctx
,
820 const void *key
, size_t len
);
823 * \brief Context initialisation (key schedule) for AES CTR encryption
824 * and decryption (`aes_ct` implementation).
826 * \param ctx context to initialise.
827 * \param key secret key.
828 * \param len secret key length (in bytes).
830 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys
*ctx
,
831 const void *key
, size_t len
);
834 * \brief CBC encryption with AES (`aes_ct` implementation).
836 * \param ctx context (already initialised).
837 * \param iv IV (updated).
838 * \param data data to encrypt (updated).
839 * \param len data length (in bytes, MUST be multiple of 16).
841 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys
*ctx
, void *iv
,
842 void *data
, size_t len
);
845 * \brief CBC decryption with AES (`aes_ct` implementation).
847 * \param ctx context (already initialised).
848 * \param iv IV (updated).
849 * \param data data to decrypt (updated).
850 * \param len data length (in bytes, MUST be multiple of 16).
852 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys
*ctx
, void *iv
,
853 void *data
, size_t len
);
856 * \brief CTR encryption and decryption with AES (`aes_ct` implementation).
858 * \param ctx context (already initialised).
859 * \param iv IV (constant, 12 bytes).
860 * \param cc initial block counter value.
861 * \param data data to decrypt (updated).
862 * \param len data length (in bytes).
863 * \return new block counter value.
865 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys
*ctx
,
866 const void *iv
, uint32_t cc
, void *data
, size_t len
);
869 * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
870 * but uses 64-bit registers, making it about twice faster than 'aes_ct'
871 * on 64-bit platforms, while remaining constant-time and with a similar
872 * code size. (The doubling in performance is only for CBC decryption
873 * and CTR mode; CBC encryption is non-parallel and cannot benefit from
874 * the larger registers.)
877 /** \brief AES block size (16 bytes). */
878 #define br_aes_ct64_BLOCK_SIZE 16
881 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption).
883 * First field is a pointer to the vtable; it is set by the initialisation
884 * function. Other fields are not supposed to be accessed by user code.
887 /** \brief Pointer to vtable for this context. */
888 const br_block_cbcenc_class
*vtable
;
889 #ifndef BR_DOXYGEN_IGNORE
893 } br_aes_ct64_cbcenc_keys
;
896 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption).
898 * First field is a pointer to the vtable; it is set by the initialisation
899 * function. Other fields are not supposed to be accessed by user code.
902 /** \brief Pointer to vtable for this context. */
903 const br_block_cbcdec_class
*vtable
;
904 #ifndef BR_DOXYGEN_IGNORE
908 } br_aes_ct64_cbcdec_keys
;
911 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption
914 * First field is a pointer to the vtable; it is set by the initialisation
915 * function. Other fields are not supposed to be accessed by user code.
918 /** \brief Pointer to vtable for this context. */
919 const br_block_ctr_class
*vtable
;
920 #ifndef BR_DOXYGEN_IGNORE
924 } br_aes_ct64_ctr_keys
;
927 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation).
929 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable
;
932 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation).
934 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable
;
937 * \brief Class instance for AES CTR encryption and decryption
938 * (`aes_ct64` implementation).
940 extern const br_block_ctr_class br_aes_ct64_ctr_vtable
;
943 * \brief Context initialisation (key schedule) for AES CBC encryption
944 * (`aes_ct64` implementation).
946 * \param ctx context to initialise.
947 * \param key secret key.
948 * \param len secret key length (in bytes).
950 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys
*ctx
,
951 const void *key
, size_t len
);
954 * \brief Context initialisation (key schedule) for AES CBC decryption
955 * (`aes_ct64` implementation).
957 * \param ctx context to initialise.
958 * \param key secret key.
959 * \param len secret key length (in bytes).
961 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys
*ctx
,
962 const void *key
, size_t len
);
965 * \brief Context initialisation (key schedule) for AES CTR encryption
966 * and decryption (`aes_ct64` implementation).
968 * \param ctx context to initialise.
969 * \param key secret key.
970 * \param len secret key length (in bytes).
972 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys
*ctx
,
973 const void *key
, size_t len
);
976 * \brief CBC encryption with AES (`aes_ct64` implementation).
978 * \param ctx context (already initialised).
979 * \param iv IV (updated).
980 * \param data data to encrypt (updated).
981 * \param len data length (in bytes, MUST be multiple of 16).
983 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys
*ctx
, void *iv
,
984 void *data
, size_t len
);
987 * \brief CBC decryption with AES (`aes_ct64` implementation).
989 * \param ctx context (already initialised).
990 * \param iv IV (updated).
991 * \param data data to decrypt (updated).
992 * \param len data length (in bytes, MUST be multiple of 16).
994 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys
*ctx
, void *iv
,
995 void *data
, size_t len
);
998 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation).
1000 * \param ctx context (already initialised).
1001 * \param iv IV (constant, 12 bytes).
1002 * \param cc initial block counter value.
1003 * \param data data to decrypt (updated).
1004 * \param len data length (in bytes).
1005 * \return new block counter value.
1007 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys
*ctx
,
1008 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1011 * AES implementation using AES-NI opcodes (x86 platform).
1014 /** \brief AES block size (16 bytes). */
1015 #define br_aes_x86ni_BLOCK_SIZE 16
1018 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC encryption).
1020 * First field is a pointer to the vtable; it is set by the initialisation
1021 * function. Other fields are not supposed to be accessed by user code.
1024 /** \brief Pointer to vtable for this context. */
1025 const br_block_cbcenc_class
*vtable
;
1026 #ifndef BR_DOXYGEN_IGNORE
1028 unsigned char skni
[16 * 15];
1030 unsigned num_rounds
;
1032 } br_aes_x86ni_cbcenc_keys
;
1035 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC decryption).
1037 * First field is a pointer to the vtable; it is set by the initialisation
1038 * function. Other fields are not supposed to be accessed by user code.
1041 /** \brief Pointer to vtable for this context. */
1042 const br_block_cbcdec_class
*vtable
;
1043 #ifndef BR_DOXYGEN_IGNORE
1045 unsigned char skni
[16 * 15];
1047 unsigned num_rounds
;
1049 } br_aes_x86ni_cbcdec_keys
;
1052 * \brief Context for AES subkeys (`aes_x86ni` implementation, CTR encryption
1055 * First field is a pointer to the vtable; it is set by the initialisation
1056 * function. Other fields are not supposed to be accessed by user code.
1059 /** \brief Pointer to vtable for this context. */
1060 const br_block_ctr_class
*vtable
;
1061 #ifndef BR_DOXYGEN_IGNORE
1063 unsigned char skni
[16 * 15];
1065 unsigned num_rounds
;
1067 } br_aes_x86ni_ctr_keys
;
1070 * \brief Class instance for AES CBC encryption (`aes_x86ni` implementation).
1072 * Since this implementation might be omitted from the library, or the
1073 * AES opcode unavailable on the current CPU, a pointer to this class
1074 * instance should be obtained through `br_aes_x86ni_cbcenc_get_vtable()`.
1076 extern const br_block_cbcenc_class br_aes_x86ni_cbcenc_vtable
;
1079 * \brief Class instance for AES CBC decryption (`aes_x86ni` implementation).
1081 * Since this implementation might be omitted from the library, or the
1082 * AES opcode unavailable on the current CPU, a pointer to this class
1083 * instance should be obtained through `br_aes_x86ni_cbcdec_get_vtable()`.
1085 extern const br_block_cbcdec_class br_aes_x86ni_cbcdec_vtable
;
1088 * \brief Class instance for AES CTR encryption and decryption
1089 * (`aes_x86ni` implementation).
1091 * Since this implementation might be omitted from the library, or the
1092 * AES opcode unavailable on the current CPU, a pointer to this class
1093 * instance should be obtained through `br_aes_x86ni_ctr_get_vtable()`.
1095 extern const br_block_ctr_class br_aes_x86ni_ctr_vtable
;
1098 * \brief Context initialisation (key schedule) for AES CBC encryption
1099 * (`aes_x86ni` implementation).
1101 * \param ctx context to initialise.
1102 * \param key secret key.
1103 * \param len secret key length (in bytes).
1105 void br_aes_x86ni_cbcenc_init(br_aes_x86ni_cbcenc_keys
*ctx
,
1106 const void *key
, size_t len
);
1109 * \brief Context initialisation (key schedule) for AES CBC decryption
1110 * (`aes_x86ni` implementation).
1112 * \param ctx context to initialise.
1113 * \param key secret key.
1114 * \param len secret key length (in bytes).
1116 void br_aes_x86ni_cbcdec_init(br_aes_x86ni_cbcdec_keys
*ctx
,
1117 const void *key
, size_t len
);
1120 * \brief Context initialisation (key schedule) for AES CTR encryption
1121 * and decryption (`aes_x86ni` implementation).
1123 * \param ctx context to initialise.
1124 * \param key secret key.
1125 * \param len secret key length (in bytes).
1127 void br_aes_x86ni_ctr_init(br_aes_x86ni_ctr_keys
*ctx
,
1128 const void *key
, size_t len
);
1131 * \brief CBC encryption with AES (`aes_x86ni` implementation).
1133 * \param ctx context (already initialised).
1134 * \param iv IV (updated).
1135 * \param data data to encrypt (updated).
1136 * \param len data length (in bytes, MUST be multiple of 16).
1138 void br_aes_x86ni_cbcenc_run(const br_aes_x86ni_cbcenc_keys
*ctx
, void *iv
,
1139 void *data
, size_t len
);
1142 * \brief CBC decryption with AES (`aes_x86ni` implementation).
1144 * \param ctx context (already initialised).
1145 * \param iv IV (updated).
1146 * \param data data to decrypt (updated).
1147 * \param len data length (in bytes, MUST be multiple of 16).
1149 void br_aes_x86ni_cbcdec_run(const br_aes_x86ni_cbcdec_keys
*ctx
, void *iv
,
1150 void *data
, size_t len
);
1153 * \brief CTR encryption and decryption with AES (`aes_x86ni` implementation).
1155 * \param ctx context (already initialised).
1156 * \param iv IV (constant, 12 bytes).
1157 * \param cc initial block counter value.
1158 * \param data data to decrypt (updated).
1159 * \param len data length (in bytes).
1160 * \return new block counter value.
1162 uint32_t br_aes_x86ni_ctr_run(const br_aes_x86ni_ctr_keys
*ctx
,
1163 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1166 * \brief Obtain the `aes_x86ni` AES-CBC (encryption) implementation, if
1169 * This function returns a pointer to `br_aes_x86ni_cbcenc_vtable`, if
1170 * that implementation was compiled in the library _and_ the x86 AES
1171 * opcodes are available on the currently running CPU. If either of
1172 * these conditions is not met, then this function returns `NULL`.
1174 * \return the `aes_x868ni` AES-CBC (encryption) implementation, or `NULL`.
1176 const br_block_cbcenc_class
*br_aes_x86ni_cbcenc_get_vtable(void);
1179 * \brief Obtain the `aes_x86ni` AES-CBC (decryption) implementation, if
1182 * This function returns a pointer to `br_aes_x86ni_cbcdec_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 (decryption) implementation, or `NULL`.
1189 const br_block_cbcdec_class
*br_aes_x86ni_cbcdec_get_vtable(void);
1192 * \brief Obtain the `aes_x86ni` AES-CTR implementation, if available.
1194 * This function returns a pointer to `br_aes_x86ni_ctr_vtable`, if
1195 * that implementation was compiled in the library _and_ the x86 AES
1196 * opcodes are available on the currently running CPU. If either of
1197 * these conditions is not met, then this function returns `NULL`.
1199 * \return the `aes_x868ni` AES-CTR implementation, or `NULL`.
1201 const br_block_ctr_class
*br_aes_x86ni_ctr_get_vtable(void);
1204 * AES implementation using POWER8 opcodes.
1207 /** \brief AES block size (16 bytes). */
1208 #define br_aes_pwr8_BLOCK_SIZE 16
1211 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC encryption).
1213 * First field is a pointer to the vtable; it is set by the initialisation
1214 * function. Other fields are not supposed to be accessed by user code.
1217 /** \brief Pointer to vtable for this context. */
1218 const br_block_cbcenc_class
*vtable
;
1219 #ifndef BR_DOXYGEN_IGNORE
1221 unsigned char skni
[16 * 15];
1223 unsigned num_rounds
;
1225 } br_aes_pwr8_cbcenc_keys
;
1228 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC decryption).
1230 * First field is a pointer to the vtable; it is set by the initialisation
1231 * function. Other fields are not supposed to be accessed by user code.
1234 /** \brief Pointer to vtable for this context. */
1235 const br_block_cbcdec_class
*vtable
;
1236 #ifndef BR_DOXYGEN_IGNORE
1238 unsigned char skni
[16 * 15];
1240 unsigned num_rounds
;
1242 } br_aes_pwr8_cbcdec_keys
;
1245 * \brief Context for AES subkeys (`aes_pwr8` implementation, CTR encryption
1248 * First field is a pointer to the vtable; it is set by the initialisation
1249 * function. Other fields are not supposed to be accessed by user code.
1252 /** \brief Pointer to vtable for this context. */
1253 const br_block_ctr_class
*vtable
;
1254 #ifndef BR_DOXYGEN_IGNORE
1256 unsigned char skni
[16 * 15];
1258 unsigned num_rounds
;
1260 } br_aes_pwr8_ctr_keys
;
1263 * \brief Class instance for AES CBC encryption (`aes_pwr8` implementation).
1265 * Since this implementation might be omitted from the library, or the
1266 * AES opcode unavailable on the current CPU, a pointer to this class
1267 * instance should be obtained through `br_aes_pwr8_cbcenc_get_vtable()`.
1269 extern const br_block_cbcenc_class br_aes_pwr8_cbcenc_vtable
;
1272 * \brief Class instance for AES CBC decryption (`aes_pwr8` implementation).
1274 * Since this implementation might be omitted from the library, or the
1275 * AES opcode unavailable on the current CPU, a pointer to this class
1276 * instance should be obtained through `br_aes_pwr8_cbcdec_get_vtable()`.
1278 extern const br_block_cbcdec_class br_aes_pwr8_cbcdec_vtable
;
1281 * \brief Class instance for AES CTR encryption and decryption
1282 * (`aes_pwr8` implementation).
1284 * Since this implementation might be omitted from the library, or the
1285 * AES opcode unavailable on the current CPU, a pointer to this class
1286 * instance should be obtained through `br_aes_pwr8_ctr_get_vtable()`.
1288 extern const br_block_ctr_class br_aes_pwr8_ctr_vtable
;
1291 * \brief Context initialisation (key schedule) for AES CBC encryption
1292 * (`aes_pwr8` implementation).
1294 * \param ctx context to initialise.
1295 * \param key secret key.
1296 * \param len secret key length (in bytes).
1298 void br_aes_pwr8_cbcenc_init(br_aes_pwr8_cbcenc_keys
*ctx
,
1299 const void *key
, size_t len
);
1302 * \brief Context initialisation (key schedule) for AES CBC decryption
1303 * (`aes_pwr8` implementation).
1305 * \param ctx context to initialise.
1306 * \param key secret key.
1307 * \param len secret key length (in bytes).
1309 void br_aes_pwr8_cbcdec_init(br_aes_pwr8_cbcdec_keys
*ctx
,
1310 const void *key
, size_t len
);
1313 * \brief Context initialisation (key schedule) for AES CTR encryption
1314 * and decryption (`aes_pwr8` implementation).
1316 * \param ctx context to initialise.
1317 * \param key secret key.
1318 * \param len secret key length (in bytes).
1320 void br_aes_pwr8_ctr_init(br_aes_pwr8_ctr_keys
*ctx
,
1321 const void *key
, size_t len
);
1324 * \brief CBC encryption with AES (`aes_pwr8` implementation).
1326 * \param ctx context (already initialised).
1327 * \param iv IV (updated).
1328 * \param data data to encrypt (updated).
1329 * \param len data length (in bytes, MUST be multiple of 16).
1331 void br_aes_pwr8_cbcenc_run(const br_aes_pwr8_cbcenc_keys
*ctx
, void *iv
,
1332 void *data
, size_t len
);
1335 * \brief CBC decryption with AES (`aes_pwr8` implementation).
1337 * \param ctx context (already initialised).
1338 * \param iv IV (updated).
1339 * \param data data to decrypt (updated).
1340 * \param len data length (in bytes, MUST be multiple of 16).
1342 void br_aes_pwr8_cbcdec_run(const br_aes_pwr8_cbcdec_keys
*ctx
, void *iv
,
1343 void *data
, size_t len
);
1346 * \brief CTR encryption and decryption with AES (`aes_pwr8` implementation).
1348 * \param ctx context (already initialised).
1349 * \param iv IV (constant, 12 bytes).
1350 * \param cc initial block counter value.
1351 * \param data data to decrypt (updated).
1352 * \param len data length (in bytes).
1353 * \return new block counter value.
1355 uint32_t br_aes_pwr8_ctr_run(const br_aes_pwr8_ctr_keys
*ctx
,
1356 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1359 * \brief Obtain the `aes_pwr8` AES-CBC (encryption) implementation, if
1362 * This function returns a pointer to `br_aes_pwr8_cbcenc_vtable`, if
1363 * that implementation was compiled in the library _and_ the POWER8
1364 * crypto opcodes are available on the currently running CPU. If either
1365 * of these conditions is not met, then this function returns `NULL`.
1367 * \return the `aes_pwr8` AES-CBC (encryption) implementation, or `NULL`.
1369 const br_block_cbcenc_class
*br_aes_pwr8_cbcenc_get_vtable(void);
1372 * \brief Obtain the `aes_pwr8` AES-CBC (decryption) implementation, if
1375 * This function returns a pointer to `br_aes_pwr8_cbcdec_vtable`, if
1376 * that implementation was compiled in the library _and_ the POWER8
1377 * crypto opcodes are available on the currently running CPU. If either
1378 * of these conditions is not met, then this function returns `NULL`.
1380 * \return the `aes_pwr8` AES-CBC (decryption) implementation, or `NULL`.
1382 const br_block_cbcdec_class
*br_aes_pwr8_cbcdec_get_vtable(void);
1385 * \brief Obtain the `aes_pwr8` AES-CTR implementation, if available.
1387 * This function returns a pointer to `br_aes_pwr8_ctr_vtable`, if that
1388 * implementation was compiled in the library _and_ the POWER8 crypto
1389 * opcodes are available on the currently running CPU. If either of
1390 * these conditions is not met, then this function returns `NULL`.
1392 * \return the `aes_pwr8` AES-CTR implementation, or `NULL`.
1394 const br_block_ctr_class
*br_aes_pwr8_ctr_get_vtable(void);
1397 * \brief Aggregate structure large enough to be used as context for
1398 * subkeys (CBC encryption) for all AES implementations.
1401 const br_block_cbcenc_class
*vtable
;
1402 br_aes_big_cbcenc_keys c_big
;
1403 br_aes_small_cbcenc_keys c_small
;
1404 br_aes_ct_cbcenc_keys c_ct
;
1405 br_aes_ct64_cbcenc_keys c_ct64
;
1406 br_aes_x86ni_cbcenc_keys c_x86ni
;
1407 br_aes_pwr8_cbcenc_keys c_pwr8
;
1408 } br_aes_gen_cbcenc_keys
;
1411 * \brief Aggregate structure large enough to be used as context for
1412 * subkeys (CBC decryption) for all AES implementations.
1415 const br_block_cbcdec_class
*vtable
;
1416 br_aes_big_cbcdec_keys c_big
;
1417 br_aes_small_cbcdec_keys c_small
;
1418 br_aes_ct_cbcdec_keys c_ct
;
1419 br_aes_ct64_cbcdec_keys c_ct64
;
1420 br_aes_x86ni_cbcdec_keys c_x86ni
;
1421 br_aes_pwr8_cbcdec_keys c_pwr8
;
1422 } br_aes_gen_cbcdec_keys
;
1425 * \brief Aggregate structure large enough to be used as context for
1426 * subkeys (CTR encryption and decryption) for all AES implementations.
1429 const br_block_ctr_class
*vtable
;
1430 br_aes_big_ctr_keys c_big
;
1431 br_aes_small_ctr_keys c_small
;
1432 br_aes_ct_ctr_keys c_ct
;
1433 br_aes_ct64_ctr_keys c_ct64
;
1434 br_aes_x86ni_ctr_keys c_x86ni
;
1435 br_aes_pwr8_ctr_keys c_pwr8
;
1436 } br_aes_gen_ctr_keys
;
1439 * Traditional, table-based implementation for DES/3DES. Since tables are
1440 * used, cache-timing attacks are conceptually possible.
1443 /** \brief DES/3DES block size (8 bytes). */
1444 #define br_des_tab_BLOCK_SIZE 8
1447 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption).
1449 * First field is a pointer to the vtable; it is set by the initialisation
1450 * function. Other fields are not supposed to be accessed by user code.
1453 /** \brief Pointer to vtable for this context. */
1454 const br_block_cbcenc_class
*vtable
;
1455 #ifndef BR_DOXYGEN_IGNORE
1457 unsigned num_rounds
;
1459 } br_des_tab_cbcenc_keys
;
1462 * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption).
1464 * First field is a pointer to the vtable; it is set by the initialisation
1465 * function. Other fields are not supposed to be accessed by user code.
1468 /** \brief Pointer to vtable for this context. */
1469 const br_block_cbcdec_class
*vtable
;
1470 #ifndef BR_DOXYGEN_IGNORE
1472 unsigned num_rounds
;
1474 } br_des_tab_cbcdec_keys
;
1477 * \brief Class instance for DES CBC encryption (`des_tab` implementation).
1479 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable
;
1482 * \brief Class instance for DES CBC decryption (`des_tab` implementation).
1484 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable
;
1487 * \brief Context initialisation (key schedule) for DES CBC encryption
1488 * (`des_tab` implementation).
1490 * \param ctx context to initialise.
1491 * \param key secret key.
1492 * \param len secret key length (in bytes).
1494 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys
*ctx
,
1495 const void *key
, size_t len
);
1498 * \brief Context initialisation (key schedule) for DES CBC decryption
1499 * (`des_tab` implementation).
1501 * \param ctx context to initialise.
1502 * \param key secret key.
1503 * \param len secret key length (in bytes).
1505 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys
*ctx
,
1506 const void *key
, size_t len
);
1509 * \brief CBC encryption with DES (`des_tab` implementation).
1511 * \param ctx context (already initialised).
1512 * \param iv IV (updated).
1513 * \param data data to encrypt (updated).
1514 * \param len data length (in bytes, MUST be multiple of 8).
1516 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys
*ctx
, void *iv
,
1517 void *data
, size_t len
);
1520 * \brief CBC decryption with DES (`des_tab` implementation).
1522 * \param ctx context (already initialised).
1523 * \param iv IV (updated).
1524 * \param data data to decrypt (updated).
1525 * \param len data length (in bytes, MUST be multiple of 8).
1527 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys
*ctx
, void *iv
,
1528 void *data
, size_t len
);
1531 * Constant-time implementation for DES/3DES. It is substantially slower
1532 * (by a factor of about 4x), but also immune to cache-timing attacks.
1535 /** \brief DES/3DES block size (8 bytes). */
1536 #define br_des_ct_BLOCK_SIZE 8
1539 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption).
1541 * First field is a pointer to the vtable; it is set by the initialisation
1542 * function. Other fields are not supposed to be accessed by user code.
1545 /** \brief Pointer to vtable for this context. */
1546 const br_block_cbcenc_class
*vtable
;
1547 #ifndef BR_DOXYGEN_IGNORE
1549 unsigned num_rounds
;
1551 } br_des_ct_cbcenc_keys
;
1554 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption).
1556 * First field is a pointer to the vtable; it is set by the initialisation
1557 * function. Other fields are not supposed to be accessed by user code.
1560 /** \brief Pointer to vtable for this context. */
1561 const br_block_cbcdec_class
*vtable
;
1562 #ifndef BR_DOXYGEN_IGNORE
1564 unsigned num_rounds
;
1566 } br_des_ct_cbcdec_keys
;
1569 * \brief Class instance for DES CBC encryption (`des_ct` implementation).
1571 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable
;
1574 * \brief Class instance for DES CBC decryption (`des_ct` implementation).
1576 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable
;
1579 * \brief Context initialisation (key schedule) for DES CBC encryption
1580 * (`des_ct` implementation).
1582 * \param ctx context to initialise.
1583 * \param key secret key.
1584 * \param len secret key length (in bytes).
1586 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys
*ctx
,
1587 const void *key
, size_t len
);
1590 * \brief Context initialisation (key schedule) for DES CBC decryption
1591 * (`des_ct` implementation).
1593 * \param ctx context to initialise.
1594 * \param key secret key.
1595 * \param len secret key length (in bytes).
1597 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys
*ctx
,
1598 const void *key
, size_t len
);
1601 * \brief CBC encryption with DES (`des_ct` implementation).
1603 * \param ctx context (already initialised).
1604 * \param iv IV (updated).
1605 * \param data data to encrypt (updated).
1606 * \param len data length (in bytes, MUST be multiple of 8).
1608 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys
*ctx
, void *iv
,
1609 void *data
, size_t len
);
1612 * \brief CBC decryption with DES (`des_ct` implementation).
1614 * \param ctx context (already initialised).
1615 * \param iv IV (updated).
1616 * \param data data to decrypt (updated).
1617 * \param len data length (in bytes, MUST be multiple of 8).
1619 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys
*ctx
, void *iv
,
1620 void *data
, size_t len
);
1623 * These structures are large enough to accommodate subkeys for all
1624 * DES/3DES implementations.
1628 * \brief Aggregate structure large enough to be used as context for
1629 * subkeys (CBC encryption) for all DES implementations.
1632 const br_block_cbcenc_class
*vtable
;
1633 br_des_tab_cbcenc_keys tab
;
1634 br_des_ct_cbcenc_keys ct
;
1635 } br_des_gen_cbcenc_keys
;
1638 * \brief Aggregate structure large enough to be used as context for
1639 * subkeys (CBC decryption) for all DES implementations.
1642 const br_block_cbcdec_class
*vtable
;
1643 br_des_tab_cbcdec_keys c_tab
;
1644 br_des_ct_cbcdec_keys c_ct
;
1645 } br_des_gen_cbcdec_keys
;
1648 * \brief Type for a ChaCha20 implementation.
1650 * An implementation follows the description in RFC 7539:
1652 * - Key is 256 bits (`key` points to exactly 32 bytes).
1654 * - IV is 96 bits (`iv` points to exactly 12 bytes).
1656 * - Block counter is over 32 bits and starts at value `cc`; the
1657 * resulting value is returned.
1659 * Data (pointed to by `data`, of length `len`) is encrypted/decrypted
1660 * in place. If `len` is not a multiple of 64, then the excess bytes from
1661 * the last block processing are dropped (therefore, "chunked" processing
1662 * works only as long as each non-final chunk has a length multiple of 64).
1664 * \param key secret key (32 bytes).
1665 * \param iv IV (12 bytes).
1666 * \param cc initial counter value.
1667 * \param data data to encrypt or decrypt.
1668 * \param len data length (in bytes).
1670 typedef uint32_t (*br_chacha20_run
)(const void *key
,
1671 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1674 * \brief ChaCha20 implementation (straightforward C code, constant-time).
1676 * \see br_chacha20_run
1678 * \param key secret key (32 bytes).
1679 * \param iv IV (12 bytes).
1680 * \param cc initial counter value.
1681 * \param data data to encrypt or decrypt.
1682 * \param len data length (in bytes).
1684 uint32_t br_chacha20_ct_run(const void *key
,
1685 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1688 * \brief Type for a ChaCha20+Poly1305 AEAD implementation.
1690 * The provided data is encrypted or decrypted with ChaCha20. The
1691 * authentication tag is computed on the concatenation of the
1692 * additional data and the ciphertext, with the padding and lengths
1693 * as described in RFC 7539 (section 2.8).
1695 * After decryption, the caller is responsible for checking that the
1696 * computed tag matches the expected value.
1698 * \param key secret key (32 bytes).
1699 * \param iv nonce (12 bytes).
1700 * \param data data to encrypt or decrypt.
1701 * \param len data length (in bytes).
1702 * \param aad additional authenticated data.
1703 * \param aad_len length of additional authenticated data (in bytes).
1704 * \param tag output buffer for the authentication tag.
1705 * \param ichacha implementation of ChaCha20.
1706 * \param encrypt non-zero for encryption, zero for decryption.
1708 typedef void (*br_poly1305_run
)(const void *key
, const void *iv
,
1709 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1710 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1713 * \brief ChaCha20+Poly1305 AEAD implementation (mixed 32-bit multiplications).
1715 * \see br_poly1305_run
1717 * \param key secret key (32 bytes).
1718 * \param iv nonce (12 bytes).
1719 * \param data data to encrypt or decrypt.
1720 * \param len data length (in bytes).
1721 * \param aad additional authenticated data.
1722 * \param aad_len length of additional authenticated data (in bytes).
1723 * \param tag output buffer for the authentication tag.
1724 * \param ichacha implementation of ChaCha20.
1725 * \param encrypt non-zero for encryption, zero for decryption.
1727 void br_poly1305_ctmul_run(const void *key
, const void *iv
,
1728 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1729 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1732 * \brief ChaCha20+Poly1305 AEAD implementation (pure 32-bit multiplications).
1734 * \see br_poly1305_run
1736 * \param key secret key (32 bytes).
1737 * \param iv nonce (12 bytes).
1738 * \param data data to encrypt or decrypt.
1739 * \param len data length (in bytes).
1740 * \param aad additional authenticated data.
1741 * \param aad_len length of additional authenticated data (in bytes).
1742 * \param tag output buffer for the authentication tag.
1743 * \param ichacha implementation of ChaCha20.
1744 * \param encrypt non-zero for encryption, zero for decryption.
1746 void br_poly1305_ctmul32_run(const void *key
, const void *iv
,
1747 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1748 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1751 * \brief ChaCha20+Poly1305 AEAD implementation (i15).
1753 * This implementation relies on the generic big integer code "i15"
1754 * (which uses pure 32-bit multiplications). As such, it may save a
1755 * little code footprint in a context where "i15" is already included
1756 * (e.g. for elliptic curves or for RSA); however, it is also
1757 * substantially slower than the ctmul and ctmul32 implementations.
1759 * \see br_poly1305_run
1761 * \param key secret key (32 bytes).
1762 * \param iv nonce (12 bytes).
1763 * \param data data to encrypt or decrypt.
1764 * \param len data length (in bytes).
1765 * \param aad additional authenticated data.
1766 * \param aad_len length of additional authenticated data (in bytes).
1767 * \param tag output buffer for the authentication tag.
1768 * \param ichacha implementation of ChaCha20.
1769 * \param encrypt non-zero for encryption, zero for decryption.
1771 void br_poly1305_i15_run(const void *key
, const void *iv
,
1772 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1773 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1776 * \brief ChaCha20+Poly1305 AEAD implementation (ctmulq).
1778 * This implementation uses 64-bit multiplications (result over 128 bits).
1779 * It is available only on platforms that offer such a primitive (in
1780 * practice, 64-bit architectures). Use `br_poly1305_ctmulq_get()` to
1781 * dynamically obtain a pointer to that function, or 0 if not supported.
1783 * \see br_poly1305_run
1785 * \param key secret key (32 bytes).
1786 * \param iv nonce (12 bytes).
1787 * \param data data to encrypt or decrypt.
1788 * \param len data length (in bytes).
1789 * \param aad additional authenticated data.
1790 * \param aad_len length of additional authenticated data (in bytes).
1791 * \param tag output buffer for the authentication tag.
1792 * \param ichacha implementation of ChaCha20.
1793 * \param encrypt non-zero for encryption, zero for decryption.
1795 void br_poly1305_ctmulq_run(const void *key
, const void *iv
,
1796 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1797 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1800 * \brief Get the ChaCha20+Poly1305 "ctmulq" implementation, if available.
1802 * This function returns a pointer to the `br_poly1305_ctmulq_run()`
1803 * function if supported on the current platform; otherwise, it returns 0.
1805 * \return the ctmulq ChaCha20+Poly1305 implementation, or 0.
1807 br_poly1305_run
br_poly1305_ctmulq_get(void);