2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 #ifndef BR_BEARSSL_BLOCK_H__
26 #define BR_BEARSSL_BLOCK_H__
31 /** \file bearssl_block.h
33 * # Block Ciphers and Symmetric Ciphers
35 * This file documents the API for block ciphers and other symmetric
41 * For a block cipher implementation, up to three separate sets of
42 * functions are provided, for CBC encryption, CBC decryption, and CTR
43 * encryption/decryption. Each set has its own context structure,
44 * initialised with the encryption key.
46 * For CBC encryption and decryption, the data to encrypt or decrypt is
47 * referenced as a sequence of blocks. The implementations assume that
48 * there is no partial block; no padding is applied or removed. The
49 * caller is responsible for handling any kind of padding.
51 * Function for CTR encryption are defined only for block ciphers with
52 * blocks of 16 bytes or more (i.e. AES, but not DES/3DES).
54 * Each implemented block cipher is identified by an "internal name"
55 * from which are derived the names of structures and functions that
56 * implement the cipher. For the block cipher of internal name "`xxx`",
57 * the following are defined:
59 * - `br_xxx_BLOCK_SIZE`
61 * A macro that evaluates to the block size (in bytes) of the
62 * cipher. For all implemented block ciphers, this value is a
65 * - `br_xxx_cbcenc_keys`
67 * Context structure that contains the subkeys resulting from the key
68 * expansion. These subkeys are appropriate for CBC encryption. The
69 * structure first field is called `vtable` and points to the
70 * appropriate OOP structure.
72 * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
74 * Perform key expansion: subkeys for CBC encryption are computed and
75 * written in the provided context structure. The key length MUST be
76 * adequate for the implemented block cipher. This function also sets
79 * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)`
81 * Perform CBC encryption of `len` bytes, in place. The encrypted data
82 * replaces the cleartext. `len` MUST be a multiple of the block length
83 * (if it is not, the function may loop forever or overflow a buffer).
84 * The IV is provided with the `iv` pointer; it is also updated with
85 * a copy of the last encrypted block.
87 * - `br_xxx_cbcdec_keys`
89 * Context structure that contains the subkeys resulting from the key
90 * expansion. These subkeys are appropriate for CBC decryption. The
91 * structure first field is called `vtable` and points to the
92 * appropriate OOP structure.
94 * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
96 * Perform key expansion: subkeys for CBC decryption are computed and
97 * written in the provided context structure. The key length MUST be
98 * adequate for the implemented block cipher. This function also sets
101 * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)`
103 * Perform CBC decryption of `len` bytes, in place. The decrypted data
104 * replaces the ciphertext. `len` MUST be a multiple of the block length
105 * (if it is not, the function may loop forever or overflow a buffer).
106 * The IV is provided with the `iv` pointer; it is also updated with
107 * a copy of the last _encrypted_ block.
109 * - `br_xxx_ctr_keys`
111 * Context structure that contains the subkeys resulting from the key
112 * expansion. These subkeys are appropriate for CTR encryption and
113 * decryption. The structure first field is called `vtable` and
114 * points to the appropriate OOP structure.
116 * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)`
118 * Perform key expansion: subkeys for CTR encryption and decryption
119 * are computed and written in the provided context structure. The
120 * key length MUST be adequate for the implemented block cipher. This
121 * function also sets the `vtable` field.
123 * - `br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len)` (returns `uint32_t`)
125 * Perform CTR encryption/decryption of some data. Processing is done
126 * "in place" (the output data replaces the input data). This function
127 * implements the "standard incrementing function" from NIST SP800-38A,
128 * annex B: the IV length shall be 4 bytes less than the block size
129 * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting
130 * with `cc`. The data length (`len`) is not necessarily a multiple of
131 * the block size. The new counter value is returned, which supports
132 * chunked processing, provided that each chunk length (except possibly
133 * the last one) is a multiple of the block size.
136 * It shall be noted that the key expansion functions return `void`. If
137 * the provided key length is not allowed, then there will be no error
138 * reporting; implementations need not validate the key length, thus an
139 * invalid key length may result in undefined behaviour (e.g. buffer
142 * Subkey structures contain no interior pointer, and no external
143 * resources are allocated upon key expansion. They can thus be
144 * discarded without any explicit deallocation.
147 * ## Object-Oriented API
149 * Each context structure begins with a field (called `vtable`) that
150 * points to an instance of a structure that references the relevant
151 * functions through pointers. Each such structure contains the
156 * The size (in bytes) of the context structure for subkeys.
160 * The cipher block size (in bytes).
164 * The base-2 logarithm of cipher block size (e.g. 4 for blocks
169 * Pointer to the key expansion function.
173 * Pointer to the encryption/decryption function.
176 * For block cipher "`xxx`", static, constant instances of these
177 * structures are defined, under the names:
179 * - `br_xxx_cbcenc_vtable`
180 * - `br_xxx_cbcdec_vtable`
181 * - `br_xxx_ctr_vtable`
184 * ## Implemented Block Ciphers
186 * Provided implementations are:
188 * | Name | Function | Block Size (bytes) | Key lengths (bytes) |
189 * | :-------- | :------- | :----------------: | :-----------------: |
190 * | aes_big | AES | 16 | 16, 24 and 32 |
191 * | aes_small | AES | 16 | 16, 24 and 32 |
192 * | aes_ct | AES | 16 | 16, 24 and 32 |
193 * | aes_ct64 | AES | 16 | 16, 24 and 32 |
194 * | aes_x86ni | AES | 16 | 16, 24 and 32 |
195 * | aes_pwr8 | AES | 16 | 16, 24 and 32 |
196 * | des_ct | DES/3DES | 8 | 8, 16 and 24 |
197 * | des_tab | DES/3DES | 8 | 8, 16 and 24 |
199 * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8,
200 * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so
201 * the _effective_ key lengths, from a security point of view, are 56,
202 * 112 and 168 bits, respectively.
204 * `aes_big` is a "classical" AES implementation, using tables. It
205 * is fast but not constant-time, since it makes data-dependent array
208 * `aes_small` is an AES implementation optimized for code size. It
209 * is substantially slower than `aes_big`; it is not constant-time
212 * `aes_ct` is a constant-time implementation of AES; its code is about
213 * as big as that of `aes_big`, while its performance is comparable to
214 * that of `aes_small`. However, it is constant-time. This
215 * implementation should thus be considered to be the "default" AES in
216 * BearSSL, to be used unless the operational context guarantees that a
217 * non-constant-time implementation is safe, or an architecture-specific
218 * constant-time implementation can be used (e.g. using dedicated
221 * `aes_ct64` is another constant-time implementation of AES. It is
222 * similar to `aes_ct` but uses 64-bit values. On 32-bit machines,
223 * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has
224 * a larger footprint; however, on 64-bit architectures, `aes_ct64`
225 * is typically twice faster than `aes_ct` for modes that allow parallel
226 * operations (i.e. CTR, and CBC decryption, but not CBC encryption).
228 * `aes_x86ni` exists only on x86 architectures (32-bit and 64-bit). It
229 * uses the AES-NI opcodes when available.
231 * `aes_pwr8` exists only on PowerPC / POWER architectures (32-bit and
232 * 64-bit, both little-endian and big-endian). It uses the AES opcodes
233 * present in POWER8 and later.
235 * `des_tab` is a classic, table-based implementation of DES/3DES. It
236 * is not constant-time.
238 * `des_ct` is an constant-time implementation of DES/3DES. It is
239 * substantially slower than `des_tab`.
241 * ## ChaCha20 and Poly1305
243 * ChaCha20 is a stream cipher. Poly1305 is a MAC algorithm. They
244 * are described in [RFC 7539](https://tools.ietf.org/html/rfc7539).
246 * Two function pointer types are defined:
248 * - `br_chacha20_run` describes a function that implements ChaCha20
251 * - `br_poly1305_run` describes an implementation of Poly1305,
252 * in the AEAD combination with ChaCha20 specified in RFC 7539
253 * (the ChaCha20 implementation is provided as a function pointer).
255 * `chacha20_ct` is a straightforward implementation of ChaCha20 in
256 * plain C; it is constant-time, small, and reasonably fast.
258 * `poly1305_ctmul` is an implementation of the ChaCha20+Poly1305 AEAD
259 * construction, where the Poly1305 part is performed with mixed 32-bit
260 * multiplications (operands are 32-bit, result is 64-bit).
264 * \brief Class type for CBC encryption implementations.
266 * A `br_block_cbcenc_class` instance points to the functions implementing
267 * a specific block cipher, when used in CBC mode for encrypting data.
269 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class
;
270 struct br_block_cbcenc_class_
{
272 * \brief Size (in bytes) of the context structure appropriate
273 * for containing subkeys.
278 * \brief Size of individual blocks (in bytes).
283 * \brief Base-2 logarithm of the size of individual blocks,
284 * expressed in bytes.
286 unsigned log_block_size
;
289 * \brief Initialisation function.
291 * This function sets the `vtable` field in the context structure.
292 * The key length MUST be one of the key lengths supported by
293 * the implementation.
295 * \param ctx context structure to initialise.
296 * \param key secret key.
297 * \param key_len key length (in bytes).
299 void (*init
)(const br_block_cbcenc_class
**ctx
,
300 const void *key
, size_t key_len
);
303 * \brief Run the CBC encryption.
305 * The `iv` parameter points to the IV for this run; it is
306 * updated with a copy of the last encrypted block. The data
307 * is encrypted "in place"; its length (`len`) MUST be a
308 * multiple of the block size.
310 * \param ctx context structure (already initialised).
311 * \param iv IV for CBC encryption (updated).
312 * \param data data to encrypt.
313 * \param len data length (in bytes, multiple of block size).
315 void (*run
)(const br_block_cbcenc_class
*const *ctx
,
316 void *iv
, void *data
, size_t len
);
320 * \brief Class type for CBC decryption implementations.
322 * A `br_block_cbcdec_class` instance points to the functions implementing
323 * a specific block cipher, when used in CBC mode for decrypting data.
325 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class
;
326 struct br_block_cbcdec_class_
{
328 * \brief Size (in bytes) of the context structure appropriate
329 * for containing subkeys.
334 * \brief Size of individual blocks (in bytes).
339 * \brief Base-2 logarithm of the size of individual blocks,
340 * expressed in bytes.
342 unsigned log_block_size
;
345 * \brief Initialisation function.
347 * This function sets the `vtable` field in the context structure.
348 * The key length MUST be one of the key lengths supported by
349 * the implementation.
351 * \param ctx context structure to initialise.
352 * \param key secret key.
353 * \param key_len key length (in bytes).
355 void (*init
)(const br_block_cbcdec_class
**ctx
,
356 const void *key
, size_t key_len
);
359 * \brief Run the CBC decryption.
361 * The `iv` parameter points to the IV for this run; it is
362 * updated with a copy of the last encrypted block. The data
363 * is decrypted "in place"; its length (`len`) MUST be a
364 * multiple of the block size.
366 * \param ctx context structure (already initialised).
367 * \param iv IV for CBC decryption (updated).
368 * \param data data to decrypt.
369 * \param len data length (in bytes, multiple of block size).
371 void (*run
)(const br_block_cbcdec_class
*const *ctx
,
372 void *iv
, void *data
, size_t len
);
376 * \brief Class type for CTR encryption/decryption implementations.
378 * A `br_block_ctr_class` instance points to the functions implementing
379 * a specific block cipher, when used in CTR mode for encrypting or
382 typedef struct br_block_ctr_class_ br_block_ctr_class
;
383 struct br_block_ctr_class_
{
385 * \brief Size (in bytes) of the context structure appropriate
386 * for containing subkeys.
391 * \brief Size of individual blocks (in bytes).
396 * \brief Base-2 logarithm of the size of individual blocks,
397 * expressed in bytes.
399 unsigned log_block_size
;
402 * \brief Initialisation function.
404 * This function sets the `vtable` field in the context structure.
405 * The key length MUST be one of the key lengths supported by
406 * the implementation.
408 * \param ctx context structure to initialise.
409 * \param key secret key.
410 * \param key_len key length (in bytes).
412 void (*init
)(const br_block_ctr_class
**ctx
,
413 const void *key
, size_t key_len
);
416 * \brief Run the CTR encryption or decryption.
418 * The `iv` parameter points to the IV for this run; its
419 * length is exactly 4 bytes less than the block size (e.g.
420 * 12 bytes for AES/CTR). The IV is combined with a 32-bit
421 * block counter to produce the block value which is processed
422 * with the block cipher.
424 * The data to encrypt or decrypt is updated "in place". Its
425 * length (`len` bytes) is not required to be a multiple of
426 * the block size; if the final block is partial, then the
427 * corresponding key stream bits are dropped.
429 * The resulting counter value is returned.
431 * \param ctx context structure (already initialised).
432 * \param iv IV for CTR encryption/decryption.
433 * \param cc initial value for the block counter.
434 * \param data data to encrypt or decrypt.
435 * \param len data length (in bytes).
436 * \return the new block counter value.
438 uint32_t (*run
)(const br_block_ctr_class
*const *ctx
,
439 const void *iv
, uint32_t cc
, void *data
, size_t len
);
443 * Traditional, table-based AES implementation. It is fast, but uses
444 * internal tables (in particular a 1 kB table for encryption, another
445 * 1 kB table for decryption, and a 256-byte table for key schedule),
446 * and it is not constant-time. In contexts where cache-timing attacks
447 * apply, this implementation may leak the secret key.
450 /** \brief AES block size (16 bytes). */
451 #define br_aes_big_BLOCK_SIZE 16
454 * \brief Context for AES subkeys (`aes_big` implementation, CBC 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_cbcenc_class
*vtable
;
462 #ifndef BR_DOXYGEN_IGNORE
466 } br_aes_big_cbcenc_keys
;
469 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption).
471 * First field is a pointer to the vtable; it is set by the initialisation
472 * function. Other fields are not supposed to be accessed by user code.
475 /** \brief Pointer to vtable for this context. */
476 const br_block_cbcdec_class
*vtable
;
477 #ifndef BR_DOXYGEN_IGNORE
481 } br_aes_big_cbcdec_keys
;
484 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption
487 * First field is a pointer to the vtable; it is set by the initialisation
488 * function. Other fields are not supposed to be accessed by user code.
491 /** \brief Pointer to vtable for this context. */
492 const br_block_ctr_class
*vtable
;
493 #ifndef BR_DOXYGEN_IGNORE
497 } br_aes_big_ctr_keys
;
500 * \brief Class instance for AES CBC encryption (`aes_big` implementation).
502 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable
;
505 * \brief Class instance for AES CBC decryption (`aes_big` implementation).
507 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable
;
510 * \brief Class instance for AES CTR encryption and decryption
511 * (`aes_big` implementation).
513 extern const br_block_ctr_class br_aes_big_ctr_vtable
;
516 * \brief Context initialisation (key schedule) for AES CBC encryption
517 * (`aes_big` implementation).
519 * \param ctx context to initialise.
520 * \param key secret key.
521 * \param len secret key length (in bytes).
523 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys
*ctx
,
524 const void *key
, size_t len
);
527 * \brief Context initialisation (key schedule) for AES CBC decryption
528 * (`aes_big` implementation).
530 * \param ctx context to initialise.
531 * \param key secret key.
532 * \param len secret key length (in bytes).
534 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys
*ctx
,
535 const void *key
, size_t len
);
538 * \brief Context initialisation (key schedule) for AES CTR encryption
539 * and decryption (`aes_big` implementation).
541 * \param ctx context to initialise.
542 * \param key secret key.
543 * \param len secret key length (in bytes).
545 void br_aes_big_ctr_init(br_aes_big_ctr_keys
*ctx
,
546 const void *key
, size_t len
);
549 * \brief CBC encryption with AES (`aes_big` implementation).
551 * \param ctx context (already initialised).
552 * \param iv IV (updated).
553 * \param data data to encrypt (updated).
554 * \param len data length (in bytes, MUST be multiple of 16).
556 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys
*ctx
, void *iv
,
557 void *data
, size_t len
);
560 * \brief CBC decryption with AES (`aes_big` implementation).
562 * \param ctx context (already initialised).
563 * \param iv IV (updated).
564 * \param data data to decrypt (updated).
565 * \param len data length (in bytes, MUST be multiple of 16).
567 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys
*ctx
, void *iv
,
568 void *data
, size_t len
);
571 * \brief CTR encryption and decryption with AES (`aes_big` implementation).
573 * \param ctx context (already initialised).
574 * \param iv IV (constant, 12 bytes).
575 * \param cc initial block counter value.
576 * \param data data to decrypt (updated).
577 * \param len data length (in bytes).
578 * \return new block counter value.
580 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys
*ctx
,
581 const void *iv
, uint32_t cc
, void *data
, size_t len
);
584 * AES implementation optimized for size. It is slower than the
585 * traditional table-based AES implementation, but requires much less
586 * code. It still uses data-dependent table accesses (albeit within a
587 * much smaller 256-byte table), which makes it conceptually vulnerable
588 * to cache-timing attacks.
591 /** \brief AES block size (16 bytes). */
592 #define br_aes_small_BLOCK_SIZE 16
595 * \brief Context for AES subkeys (`aes_small` implementation, CBC 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_cbcenc_class
*vtable
;
603 #ifndef BR_DOXYGEN_IGNORE
607 } br_aes_small_cbcenc_keys
;
610 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption).
612 * First field is a pointer to the vtable; it is set by the initialisation
613 * function. Other fields are not supposed to be accessed by user code.
616 /** \brief Pointer to vtable for this context. */
617 const br_block_cbcdec_class
*vtable
;
618 #ifndef BR_DOXYGEN_IGNORE
622 } br_aes_small_cbcdec_keys
;
625 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption
628 * First field is a pointer to the vtable; it is set by the initialisation
629 * function. Other fields are not supposed to be accessed by user code.
632 /** \brief Pointer to vtable for this context. */
633 const br_block_ctr_class
*vtable
;
634 #ifndef BR_DOXYGEN_IGNORE
638 } br_aes_small_ctr_keys
;
641 * \brief Class instance for AES CBC encryption (`aes_small` implementation).
643 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable
;
646 * \brief Class instance for AES CBC decryption (`aes_small` implementation).
648 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable
;
651 * \brief Class instance for AES CTR encryption and decryption
652 * (`aes_small` implementation).
654 extern const br_block_ctr_class br_aes_small_ctr_vtable
;
657 * \brief Context initialisation (key schedule) for AES CBC encryption
658 * (`aes_small` implementation).
660 * \param ctx context to initialise.
661 * \param key secret key.
662 * \param len secret key length (in bytes).
664 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys
*ctx
,
665 const void *key
, size_t len
);
668 * \brief Context initialisation (key schedule) for AES CBC decryption
669 * (`aes_small` implementation).
671 * \param ctx context to initialise.
672 * \param key secret key.
673 * \param len secret key length (in bytes).
675 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys
*ctx
,
676 const void *key
, size_t len
);
679 * \brief Context initialisation (key schedule) for AES CTR encryption
680 * and decryption (`aes_small` implementation).
682 * \param ctx context to initialise.
683 * \param key secret key.
684 * \param len secret key length (in bytes).
686 void br_aes_small_ctr_init(br_aes_small_ctr_keys
*ctx
,
687 const void *key
, size_t len
);
690 * \brief CBC encryption with AES (`aes_small` implementation).
692 * \param ctx context (already initialised).
693 * \param iv IV (updated).
694 * \param data data to encrypt (updated).
695 * \param len data length (in bytes, MUST be multiple of 16).
697 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys
*ctx
, void *iv
,
698 void *data
, size_t len
);
701 * \brief CBC decryption with AES (`aes_small` implementation).
703 * \param ctx context (already initialised).
704 * \param iv IV (updated).
705 * \param data data to decrypt (updated).
706 * \param len data length (in bytes, MUST be multiple of 16).
708 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys
*ctx
, void *iv
,
709 void *data
, size_t len
);
712 * \brief CTR encryption and decryption with AES (`aes_small` implementation).
714 * \param ctx context (already initialised).
715 * \param iv IV (constant, 12 bytes).
716 * \param cc initial block counter value.
717 * \param data data to decrypt (updated).
718 * \param len data length (in bytes).
719 * \return new block counter value.
721 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys
*ctx
,
722 const void *iv
, uint32_t cc
, void *data
, size_t len
);
725 * Constant-time AES implementation. Its size is similar to that of
726 * 'aes_big', and its performance is similar to that of 'aes_small' (faster
727 * decryption, slower encryption). However, it is constant-time, i.e.
728 * immune to cache-timing and similar attacks.
731 /** \brief AES block size (16 bytes). */
732 #define br_aes_ct_BLOCK_SIZE 16
735 * \brief Context for AES subkeys (`aes_ct` implementation, CBC 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_cbcenc_class
*vtable
;
743 #ifndef BR_DOXYGEN_IGNORE
747 } br_aes_ct_cbcenc_keys
;
750 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption).
752 * First field is a pointer to the vtable; it is set by the initialisation
753 * function. Other fields are not supposed to be accessed by user code.
756 /** \brief Pointer to vtable for this context. */
757 const br_block_cbcdec_class
*vtable
;
758 #ifndef BR_DOXYGEN_IGNORE
762 } br_aes_ct_cbcdec_keys
;
765 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption
768 * First field is a pointer to the vtable; it is set by the initialisation
769 * function. Other fields are not supposed to be accessed by user code.
772 /** \brief Pointer to vtable for this context. */
773 const br_block_ctr_class
*vtable
;
774 #ifndef BR_DOXYGEN_IGNORE
778 } br_aes_ct_ctr_keys
;
781 * \brief Class instance for AES CBC encryption (`aes_ct` implementation).
783 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable
;
786 * \brief Class instance for AES CBC decryption (`aes_ct` implementation).
788 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable
;
791 * \brief Class instance for AES CTR encryption and decryption
792 * (`aes_ct` implementation).
794 extern const br_block_ctr_class br_aes_ct_ctr_vtable
;
797 * \brief Context initialisation (key schedule) for AES CBC encryption
798 * (`aes_ct` implementation).
800 * \param ctx context to initialise.
801 * \param key secret key.
802 * \param len secret key length (in bytes).
804 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys
*ctx
,
805 const void *key
, size_t len
);
808 * \brief Context initialisation (key schedule) for AES CBC decryption
809 * (`aes_ct` implementation).
811 * \param ctx context to initialise.
812 * \param key secret key.
813 * \param len secret key length (in bytes).
815 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys
*ctx
,
816 const void *key
, size_t len
);
819 * \brief Context initialisation (key schedule) for AES CTR encryption
820 * and decryption (`aes_ct` implementation).
822 * \param ctx context to initialise.
823 * \param key secret key.
824 * \param len secret key length (in bytes).
826 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys
*ctx
,
827 const void *key
, size_t len
);
830 * \brief CBC encryption with AES (`aes_ct` implementation).
832 * \param ctx context (already initialised).
833 * \param iv IV (updated).
834 * \param data data to encrypt (updated).
835 * \param len data length (in bytes, MUST be multiple of 16).
837 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys
*ctx
, void *iv
,
838 void *data
, size_t len
);
841 * \brief CBC decryption with AES (`aes_ct` implementation).
843 * \param ctx context (already initialised).
844 * \param iv IV (updated).
845 * \param data data to decrypt (updated).
846 * \param len data length (in bytes, MUST be multiple of 16).
848 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys
*ctx
, void *iv
,
849 void *data
, size_t len
);
852 * \brief CTR encryption and decryption with AES (`aes_ct` implementation).
854 * \param ctx context (already initialised).
855 * \param iv IV (constant, 12 bytes).
856 * \param cc initial block counter value.
857 * \param data data to decrypt (updated).
858 * \param len data length (in bytes).
859 * \return new block counter value.
861 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys
*ctx
,
862 const void *iv
, uint32_t cc
, void *data
, size_t len
);
865 * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
866 * but uses 64-bit registers, making it about twice faster than 'aes_ct'
867 * on 64-bit platforms, while remaining constant-time and with a similar
868 * code size. (The doubling in performance is only for CBC decryption
869 * and CTR mode; CBC encryption is non-parallel and cannot benefit from
870 * the larger registers.)
873 /** \brief AES block size (16 bytes). */
874 #define br_aes_ct64_BLOCK_SIZE 16
877 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC 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_cbcenc_class
*vtable
;
885 #ifndef BR_DOXYGEN_IGNORE
889 } br_aes_ct64_cbcenc_keys
;
892 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption).
894 * First field is a pointer to the vtable; it is set by the initialisation
895 * function. Other fields are not supposed to be accessed by user code.
898 /** \brief Pointer to vtable for this context. */
899 const br_block_cbcdec_class
*vtable
;
900 #ifndef BR_DOXYGEN_IGNORE
904 } br_aes_ct64_cbcdec_keys
;
907 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption
910 * First field is a pointer to the vtable; it is set by the initialisation
911 * function. Other fields are not supposed to be accessed by user code.
914 /** \brief Pointer to vtable for this context. */
915 const br_block_ctr_class
*vtable
;
916 #ifndef BR_DOXYGEN_IGNORE
920 } br_aes_ct64_ctr_keys
;
923 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation).
925 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable
;
928 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation).
930 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable
;
933 * \brief Class instance for AES CTR encryption and decryption
934 * (`aes_ct64` implementation).
936 extern const br_block_ctr_class br_aes_ct64_ctr_vtable
;
939 * \brief Context initialisation (key schedule) for AES CBC encryption
940 * (`aes_ct64` implementation).
942 * \param ctx context to initialise.
943 * \param key secret key.
944 * \param len secret key length (in bytes).
946 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys
*ctx
,
947 const void *key
, size_t len
);
950 * \brief Context initialisation (key schedule) for AES CBC decryption
951 * (`aes_ct64` implementation).
953 * \param ctx context to initialise.
954 * \param key secret key.
955 * \param len secret key length (in bytes).
957 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys
*ctx
,
958 const void *key
, size_t len
);
961 * \brief Context initialisation (key schedule) for AES CTR encryption
962 * and decryption (`aes_ct64` implementation).
964 * \param ctx context to initialise.
965 * \param key secret key.
966 * \param len secret key length (in bytes).
968 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys
*ctx
,
969 const void *key
, size_t len
);
972 * \brief CBC encryption with AES (`aes_ct64` implementation).
974 * \param ctx context (already initialised).
975 * \param iv IV (updated).
976 * \param data data to encrypt (updated).
977 * \param len data length (in bytes, MUST be multiple of 16).
979 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys
*ctx
, void *iv
,
980 void *data
, size_t len
);
983 * \brief CBC decryption with AES (`aes_ct64` implementation).
985 * \param ctx context (already initialised).
986 * \param iv IV (updated).
987 * \param data data to decrypt (updated).
988 * \param len data length (in bytes, MUST be multiple of 16).
990 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys
*ctx
, void *iv
,
991 void *data
, size_t len
);
994 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation).
996 * \param ctx context (already initialised).
997 * \param iv IV (constant, 12 bytes).
998 * \param cc initial block counter value.
999 * \param data data to decrypt (updated).
1000 * \param len data length (in bytes).
1001 * \return new block counter value.
1003 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys
*ctx
,
1004 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1007 * AES implementation using AES-NI opcodes (x86 platform).
1010 /** \brief AES block size (16 bytes). */
1011 #define br_aes_x86ni_BLOCK_SIZE 16
1014 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC encryption).
1016 * First field is a pointer to the vtable; it is set by the initialisation
1017 * function. Other fields are not supposed to be accessed by user code.
1020 /** \brief Pointer to vtable for this context. */
1021 const br_block_cbcenc_class
*vtable
;
1022 #ifndef BR_DOXYGEN_IGNORE
1024 unsigned char skni
[16 * 15];
1026 unsigned num_rounds
;
1028 } br_aes_x86ni_cbcenc_keys
;
1031 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC decryption).
1033 * First field is a pointer to the vtable; it is set by the initialisation
1034 * function. Other fields are not supposed to be accessed by user code.
1037 /** \brief Pointer to vtable for this context. */
1038 const br_block_cbcdec_class
*vtable
;
1039 #ifndef BR_DOXYGEN_IGNORE
1041 unsigned char skni
[16 * 15];
1043 unsigned num_rounds
;
1045 } br_aes_x86ni_cbcdec_keys
;
1048 * \brief Context for AES subkeys (`aes_x86ni` implementation, CTR encryption
1051 * First field is a pointer to the vtable; it is set by the initialisation
1052 * function. Other fields are not supposed to be accessed by user code.
1055 /** \brief Pointer to vtable for this context. */
1056 const br_block_ctr_class
*vtable
;
1057 #ifndef BR_DOXYGEN_IGNORE
1059 unsigned char skni
[16 * 15];
1061 unsigned num_rounds
;
1063 } br_aes_x86ni_ctr_keys
;
1066 * \brief Class instance for AES CBC encryption (`aes_x86ni` implementation).
1068 * Since this implementation might be omitted from the library, or the
1069 * AES opcode unavailable on the current CPU, a pointer to this class
1070 * instance should be obtained through `br_aes_x86ni_cbcenc_get_vtable()`.
1072 extern const br_block_cbcenc_class br_aes_x86ni_cbcenc_vtable
;
1075 * \brief Class instance for AES CBC decryption (`aes_x86ni` implementation).
1077 * Since this implementation might be omitted from the library, or the
1078 * AES opcode unavailable on the current CPU, a pointer to this class
1079 * instance should be obtained through `br_aes_x86ni_cbcdec_get_vtable()`.
1081 extern const br_block_cbcdec_class br_aes_x86ni_cbcdec_vtable
;
1084 * \brief Class instance for AES CTR encryption and decryption
1085 * (`aes_x86ni` implementation).
1087 * Since this implementation might be omitted from the library, or the
1088 * AES opcode unavailable on the current CPU, a pointer to this class
1089 * instance should be obtained through `br_aes_x86ni_ctr_get_vtable()`.
1091 extern const br_block_ctr_class br_aes_x86ni_ctr_vtable
;
1094 * \brief Context initialisation (key schedule) for AES CBC encryption
1095 * (`aes_x86ni` implementation).
1097 * \param ctx context to initialise.
1098 * \param key secret key.
1099 * \param len secret key length (in bytes).
1101 void br_aes_x86ni_cbcenc_init(br_aes_x86ni_cbcenc_keys
*ctx
,
1102 const void *key
, size_t len
);
1105 * \brief Context initialisation (key schedule) for AES CBC decryption
1106 * (`aes_x86ni` implementation).
1108 * \param ctx context to initialise.
1109 * \param key secret key.
1110 * \param len secret key length (in bytes).
1112 void br_aes_x86ni_cbcdec_init(br_aes_x86ni_cbcdec_keys
*ctx
,
1113 const void *key
, size_t len
);
1116 * \brief Context initialisation (key schedule) for AES CTR encryption
1117 * and decryption (`aes_x86ni` implementation).
1119 * \param ctx context to initialise.
1120 * \param key secret key.
1121 * \param len secret key length (in bytes).
1123 void br_aes_x86ni_ctr_init(br_aes_x86ni_ctr_keys
*ctx
,
1124 const void *key
, size_t len
);
1127 * \brief CBC encryption with AES (`aes_x86ni` implementation).
1129 * \param ctx context (already initialised).
1130 * \param iv IV (updated).
1131 * \param data data to encrypt (updated).
1132 * \param len data length (in bytes, MUST be multiple of 16).
1134 void br_aes_x86ni_cbcenc_run(const br_aes_x86ni_cbcenc_keys
*ctx
, void *iv
,
1135 void *data
, size_t len
);
1138 * \brief CBC decryption with AES (`aes_x86ni` implementation).
1140 * \param ctx context (already initialised).
1141 * \param iv IV (updated).
1142 * \param data data to decrypt (updated).
1143 * \param len data length (in bytes, MUST be multiple of 16).
1145 void br_aes_x86ni_cbcdec_run(const br_aes_x86ni_cbcdec_keys
*ctx
, void *iv
,
1146 void *data
, size_t len
);
1149 * \brief CTR encryption and decryption with AES (`aes_x86ni` implementation).
1151 * \param ctx context (already initialised).
1152 * \param iv IV (constant, 12 bytes).
1153 * \param cc initial block counter value.
1154 * \param data data to decrypt (updated).
1155 * \param len data length (in bytes).
1156 * \return new block counter value.
1158 uint32_t br_aes_x86ni_ctr_run(const br_aes_x86ni_ctr_keys
*ctx
,
1159 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1162 * \brief Obtain the `aes_x86ni` AES-CBC (encryption) implementation, if
1165 * This function returns a pointer to `br_aes_x86ni_cbcenc_vtable`, if
1166 * that implementation was compiled in the library _and_ the x86 AES
1167 * opcodes are available on the currently running CPU. If either of
1168 * these conditions is not met, then this function returns `NULL`.
1170 * \return the `aes_x868ni` AES-CBC (encryption) implementation, or `NULL`.
1172 const br_block_cbcenc_class
*br_aes_x86ni_cbcenc_get_vtable(void);
1175 * \brief Obtain the `aes_x86ni` AES-CBC (decryption) implementation, if
1178 * This function returns a pointer to `br_aes_x86ni_cbcdec_vtable`, if
1179 * that implementation was compiled in the library _and_ the x86 AES
1180 * opcodes are available on the currently running CPU. If either of
1181 * these conditions is not met, then this function returns `NULL`.
1183 * \return the `aes_x868ni` AES-CBC (decryption) implementation, or `NULL`.
1185 const br_block_cbcdec_class
*br_aes_x86ni_cbcdec_get_vtable(void);
1188 * \brief Obtain the `aes_x86ni` AES-CTR implementation, if available.
1190 * This function returns a pointer to `br_aes_x86ni_ctr_vtable`, if
1191 * that implementation was compiled in the library _and_ the x86 AES
1192 * opcodes are available on the currently running CPU. If either of
1193 * these conditions is not met, then this function returns `NULL`.
1195 * \return the `aes_x868ni` AES-CTR implementation, or `NULL`.
1197 const br_block_ctr_class
*br_aes_x86ni_ctr_get_vtable(void);
1200 * AES implementation using POWER8 opcodes.
1203 /** \brief AES block size (16 bytes). */
1204 #define br_aes_pwr8_BLOCK_SIZE 16
1207 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC encryption).
1209 * First field is a pointer to the vtable; it is set by the initialisation
1210 * function. Other fields are not supposed to be accessed by user code.
1213 /** \brief Pointer to vtable for this context. */
1214 const br_block_cbcenc_class
*vtable
;
1215 #ifndef BR_DOXYGEN_IGNORE
1217 unsigned char skni
[16 * 15];
1219 unsigned num_rounds
;
1221 } br_aes_pwr8_cbcenc_keys
;
1224 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC decryption).
1226 * First field is a pointer to the vtable; it is set by the initialisation
1227 * function. Other fields are not supposed to be accessed by user code.
1230 /** \brief Pointer to vtable for this context. */
1231 const br_block_cbcdec_class
*vtable
;
1232 #ifndef BR_DOXYGEN_IGNORE
1234 unsigned char skni
[16 * 15];
1236 unsigned num_rounds
;
1238 } br_aes_pwr8_cbcdec_keys
;
1241 * \brief Context for AES subkeys (`aes_pwr8` implementation, CTR encryption
1244 * First field is a pointer to the vtable; it is set by the initialisation
1245 * function. Other fields are not supposed to be accessed by user code.
1248 /** \brief Pointer to vtable for this context. */
1249 const br_block_ctr_class
*vtable
;
1250 #ifndef BR_DOXYGEN_IGNORE
1252 unsigned char skni
[16 * 15];
1254 unsigned num_rounds
;
1256 } br_aes_pwr8_ctr_keys
;
1259 * \brief Class instance for AES CBC encryption (`aes_pwr8` implementation).
1261 * Since this implementation might be omitted from the library, or the
1262 * AES opcode unavailable on the current CPU, a pointer to this class
1263 * instance should be obtained through `br_aes_pwr8_cbcenc_get_vtable()`.
1265 extern const br_block_cbcenc_class br_aes_pwr8_cbcenc_vtable
;
1268 * \brief Class instance for AES CBC decryption (`aes_pwr8` implementation).
1270 * Since this implementation might be omitted from the library, or the
1271 * AES opcode unavailable on the current CPU, a pointer to this class
1272 * instance should be obtained through `br_aes_pwr8_cbcdec_get_vtable()`.
1274 extern const br_block_cbcdec_class br_aes_pwr8_cbcdec_vtable
;
1277 * \brief Class instance for AES CTR encryption and decryption
1278 * (`aes_pwr8` implementation).
1280 * Since this implementation might be omitted from the library, or the
1281 * AES opcode unavailable on the current CPU, a pointer to this class
1282 * instance should be obtained through `br_aes_pwr8_ctr_get_vtable()`.
1284 extern const br_block_ctr_class br_aes_pwr8_ctr_vtable
;
1287 * \brief Context initialisation (key schedule) for AES CBC encryption
1288 * (`aes_pwr8` implementation).
1290 * \param ctx context to initialise.
1291 * \param key secret key.
1292 * \param len secret key length (in bytes).
1294 void br_aes_pwr8_cbcenc_init(br_aes_pwr8_cbcenc_keys
*ctx
,
1295 const void *key
, size_t len
);
1298 * \brief Context initialisation (key schedule) for AES CBC decryption
1299 * (`aes_pwr8` implementation).
1301 * \param ctx context to initialise.
1302 * \param key secret key.
1303 * \param len secret key length (in bytes).
1305 void br_aes_pwr8_cbcdec_init(br_aes_pwr8_cbcdec_keys
*ctx
,
1306 const void *key
, size_t len
);
1309 * \brief Context initialisation (key schedule) for AES CTR encryption
1310 * and decryption (`aes_pwr8` implementation).
1312 * \param ctx context to initialise.
1313 * \param key secret key.
1314 * \param len secret key length (in bytes).
1316 void br_aes_pwr8_ctr_init(br_aes_pwr8_ctr_keys
*ctx
,
1317 const void *key
, size_t len
);
1320 * \brief CBC encryption with AES (`aes_pwr8` implementation).
1322 * \param ctx context (already initialised).
1323 * \param iv IV (updated).
1324 * \param data data to encrypt (updated).
1325 * \param len data length (in bytes, MUST be multiple of 16).
1327 void br_aes_pwr8_cbcenc_run(const br_aes_pwr8_cbcenc_keys
*ctx
, void *iv
,
1328 void *data
, size_t len
);
1331 * \brief CBC decryption with AES (`aes_pwr8` implementation).
1333 * \param ctx context (already initialised).
1334 * \param iv IV (updated).
1335 * \param data data to decrypt (updated).
1336 * \param len data length (in bytes, MUST be multiple of 16).
1338 void br_aes_pwr8_cbcdec_run(const br_aes_pwr8_cbcdec_keys
*ctx
, void *iv
,
1339 void *data
, size_t len
);
1342 * \brief CTR encryption and decryption with AES (`aes_pwr8` implementation).
1344 * \param ctx context (already initialised).
1345 * \param iv IV (constant, 12 bytes).
1346 * \param cc initial block counter value.
1347 * \param data data to decrypt (updated).
1348 * \param len data length (in bytes).
1349 * \return new block counter value.
1351 uint32_t br_aes_pwr8_ctr_run(const br_aes_pwr8_ctr_keys
*ctx
,
1352 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1355 * \brief Obtain the `aes_pwr8` AES-CBC (encryption) implementation, if
1358 * This function returns a pointer to `br_aes_pwr8_cbcenc_vtable`, if
1359 * that implementation was compiled in the library _and_ the x86 AES
1360 * opcodes are available on the currently running CPU. If either of
1361 * these conditions is not met, then this function returns `NULL`.
1363 * \return the `aes_x868ni` AES-CBC (encryption) implementation, or `NULL`.
1365 const br_block_cbcenc_class
*br_aes_pwr8_cbcenc_get_vtable(void);
1368 * \brief Obtain the `aes_pwr8` AES-CBC (decryption) implementation, if
1371 * This function returns a pointer to `br_aes_pwr8_cbcdec_vtable`, if
1372 * that implementation was compiled in the library _and_ the x86 AES
1373 * opcodes are available on the currently running CPU. If either of
1374 * these conditions is not met, then this function returns `NULL`.
1376 * \return the `aes_x868ni` AES-CBC (decryption) implementation, or `NULL`.
1378 const br_block_cbcdec_class
*br_aes_pwr8_cbcdec_get_vtable(void);
1381 * \brief Obtain the `aes_pwr8` AES-CTR implementation, if available.
1383 * This function returns a pointer to `br_aes_pwr8_ctr_vtable`, if
1384 * that implementation was compiled in the library _and_ the x86 AES
1385 * opcodes are available on the currently running CPU. If either of
1386 * these conditions is not met, then this function returns `NULL`.
1388 * \return the `aes_x868ni` AES-CTR implementation, or `NULL`.
1390 const br_block_ctr_class
*br_aes_pwr8_ctr_get_vtable(void);
1393 * \brief Aggregate structure large enough to be used as context for
1394 * subkeys (CBC encryption) for all AES implementations.
1397 const br_block_cbcenc_class
*vtable
;
1398 br_aes_big_cbcenc_keys c_big
;
1399 br_aes_small_cbcenc_keys c_small
;
1400 br_aes_ct_cbcenc_keys c_ct
;
1401 br_aes_ct64_cbcenc_keys c_ct64
;
1402 br_aes_x86ni_cbcenc_keys c_x86ni
;
1403 br_aes_pwr8_cbcenc_keys c_pwr8
;
1404 } br_aes_gen_cbcenc_keys
;
1407 * \brief Aggregate structure large enough to be used as context for
1408 * subkeys (CBC decryption) for all AES implementations.
1411 const br_block_cbcdec_class
*vtable
;
1412 br_aes_big_cbcdec_keys c_big
;
1413 br_aes_small_cbcdec_keys c_small
;
1414 br_aes_ct_cbcdec_keys c_ct
;
1415 br_aes_ct64_cbcdec_keys c_ct64
;
1416 br_aes_x86ni_cbcdec_keys c_x86ni
;
1417 br_aes_pwr8_cbcdec_keys c_pwr8
;
1418 } br_aes_gen_cbcdec_keys
;
1421 * \brief Aggregate structure large enough to be used as context for
1422 * subkeys (CTR encryption and decryption) for all AES implementations.
1425 const br_block_ctr_class
*vtable
;
1426 br_aes_big_ctr_keys c_big
;
1427 br_aes_small_ctr_keys c_small
;
1428 br_aes_ct_ctr_keys c_ct
;
1429 br_aes_ct64_ctr_keys c_ct64
;
1430 br_aes_x86ni_ctr_keys c_x86ni
;
1431 br_aes_pwr8_ctr_keys c_pwr8
;
1432 } br_aes_gen_ctr_keys
;
1435 * Traditional, table-based implementation for DES/3DES. Since tables are
1436 * used, cache-timing attacks are conceptually possible.
1439 /** \brief DES/3DES block size (8 bytes). */
1440 #define br_des_tab_BLOCK_SIZE 8
1443 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption).
1445 * First field is a pointer to the vtable; it is set by the initialisation
1446 * function. Other fields are not supposed to be accessed by user code.
1449 /** \brief Pointer to vtable for this context. */
1450 const br_block_cbcenc_class
*vtable
;
1451 #ifndef BR_DOXYGEN_IGNORE
1453 unsigned num_rounds
;
1455 } br_des_tab_cbcenc_keys
;
1458 * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption).
1460 * First field is a pointer to the vtable; it is set by the initialisation
1461 * function. Other fields are not supposed to be accessed by user code.
1464 /** \brief Pointer to vtable for this context. */
1465 const br_block_cbcdec_class
*vtable
;
1466 #ifndef BR_DOXYGEN_IGNORE
1468 unsigned num_rounds
;
1470 } br_des_tab_cbcdec_keys
;
1473 * \brief Class instance for DES CBC encryption (`des_tab` implementation).
1475 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable
;
1478 * \brief Class instance for DES CBC decryption (`des_tab` implementation).
1480 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable
;
1483 * \brief Context initialisation (key schedule) for DES CBC encryption
1484 * (`des_tab` implementation).
1486 * \param ctx context to initialise.
1487 * \param key secret key.
1488 * \param len secret key length (in bytes).
1490 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys
*ctx
,
1491 const void *key
, size_t len
);
1494 * \brief Context initialisation (key schedule) for DES CBC decryption
1495 * (`des_tab` implementation).
1497 * \param ctx context to initialise.
1498 * \param key secret key.
1499 * \param len secret key length (in bytes).
1501 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys
*ctx
,
1502 const void *key
, size_t len
);
1505 * \brief CBC encryption with DES (`des_tab` implementation).
1507 * \param ctx context (already initialised).
1508 * \param iv IV (updated).
1509 * \param data data to encrypt (updated).
1510 * \param len data length (in bytes, MUST be multiple of 8).
1512 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys
*ctx
, void *iv
,
1513 void *data
, size_t len
);
1516 * \brief CBC decryption with DES (`des_tab` implementation).
1518 * \param ctx context (already initialised).
1519 * \param iv IV (updated).
1520 * \param data data to decrypt (updated).
1521 * \param len data length (in bytes, MUST be multiple of 8).
1523 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys
*ctx
, void *iv
,
1524 void *data
, size_t len
);
1527 * Constant-time implementation for DES/3DES. It is substantially slower
1528 * (by a factor of about 4x), but also immune to cache-timing attacks.
1531 /** \brief DES/3DES block size (8 bytes). */
1532 #define br_des_ct_BLOCK_SIZE 8
1535 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption).
1537 * First field is a pointer to the vtable; it is set by the initialisation
1538 * function. Other fields are not supposed to be accessed by user code.
1541 /** \brief Pointer to vtable for this context. */
1542 const br_block_cbcenc_class
*vtable
;
1543 #ifndef BR_DOXYGEN_IGNORE
1545 unsigned num_rounds
;
1547 } br_des_ct_cbcenc_keys
;
1550 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption).
1552 * First field is a pointer to the vtable; it is set by the initialisation
1553 * function. Other fields are not supposed to be accessed by user code.
1556 /** \brief Pointer to vtable for this context. */
1557 const br_block_cbcdec_class
*vtable
;
1558 #ifndef BR_DOXYGEN_IGNORE
1560 unsigned num_rounds
;
1562 } br_des_ct_cbcdec_keys
;
1565 * \brief Class instance for DES CBC encryption (`des_ct` implementation).
1567 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable
;
1570 * \brief Class instance for DES CBC decryption (`des_ct` implementation).
1572 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable
;
1575 * \brief Context initialisation (key schedule) for DES CBC encryption
1576 * (`des_ct` implementation).
1578 * \param ctx context to initialise.
1579 * \param key secret key.
1580 * \param len secret key length (in bytes).
1582 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys
*ctx
,
1583 const void *key
, size_t len
);
1586 * \brief Context initialisation (key schedule) for DES CBC decryption
1587 * (`des_ct` implementation).
1589 * \param ctx context to initialise.
1590 * \param key secret key.
1591 * \param len secret key length (in bytes).
1593 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys
*ctx
,
1594 const void *key
, size_t len
);
1597 * \brief CBC encryption with DES (`des_ct` implementation).
1599 * \param ctx context (already initialised).
1600 * \param iv IV (updated).
1601 * \param data data to encrypt (updated).
1602 * \param len data length (in bytes, MUST be multiple of 8).
1604 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys
*ctx
, void *iv
,
1605 void *data
, size_t len
);
1608 * \brief CBC decryption with DES (`des_ct` implementation).
1610 * \param ctx context (already initialised).
1611 * \param iv IV (updated).
1612 * \param data data to decrypt (updated).
1613 * \param len data length (in bytes, MUST be multiple of 8).
1615 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys
*ctx
, void *iv
,
1616 void *data
, size_t len
);
1619 * These structures are large enough to accommodate subkeys for all
1620 * DES/3DES implementations.
1624 * \brief Aggregate structure large enough to be used as context for
1625 * subkeys (CBC encryption) for all DES implementations.
1628 const br_block_cbcenc_class
*vtable
;
1629 br_des_tab_cbcenc_keys tab
;
1630 br_des_ct_cbcenc_keys ct
;
1631 } br_des_gen_cbcenc_keys
;
1634 * \brief Aggregate structure large enough to be used as context for
1635 * subkeys (CBC decryption) for all DES implementations.
1638 const br_block_cbcdec_class
*vtable
;
1639 br_des_tab_cbcdec_keys c_tab
;
1640 br_des_ct_cbcdec_keys c_ct
;
1641 } br_des_gen_cbcdec_keys
;
1644 * \brief Type for a ChaCha20 implementation.
1646 * An implementation follows the description in RFC 7539:
1648 * - Key is 256 bits (`key` points to exactly 32 bytes).
1650 * - IV is 96 bits (`iv` points to exactly 12 bytes).
1652 * - Block counter is over 32 bits and starts at value `cc`; the
1653 * resulting value is returned.
1655 * Data (pointed to by `data`, of length `len`) is encrypted/decrypted
1656 * in place. If `len` is not a multiple of 64, then the excess bytes from
1657 * the last block processing are dropped (therefore, "chunked" processing
1658 * works only as long as each non-final chunk has a length multiple of 64).
1660 * \param key secret key (32 bytes).
1661 * \param iv IV (12 bytes).
1662 * \param cc initial counter value.
1663 * \param data data to encrypt or decrypt.
1664 * \param len data length (in bytes).
1666 typedef uint32_t (*br_chacha20_run
)(const void *key
,
1667 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1670 * \brief ChaCha20 implementation (straightforward C code, constant-time).
1672 * \see br_chacha20_run
1674 * \param key secret key (32 bytes).
1675 * \param iv IV (12 bytes).
1676 * \param cc initial counter value.
1677 * \param data data to encrypt or decrypt.
1678 * \param len data length (in bytes).
1680 uint32_t br_chacha20_ct_run(const void *key
,
1681 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1684 * \brief Type for a ChaCha20+Poly1305 AEAD implementation.
1686 * The provided data is encrypted or decrypted with ChaCha20. The
1687 * authentication tag is computed on the concatenation of the
1688 * additional data and the ciphertext, with the padding and lengths
1689 * as described in RFC 7539 (section 2.8).
1691 * After decryption, the caller is responsible for checking that the
1692 * computed tag matches the expected value.
1694 * \param key secret key (32 bytes).
1695 * \param iv nonce (12 bytes).
1696 * \param data data to encrypt or decrypt.
1697 * \param len data length (in bytes).
1698 * \param aad additional authenticated data.
1699 * \param aad_len length of additional authenticated data (in bytes).
1700 * \param tag output buffer for the authentication tag.
1701 * \param ichacha implementation of ChaCha20.
1702 * \param encrypt non-zero for encryption, zero for decryption.
1704 typedef void (*br_poly1305_run
)(const void *key
, const void *iv
,
1705 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1706 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1709 * \brief ChaCha20+Poly1305 AEAD implementation (mixed 32-bit multiplications).
1711 * \see br_poly1305_run
1713 * \param key secret key (32 bytes).
1714 * \param iv nonce (12 bytes).
1715 * \param data data to encrypt or decrypt.
1716 * \param len data length (in bytes).
1717 * \param aad additional authenticated data.
1718 * \param aad_len length of additional authenticated data (in bytes).
1719 * \param tag output buffer for the authentication tag.
1720 * \param ichacha implementation of ChaCha20.
1721 * \param encrypt non-zero for encryption, zero for decryption.
1723 void br_poly1305_ctmul_run(const void *key
, const void *iv
,
1724 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1725 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1728 * \brief ChaCha20+Poly1305 AEAD implementation (pure 32-bit multiplications).
1730 * \see br_poly1305_run
1732 * \param key secret key (32 bytes).
1733 * \param iv nonce (12 bytes).
1734 * \param data data to encrypt or decrypt.
1735 * \param len data length (in bytes).
1736 * \param aad additional authenticated data.
1737 * \param aad_len length of additional authenticated data (in bytes).
1738 * \param tag output buffer for the authentication tag.
1739 * \param ichacha implementation of ChaCha20.
1740 * \param encrypt non-zero for encryption, zero for decryption.
1742 void br_poly1305_ctmul32_run(const void *key
, const void *iv
,
1743 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1744 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1747 * \brief ChaCha20+Poly1305 AEAD implementation (i15).
1749 * This implementation relies on the generic big integer code "i15"
1750 * (which uses pure 32-bit multiplications). As such, it may save a
1751 * little code footprint in a context where "i15" is already included
1752 * (e.g. for elliptic curves or for RSA); however, it is also
1753 * substantially slower than the ctmul and ctmul32 implementations.
1755 * \see br_poly1305_run
1757 * \param key secret key (32 bytes).
1758 * \param iv nonce (12 bytes).
1759 * \param data data to encrypt or decrypt.
1760 * \param len data length (in bytes).
1761 * \param aad additional authenticated data.
1762 * \param aad_len length of additional authenticated data (in bytes).
1763 * \param tag output buffer for the authentication tag.
1764 * \param ichacha implementation of ChaCha20.
1765 * \param encrypt non-zero for encryption, zero for decryption.
1767 void br_poly1305_i15_run(const void *key
, const void *iv
,
1768 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1769 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1772 * \brief ChaCha20+Poly1305 AEAD implementation (ctmulq).
1774 * This implementation uses 64-bit multiplications (result over 128 bits).
1775 * It is available only on platforms that offer such a primitive (in
1776 * practice, 64-bit architectures). Use `br_poly1305_ctmulq_get()` to
1777 * dynamically obtain a pointer to that function, or 0 if not supported.
1779 * \see br_poly1305_run
1781 * \param key secret key (32 bytes).
1782 * \param iv nonce (12 bytes).
1783 * \param data data to encrypt or decrypt.
1784 * \param len data length (in bytes).
1785 * \param aad additional authenticated data.
1786 * \param aad_len length of additional authenticated data (in bytes).
1787 * \param tag output buffer for the authentication tag.
1788 * \param ichacha implementation of ChaCha20.
1789 * \param encrypt non-zero for encryption, zero for decryption.
1791 void br_poly1305_ctmulq_run(const void *key
, const void *iv
,
1792 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1793 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1796 * \brief Get the ChaCha20+Poly1305 "ctmulq" implementation, if available.
1798 * This function returns a pointer to the `br_poly1305_ctmulq_run()`
1799 * function if supported on the current platform; otherwise, it returns 0.
1801 * \return the ctmulq ChaCha20+Poly1305 implementation, or 0.
1803 br_poly1305_run
br_poly1305_ctmulq_get(void);