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
35 * This file documents the API for block ciphers.
40 * For a block cipher implementation, up to three separate sets of
41 * functions are provided, for CBC encryption, CBC decryption, and CTR
42 * encryption/decryption. Each set has its own context structure,
43 * initialised with the encryption key.
45 * For CBC encryption and decryption, the data to encrypt or decrypt is
46 * referenced as a sequence of blocks. The implementations assume that
47 * there is no partial block; no padding is applied or removed. The
48 * caller is responsible for handling any kind of padding.
50 * Function for CTR encryption are defined only for block ciphers with
51 * blocks of 16 bytes or more (i.e. AES, but not DES/3DES).
53 * Each implemented block cipher is identified by an "internal name"
54 * from which are derived the names of structures and functions that
55 * implement the cipher. For the block cipher of internal name "`xxx`",
56 * the following are defined:
58 * - `br_xxx_BLOCK_SIZE`
60 * A macro that evaluates to the block size (in bytes) of the
61 * cipher. For all implemented block ciphers, this value is a
64 * - `br_xxx_cbcenc_keys`
66 * Context structure that contains the subkeys resulting from the key
67 * expansion. These subkeys are appropriate for CBC encryption. The
68 * structure first field is called `vtable` and points to the
69 * appropriate OOP structure.
71 * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
73 * Perform key expansion: subkeys for CBC encryption are computed and
74 * written in the provided context structure. The key length MUST be
75 * adequate for the implemented block cipher. This function also sets
78 * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)`
80 * Perform CBC encryption of `len` bytes, in place. The encrypted data
81 * replaces the cleartext. `len` MUST be a multiple of the block length
82 * (if it is not, the function may loop forever or overflow a buffer).
83 * The IV is provided with the `iv` pointer; it is also updated with
84 * a copy of the last encrypted block.
86 * - `br_xxx_cbcdec_keys`
88 * Context structure that contains the subkeys resulting from the key
89 * expansion. These subkeys are appropriate for CBC decryption. The
90 * structure first field is called `vtable` and points to the
91 * appropriate OOP structure.
93 * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
95 * Perform key expansion: subkeys for CBC decryption are computed and
96 * written in the provided context structure. The key length MUST be
97 * adequate for the implemented block cipher. This function also sets
100 * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)`
102 * Perform CBC decryption of `len` bytes, in place. The decrypted data
103 * replaces the ciphertext. `len` MUST be a multiple of the block length
104 * (if it is not, the function may loop forever or overflow a buffer).
105 * The IV is provided with the `iv` pointer; it is also updated with
106 * a copy of the last _encrypted_ block.
108 * - `br_xxx_ctr_keys`
110 * Context structure that contains the subkeys resulting from the key
111 * expansion. These subkeys are appropriate for CTR encryption and
112 * decryption. The structure first field is called `vtable` and
113 * points to the appropriate OOP structure.
115 * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)`
117 * Perform key expansion: subkeys for CTR encryption and decryption
118 * are computed and written in the provided context structure. The
119 * key length MUST be adequate for the implemented block cipher. This
120 * function also sets the `vtable` field.
122 * - `br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len)` (returns `uint32_t`)
124 * Perform CTR encryption/decryption of some data. Processing is done
125 * "in place" (the output data replaces the input data). This function
126 * implements the "standard incrementing function" from NIST SP800-38A,
127 * annex B: the IV length shall be 4 bytes less than the block size
128 * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting
129 * with `cc`. The data length (`len`) is not necessarily a multiple of
130 * the block size. The new counter value is returned, which supports
131 * chunked processing, provided that each chunk length (except possibly
132 * the last one) is a multiple of the block size.
135 * It shall be noted that the key expansion functions return `void`. If
136 * the provided key length is not allowed, then there will be no error
137 * reporting; implementations need not validate the key length, thus an
138 * invalid key length may result in undefined behaviour (e.g. buffer
141 * Subkey structures contain no interior pointer, and no external
142 * resources are allocated upon key expansion. They can thus be
143 * discarded without any explicit deallocation.
146 * ## Object-Oriented API
148 * Each context structure begins with a field (called `vtable`) that
149 * points to an instance of a structure that references the relevant
150 * functions through pointers. Each such structure contains the
155 * The size (in bytes) of the context structure for subkeys.
159 * The cipher block size (in bytes).
163 * The base-2 logarithm of cipher block size (e.g. 4 for blocks
168 * Pointer to the key expansion function.
172 * Pointer to the encryption/decryption function.
175 * For block cipher "`xxx`", static, constant instances of these
176 * structures are defined, under the names:
178 * - `br_xxx_cbcenc_vtable`
179 * - `br_xxx_cbcdec_vtable`
180 * - `br_xxx_ctr_vtable`
183 * ## Implemented Block Ciphers
185 * Provided implementations are:
187 * | Name | Function | Block Size (bytes) | Key lengths (bytes) |
188 * | :-------- | :------- | :----------------: | :-----------------: |
189 * | aes_big | AES | 16 | 16, 24 and 32 |
190 * | aes_small | AES | 16 | 16, 24 and 32 |
191 * | aes_ct | AES | 16 | 16, 24 and 32 |
192 * | aes_ct64 | AES | 16 | 16, 24 and 32 |
193 * | des_ct | DES/3DES | 8 | 8, 16 and 24 |
194 * | des_tab | DES/3DES | 8 | 8, 16 and 24 |
196 * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8,
197 * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so
198 * the _effective_ key lengths, from a security point of view, are 56,
199 * 112 and 168 bits, respectively.
201 * `aes_big` is a "classical" AES implementation, using tables. It
202 * is fast but not constant-time, since it makes data-dependent array
205 * `aes_small` is an AES implementation optimized for code size. It
206 * is substantially slower than `aes_big`; it is not constant-time
209 * `aes_ct` is a constant-time implementation of AES; its code is about
210 * as big as that of `aes_big`, while its performance is comparable to
211 * that of `aes_small`. However, it is constant-time. This
212 * implementation should thus be considered to be the "default" AES in
213 * BearSSL, to be used unless the operational context guarantees that a
214 * non-constant-time implementation is safe, or an architecture-specific
215 * constant-time implementation can be used (e.g. using dedicated
218 * `aes_ct64` is another constant-time implementation of AES. It is
219 * similar to `aes_ct` but uses 64-bit values. On 32-bit machines,
220 * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has
221 * a larger footprint; however, on 64-bit architectures, `aes_ct64`
222 * is typically twice faster than `aes_ct` for modes that allow parallel
223 * operations (i.e. CTR, and CBC decryption, but not CBC encryption).
225 * `des_tab` is a classic, table-based implementation of DES/3DES. It
226 * is not constant-time.
228 * `des_ct` is an constant-time implementation of DES/3DES. It is
229 * substantially slower than `des_tab`.
233 * \brief Class type for CBC encryption implementations.
235 * A `br_block_cbcenc_class` instance points to the functions implementing
236 * a specific block cipher, when used in CBC mode for encrypting data.
238 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class
;
239 struct br_block_cbcenc_class_
{
241 * \brief Size (in bytes) of the context structure appropriate
242 * for containing subkeys.
247 * \brief Size of individual blocks (in bytes).
252 * \brief Base-2 logarithm of the size of individual blocks,
253 * expressed in bytes.
255 unsigned log_block_size
;
258 * \brief Initialisation function.
260 * This function sets the `vtable` field in the context structure.
261 * The key length MUST be one of the key lengths supported by
262 * the implementation.
264 * \param ctx context structure to initialise.
265 * \param key secret key.
266 * \param key_len key length (in bytes).
268 void (*init
)(const br_block_cbcenc_class
**ctx
,
269 const void *key
, size_t key_len
);
272 * \brief Run the CBC encryption.
274 * The `iv` parameter points to the IV for this run; it is
275 * updated with a copy of the last encrypted block. The data
276 * is encrypted "in place"; its length (`len`) MUST be a
277 * multiple of the block size.
279 * \param ctx context structure (already initialised).
280 * \param iv IV for CBC encryption (updated).
281 * \param data data to encrypt.
282 * \param len data length (in bytes, multiple of block size).
284 void (*run
)(const br_block_cbcenc_class
*const *ctx
,
285 void *iv
, void *data
, size_t len
);
289 * \brief Class type for CBC decryption implementations.
291 * A `br_block_cbcdec_class` instance points to the functions implementing
292 * a specific block cipher, when used in CBC mode for decrypting data.
294 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class
;
295 struct br_block_cbcdec_class_
{
297 * \brief Size (in bytes) of the context structure appropriate
298 * for containing subkeys.
303 * \brief Size of individual blocks (in bytes).
308 * \brief Base-2 logarithm of the size of individual blocks,
309 * expressed in bytes.
311 unsigned log_block_size
;
314 * \brief Initialisation function.
316 * This function sets the `vtable` field in the context structure.
317 * The key length MUST be one of the key lengths supported by
318 * the implementation.
320 * \param ctx context structure to initialise.
321 * \param key secret key.
322 * \param key_len key length (in bytes).
324 void (*init
)(const br_block_cbcdec_class
**ctx
,
325 const void *key
, size_t key_len
);
328 * \brief Run the CBC decryption.
330 * The `iv` parameter points to the IV for this run; it is
331 * updated with a copy of the last encrypted block. The data
332 * is decrypted "in place"; its length (`len`) MUST be a
333 * multiple of the block size.
335 * \param ctx context structure (already initialised).
336 * \param iv IV for CBC decryption (updated).
337 * \param data data to decrypt.
338 * \param len data length (in bytes, multiple of block size).
340 void (*run
)(const br_block_cbcdec_class
*const *ctx
,
341 void *iv
, void *data
, size_t len
);
345 * \brief Class type for CTR encryption/decryption implementations.
347 * A `br_block_ctr_class` instance points to the functions implementing
348 * a specific block cipher, when used in CTR mode for encrypting or
351 typedef struct br_block_ctr_class_ br_block_ctr_class
;
352 struct br_block_ctr_class_
{
354 * \brief Size (in bytes) of the context structure appropriate
355 * for containing subkeys.
360 * \brief Size of individual blocks (in bytes).
365 * \brief Base-2 logarithm of the size of individual blocks,
366 * expressed in bytes.
368 unsigned log_block_size
;
371 * \brief Initialisation function.
373 * This function sets the `vtable` field in the context structure.
374 * The key length MUST be one of the key lengths supported by
375 * the implementation.
377 * \param ctx context structure to initialise.
378 * \param key secret key.
379 * \param key_len key length (in bytes).
381 void (*init
)(const br_block_ctr_class
**ctx
,
382 const void *key
, size_t key_len
);
385 * \brief Run the CTR encryption or decryption.
387 * The `iv` parameter points to the IV for this run; its
388 * length is exactly 4 bytes less than the block size (e.g.
389 * 12 bytes for AES/CTR). The IV is combined with a 32-bit
390 * block counter to produce the block value which is processed
391 * with the block cipher.
393 * The data to encrypt or decrypt is updated "in place". Its
394 * length (`len` bytes) is not required to be a multiple of
395 * the block size; if the final block is partial, then the
396 * corresponding key stream bits are dropped.
398 * The resulting counter value is returned.
400 * \param ctx context structure (already initialised).
401 * \param iv IV for CTR encryption/decryption.
402 * \param cc initial value for the block counter.
403 * \param data data to encrypt or decrypt.
404 * \param len data length (in bytes).
405 * \return the new block counter value.
407 uint32_t (*run
)(const br_block_ctr_class
*const *ctx
,
408 const void *iv
, uint32_t cc
, void *data
, size_t len
);
412 * Traditional, table-based AES implementation. It is fast, but uses
413 * internal tables (in particular a 1 kB table for encryption, another
414 * 1 kB table for decryption, and a 256-byte table for key schedule),
415 * and it is not constant-time. In contexts where cache-timing attacks
416 * apply, this implementation may leak the secret key.
419 /** \brief AES block size (16 bytes). */
420 #define br_aes_big_BLOCK_SIZE 16
423 * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption).
425 * First field is a pointer to the vtable; it is set by the initialisation
426 * function. Other fields are not supposed to be accessed by user code.
429 /** \brief Pointer to vtable for this context. */
430 const br_block_cbcenc_class
*vtable
;
431 #ifndef BR_DOXYGEN_IGNORE
435 } br_aes_big_cbcenc_keys
;
438 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption).
440 * First field is a pointer to the vtable; it is set by the initialisation
441 * function. Other fields are not supposed to be accessed by user code.
444 /** \brief Pointer to vtable for this context. */
445 const br_block_cbcdec_class
*vtable
;
446 #ifndef BR_DOXYGEN_IGNORE
450 } br_aes_big_cbcdec_keys
;
453 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption
456 * First field is a pointer to the vtable; it is set by the initialisation
457 * function. Other fields are not supposed to be accessed by user code.
460 /** \brief Pointer to vtable for this context. */
461 const br_block_ctr_class
*vtable
;
462 #ifndef BR_DOXYGEN_IGNORE
466 } br_aes_big_ctr_keys
;
469 * \brief Class instance for AES CBC encryption (`aes_big` implementation).
471 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable
;
474 * \brief Class instance for AES CBC decryption (`aes_big` implementation).
476 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable
;
479 * \brief Class instance for AES CTR encryption and decryption
480 * (`aes_big` implementation).
482 extern const br_block_ctr_class br_aes_big_ctr_vtable
;
485 * \brief Context initialisation (key schedule) for AES CBC encryption
486 * (`aes_big` implementation).
488 * \param ctx context to initialise.
489 * \param key secret key.
490 * \param len secret key length (in bytes).
492 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys
*ctx
,
493 const void *key
, size_t len
);
496 * \brief Context initialisation (key schedule) for AES CBC decryption
497 * (`aes_big` implementation).
499 * \param ctx context to initialise.
500 * \param key secret key.
501 * \param len secret key length (in bytes).
503 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys
*ctx
,
504 const void *key
, size_t len
);
507 * \brief Context initialisation (key schedule) for AES CTR encryption
508 * and decryption (`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_ctr_init(br_aes_big_ctr_keys
*ctx
,
515 const void *key
, size_t len
);
518 * \brief CBC encryption with AES (`aes_big` implementation).
520 * \param ctx context (already initialised).
521 * \param iv IV (updated).
522 * \param data data to encrypt (updated).
523 * \param len data length (in bytes, MUST be multiple of 16).
525 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys
*ctx
, void *iv
,
526 void *data
, size_t len
);
529 * \brief CBC decryption with AES (`aes_big` implementation).
531 * \param ctx context (already initialised).
532 * \param iv IV (updated).
533 * \param data data to decrypt (updated).
534 * \param len data length (in bytes, MUST be multiple of 16).
536 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys
*ctx
, void *iv
,
537 void *data
, size_t len
);
540 * \brief CTR encryption and decryption with AES (`aes_big` implementation).
542 * \param ctx context (already initialised).
543 * \param iv IV (constant, 12 bytes).
544 * \param cc initial block counter value.
545 * \param data data to decrypt (updated).
546 * \param len data length (in bytes).
547 * \return new block counter value.
549 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys
*ctx
,
550 const void *iv
, uint32_t cc
, void *data
, size_t len
);
553 * AES implementation optimized for size. It is slower than the
554 * traditional table-based AES implementation, but requires much less
555 * code. It still uses data-dependent table accesses (albeit within a
556 * much smaller 256-byte table), which makes it conceptually vulnerable
557 * to cache-timing attacks.
560 /** \brief AES block size (16 bytes). */
561 #define br_aes_small_BLOCK_SIZE 16
564 * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption).
566 * First field is a pointer to the vtable; it is set by the initialisation
567 * function. Other fields are not supposed to be accessed by user code.
570 /** \brief Pointer to vtable for this context. */
571 const br_block_cbcenc_class
*vtable
;
572 #ifndef BR_DOXYGEN_IGNORE
576 } br_aes_small_cbcenc_keys
;
579 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption).
581 * First field is a pointer to the vtable; it is set by the initialisation
582 * function. Other fields are not supposed to be accessed by user code.
585 /** \brief Pointer to vtable for this context. */
586 const br_block_cbcdec_class
*vtable
;
587 #ifndef BR_DOXYGEN_IGNORE
591 } br_aes_small_cbcdec_keys
;
594 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption
597 * First field is a pointer to the vtable; it is set by the initialisation
598 * function. Other fields are not supposed to be accessed by user code.
601 /** \brief Pointer to vtable for this context. */
602 const br_block_ctr_class
*vtable
;
603 #ifndef BR_DOXYGEN_IGNORE
607 } br_aes_small_ctr_keys
;
610 * \brief Class instance for AES CBC encryption (`aes_small` implementation).
612 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable
;
615 * \brief Class instance for AES CBC decryption (`aes_small` implementation).
617 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable
;
620 * \brief Class instance for AES CTR encryption and decryption
621 * (`aes_small` implementation).
623 extern const br_block_ctr_class br_aes_small_ctr_vtable
;
626 * \brief Context initialisation (key schedule) for AES CBC encryption
627 * (`aes_small` implementation).
629 * \param ctx context to initialise.
630 * \param key secret key.
631 * \param len secret key length (in bytes).
633 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys
*ctx
,
634 const void *key
, size_t len
);
637 * \brief Context initialisation (key schedule) for AES CBC decryption
638 * (`aes_small` implementation).
640 * \param ctx context to initialise.
641 * \param key secret key.
642 * \param len secret key length (in bytes).
644 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys
*ctx
,
645 const void *key
, size_t len
);
648 * \brief Context initialisation (key schedule) for AES CTR encryption
649 * and decryption (`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_ctr_init(br_aes_small_ctr_keys
*ctx
,
656 const void *key
, size_t len
);
659 * \brief CBC encryption with AES (`aes_small` implementation).
661 * \param ctx context (already initialised).
662 * \param iv IV (updated).
663 * \param data data to encrypt (updated).
664 * \param len data length (in bytes, MUST be multiple of 16).
666 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys
*ctx
, void *iv
,
667 void *data
, size_t len
);
670 * \brief CBC decryption with AES (`aes_small` implementation).
672 * \param ctx context (already initialised).
673 * \param iv IV (updated).
674 * \param data data to decrypt (updated).
675 * \param len data length (in bytes, MUST be multiple of 16).
677 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys
*ctx
, void *iv
,
678 void *data
, size_t len
);
681 * \brief CTR encryption and decryption with AES (`aes_small` implementation).
683 * \param ctx context (already initialised).
684 * \param iv IV (constant, 12 bytes).
685 * \param cc initial block counter value.
686 * \param data data to decrypt (updated).
687 * \param len data length (in bytes).
688 * \return new block counter value.
690 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys
*ctx
,
691 const void *iv
, uint32_t cc
, void *data
, size_t len
);
694 * Constant-time AES implementation. Its size is similar to that of
695 * 'aes_big', and its performance is similar to that of 'aes_small' (faster
696 * decryption, slower encryption). However, it is constant-time, i.e.
697 * immune to cache-timing and similar attacks.
700 /** \brief AES block size (16 bytes). */
701 #define br_aes_ct_BLOCK_SIZE 16
704 * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption).
706 * First field is a pointer to the vtable; it is set by the initialisation
707 * function. Other fields are not supposed to be accessed by user code.
710 /** \brief Pointer to vtable for this context. */
711 const br_block_cbcenc_class
*vtable
;
712 #ifndef BR_DOXYGEN_IGNORE
716 } br_aes_ct_cbcenc_keys
;
719 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption).
721 * First field is a pointer to the vtable; it is set by the initialisation
722 * function. Other fields are not supposed to be accessed by user code.
725 /** \brief Pointer to vtable for this context. */
726 const br_block_cbcdec_class
*vtable
;
727 #ifndef BR_DOXYGEN_IGNORE
731 } br_aes_ct_cbcdec_keys
;
734 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption
737 * First field is a pointer to the vtable; it is set by the initialisation
738 * function. Other fields are not supposed to be accessed by user code.
741 /** \brief Pointer to vtable for this context. */
742 const br_block_ctr_class
*vtable
;
743 #ifndef BR_DOXYGEN_IGNORE
747 } br_aes_ct_ctr_keys
;
750 * \brief Class instance for AES CBC encryption (`aes_ct` implementation).
752 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable
;
755 * \brief Class instance for AES CBC decryption (`aes_ct` implementation).
757 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable
;
760 * \brief Class instance for AES CTR encryption and decryption
761 * (`aes_ct` implementation).
763 extern const br_block_ctr_class br_aes_ct_ctr_vtable
;
766 * \brief Context initialisation (key schedule) for AES CBC encryption
767 * (`aes_ct` implementation).
769 * \param ctx context to initialise.
770 * \param key secret key.
771 * \param len secret key length (in bytes).
773 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys
*ctx
,
774 const void *key
, size_t len
);
777 * \brief Context initialisation (key schedule) for AES CBC decryption
778 * (`aes_ct` implementation).
780 * \param ctx context to initialise.
781 * \param key secret key.
782 * \param len secret key length (in bytes).
784 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys
*ctx
,
785 const void *key
, size_t len
);
788 * \brief Context initialisation (key schedule) for AES CTR encryption
789 * and decryption (`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_ctr_init(br_aes_ct_ctr_keys
*ctx
,
796 const void *key
, size_t len
);
799 * \brief CBC encryption with AES (`aes_ct` implementation).
801 * \param ctx context (already initialised).
802 * \param iv IV (updated).
803 * \param data data to encrypt (updated).
804 * \param len data length (in bytes, MUST be multiple of 16).
806 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys
*ctx
, void *iv
,
807 void *data
, size_t len
);
810 * \brief CBC decryption with AES (`aes_ct` implementation).
812 * \param ctx context (already initialised).
813 * \param iv IV (updated).
814 * \param data data to decrypt (updated).
815 * \param len data length (in bytes, MUST be multiple of 16).
817 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys
*ctx
, void *iv
,
818 void *data
, size_t len
);
821 * \brief CTR encryption and decryption with AES (`aes_ct` implementation).
823 * \param ctx context (already initialised).
824 * \param iv IV (constant, 12 bytes).
825 * \param cc initial block counter value.
826 * \param data data to decrypt (updated).
827 * \param len data length (in bytes).
828 * \return new block counter value.
830 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys
*ctx
,
831 const void *iv
, uint32_t cc
, void *data
, size_t len
);
834 * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
835 * but uses 64-bit registers, making it about twice faster than 'aes_ct'
836 * on 64-bit platforms, while remaining constant-time and with a similar
837 * code size. (The doubling in performance is only for CBC decryption
838 * and CTR mode; CBC encryption is non-parallel and cannot benefit from
839 * the larger registers.)
842 /** \brief AES block size (16 bytes). */
843 #define br_aes_ct64_BLOCK_SIZE 16
846 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption).
848 * First field is a pointer to the vtable; it is set by the initialisation
849 * function. Other fields are not supposed to be accessed by user code.
852 /** \brief Pointer to vtable for this context. */
853 const br_block_cbcenc_class
*vtable
;
854 #ifndef BR_DOXYGEN_IGNORE
858 } br_aes_ct64_cbcenc_keys
;
861 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption).
863 * First field is a pointer to the vtable; it is set by the initialisation
864 * function. Other fields are not supposed to be accessed by user code.
867 /** \brief Pointer to vtable for this context. */
868 const br_block_cbcdec_class
*vtable
;
869 #ifndef BR_DOXYGEN_IGNORE
873 } br_aes_ct64_cbcdec_keys
;
876 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption
879 * First field is a pointer to the vtable; it is set by the initialisation
880 * function. Other fields are not supposed to be accessed by user code.
883 /** \brief Pointer to vtable for this context. */
884 const br_block_ctr_class
*vtable
;
885 #ifndef BR_DOXYGEN_IGNORE
889 } br_aes_ct64_ctr_keys
;
892 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation).
894 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable
;
897 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation).
899 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable
;
902 * \brief Class instance for AES CTR encryption and decryption
903 * (`aes_ct64` implementation).
905 extern const br_block_ctr_class br_aes_ct64_ctr_vtable
;
908 * \brief Context initialisation (key schedule) for AES CBC encryption
909 * (`aes_ct64` implementation).
911 * \param ctx context to initialise.
912 * \param key secret key.
913 * \param len secret key length (in bytes).
915 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys
*ctx
,
916 const void *key
, size_t len
);
919 * \brief Context initialisation (key schedule) for AES CBC decryption
920 * (`aes_ct64` implementation).
922 * \param ctx context to initialise.
923 * \param key secret key.
924 * \param len secret key length (in bytes).
926 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys
*ctx
,
927 const void *key
, size_t len
);
930 * \brief Context initialisation (key schedule) for AES CTR encryption
931 * and decryption (`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_ctr_init(br_aes_ct64_ctr_keys
*ctx
,
938 const void *key
, size_t len
);
941 * \brief CBC encryption with AES (`aes_ct64` implementation).
943 * \param ctx context (already initialised).
944 * \param iv IV (updated).
945 * \param data data to encrypt (updated).
946 * \param len data length (in bytes, MUST be multiple of 16).
948 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys
*ctx
, void *iv
,
949 void *data
, size_t len
);
952 * \brief CBC decryption with AES (`aes_ct64` implementation).
954 * \param ctx context (already initialised).
955 * \param iv IV (updated).
956 * \param data data to decrypt (updated).
957 * \param len data length (in bytes, MUST be multiple of 16).
959 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys
*ctx
, void *iv
,
960 void *data
, size_t len
);
963 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation).
965 * \param ctx context (already initialised).
966 * \param iv IV (constant, 12 bytes).
967 * \param cc initial block counter value.
968 * \param data data to decrypt (updated).
969 * \param len data length (in bytes).
970 * \return new block counter value.
972 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys
*ctx
,
973 const void *iv
, uint32_t cc
, void *data
, size_t len
);
976 * \brief Aggregate structure large enough to be used as context for
977 * subkeys (CBC encryption) for all AES implementations.
980 const br_block_cbcenc_class
*vtable
;
981 br_aes_big_cbcenc_keys big
;
982 br_aes_small_cbcenc_keys small
;
983 br_aes_ct_cbcenc_keys ct
;
984 br_aes_ct64_cbcenc_keys ct64
;
985 } br_aes_gen_cbcenc_keys
;
988 * \brief Aggregate structure large enough to be used as context for
989 * subkeys (CBC decryption) for all AES implementations.
992 const br_block_cbcdec_class
*vtable
;
993 br_aes_big_cbcdec_keys big
;
994 br_aes_small_cbcdec_keys small
;
995 br_aes_ct_cbcdec_keys ct
;
996 br_aes_ct64_cbcdec_keys ct64
;
997 } br_aes_gen_cbcdec_keys
;
1000 * \brief Aggregate structure large enough to be used as context for
1001 * subkeys (CTR encryption and decryption) for all AES implementations.
1004 const br_block_ctr_class
*vtable
;
1005 br_aes_big_ctr_keys big
;
1006 br_aes_small_ctr_keys small
;
1007 br_aes_ct_ctr_keys ct
;
1008 br_aes_ct64_ctr_keys ct64
;
1009 } br_aes_gen_ctr_keys
;
1012 * Traditional, table-based implementation for DES/3DES. Since tables are
1013 * used, cache-timing attacks are conceptually possible.
1016 /** \brief DES/3DES block size (8 bytes). */
1017 #define br_des_tab_BLOCK_SIZE 8
1020 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption).
1022 * First field is a pointer to the vtable; it is set by the initialisation
1023 * function. Other fields are not supposed to be accessed by user code.
1026 /** \brief Pointer to vtable for this context. */
1027 const br_block_cbcenc_class
*vtable
;
1028 #ifndef BR_DOXYGEN_IGNORE
1030 unsigned num_rounds
;
1032 } br_des_tab_cbcenc_keys
;
1035 * \brief Context for DES subkeys (`des_tab` 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 num_rounds
;
1047 } br_des_tab_cbcdec_keys
;
1050 * \brief Class instance for DES CBC encryption (`des_tab` implementation).
1052 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable
;
1055 * \brief Class instance for DES CBC decryption (`des_tab` implementation).
1057 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable
;
1060 * \brief Context initialisation (key schedule) for DES CBC encryption
1061 * (`des_tab` implementation).
1063 * \param ctx context to initialise.
1064 * \param key secret key.
1065 * \param len secret key length (in bytes).
1067 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys
*ctx
,
1068 const void *key
, size_t len
);
1071 * \brief Context initialisation (key schedule) for DES CBC decryption
1072 * (`des_tab` implementation).
1074 * \param ctx context to initialise.
1075 * \param key secret key.
1076 * \param len secret key length (in bytes).
1078 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys
*ctx
,
1079 const void *key
, size_t len
);
1082 * \brief CBC encryption with DES (`des_tab` implementation).
1084 * \param ctx context (already initialised).
1085 * \param iv IV (updated).
1086 * \param data data to encrypt (updated).
1087 * \param len data length (in bytes, MUST be multiple of 8).
1089 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys
*ctx
, void *iv
,
1090 void *data
, size_t len
);
1093 * \brief CBC decryption with DES (`des_tab` implementation).
1095 * \param ctx context (already initialised).
1096 * \param iv IV (updated).
1097 * \param data data to decrypt (updated).
1098 * \param len data length (in bytes, MUST be multiple of 8).
1100 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys
*ctx
, void *iv
,
1101 void *data
, size_t len
);
1104 * Constant-time implementation for DES/3DES. It is substantially slower
1105 * (by a factor of about 4x), but also immune to cache-timing attacks.
1108 /** \brief DES/3DES block size (8 bytes). */
1109 #define br_des_ct_BLOCK_SIZE 8
1112 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption).
1114 * First field is a pointer to the vtable; it is set by the initialisation
1115 * function. Other fields are not supposed to be accessed by user code.
1118 /** \brief Pointer to vtable for this context. */
1119 const br_block_cbcenc_class
*vtable
;
1120 #ifndef BR_DOXYGEN_IGNORE
1122 unsigned num_rounds
;
1124 } br_des_ct_cbcenc_keys
;
1127 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption).
1129 * First field is a pointer to the vtable; it is set by the initialisation
1130 * function. Other fields are not supposed to be accessed by user code.
1133 /** \brief Pointer to vtable for this context. */
1134 const br_block_cbcdec_class
*vtable
;
1135 #ifndef BR_DOXYGEN_IGNORE
1137 unsigned num_rounds
;
1139 } br_des_ct_cbcdec_keys
;
1142 * \brief Class instance for DES CBC encryption (`des_ct` implementation).
1144 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable
;
1147 * \brief Class instance for DES CBC decryption (`des_ct` implementation).
1149 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable
;
1152 * \brief Context initialisation (key schedule) for DES CBC encryption
1153 * (`des_ct` implementation).
1155 * \param ctx context to initialise.
1156 * \param key secret key.
1157 * \param len secret key length (in bytes).
1159 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys
*ctx
,
1160 const void *key
, size_t len
);
1163 * \brief Context initialisation (key schedule) for DES CBC decryption
1164 * (`des_ct` implementation).
1166 * \param ctx context to initialise.
1167 * \param key secret key.
1168 * \param len secret key length (in bytes).
1170 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys
*ctx
,
1171 const void *key
, size_t len
);
1174 * \brief CBC encryption with DES (`des_ct` implementation).
1176 * \param ctx context (already initialised).
1177 * \param iv IV (updated).
1178 * \param data data to encrypt (updated).
1179 * \param len data length (in bytes, MUST be multiple of 8).
1181 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys
*ctx
, void *iv
,
1182 void *data
, size_t len
);
1185 * \brief CBC decryption with DES (`des_ct` implementation).
1187 * \param ctx context (already initialised).
1188 * \param iv IV (updated).
1189 * \param data data to decrypt (updated).
1190 * \param len data length (in bytes, MUST be multiple of 8).
1192 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys
*ctx
, void *iv
,
1193 void *data
, size_t len
);
1196 * These structures are large enough to accommodate subkeys for all
1197 * DES/3DES implementations.
1201 * \brief Aggregate structure large enough to be used as context for
1202 * subkeys (CBC encryption) for all DES implementations.
1205 const br_block_cbcenc_class
*vtable
;
1206 br_des_tab_cbcenc_keys tab
;
1207 br_des_ct_cbcenc_keys ct
;
1208 } br_des_gen_cbcenc_keys
;
1211 * \brief Aggregate structure large enough to be used as context for
1212 * subkeys (CBC decryption) for all DES implementations.
1215 const br_block_cbcdec_class
*vtable
;
1216 br_des_tab_cbcdec_keys tab
;
1217 br_des_ct_cbcdec_keys ct
;
1218 } br_des_gen_cbcdec_keys
;