2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 #ifndef BR_BEARSSL_BLOCK_H__
26 #define BR_BEARSSL_BLOCK_H__
35 /** \file bearssl_block.h
37 * # Block Ciphers and Symmetric Ciphers
39 * This file documents the API for block ciphers and other symmetric
45 * For a block cipher implementation, up to three separate sets of
46 * functions are provided, for CBC encryption, CBC decryption, and CTR
47 * encryption/decryption. Each set has its own context structure,
48 * initialised with the encryption key.
50 * For CBC encryption and decryption, the data to encrypt or decrypt is
51 * referenced as a sequence of blocks. The implementations assume that
52 * there is no partial block; no padding is applied or removed. The
53 * caller is responsible for handling any kind of padding.
55 * Function for CTR encryption are defined only for block ciphers with
56 * blocks of 16 bytes or more (i.e. AES, but not DES/3DES).
58 * Each implemented block cipher is identified by an "internal name"
59 * from which are derived the names of structures and functions that
60 * implement the cipher. For the block cipher of internal name "`xxx`",
61 * the following are defined:
63 * - `br_xxx_BLOCK_SIZE`
65 * A macro that evaluates to the block size (in bytes) of the
66 * cipher. For all implemented block ciphers, this value is a
69 * - `br_xxx_cbcenc_keys`
71 * Context structure that contains the subkeys resulting from the key
72 * expansion. These subkeys are appropriate for CBC encryption. The
73 * structure first field is called `vtable` and points to the
74 * appropriate OOP structure.
76 * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
78 * Perform key expansion: subkeys for CBC encryption are computed and
79 * written in the provided context structure. The key length MUST be
80 * adequate for the implemented block cipher. This function also sets
83 * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)`
85 * Perform CBC encryption of `len` bytes, in place. The encrypted data
86 * replaces the cleartext. `len` MUST be a multiple of the block length
87 * (if it is not, the function may loop forever or overflow a buffer).
88 * The IV is provided with the `iv` pointer; it is also updated with
89 * a copy of the last encrypted block.
91 * - `br_xxx_cbcdec_keys`
93 * Context structure that contains the subkeys resulting from the key
94 * expansion. These subkeys are appropriate for CBC decryption. The
95 * structure first field is called `vtable` and points to the
96 * appropriate OOP structure.
98 * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
100 * Perform key expansion: subkeys for CBC decryption are computed and
101 * written in the provided context structure. The key length MUST be
102 * adequate for the implemented block cipher. This function also sets
103 * the `vtable` field.
105 * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)`
107 * Perform CBC decryption of `len` bytes, in place. The decrypted data
108 * replaces the ciphertext. `len` MUST be a multiple of the block length
109 * (if it is not, the function may loop forever or overflow a buffer).
110 * The IV is provided with the `iv` pointer; it is also updated with
111 * a copy of the last _encrypted_ block.
113 * - `br_xxx_ctr_keys`
115 * Context structure that contains the subkeys resulting from the key
116 * expansion. These subkeys are appropriate for CTR encryption and
117 * decryption. The structure first field is called `vtable` and
118 * points to the appropriate OOP structure.
120 * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)`
122 * Perform key expansion: subkeys for CTR encryption and decryption
123 * are computed and written in the provided context structure. The
124 * key length MUST be adequate for the implemented block cipher. This
125 * function also sets the `vtable` field.
127 * - `br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv, uint32_t cc, void *data, size_t len)` (returns `uint32_t`)
129 * Perform CTR encryption/decryption of some data. Processing is done
130 * "in place" (the output data replaces the input data). This function
131 * implements the "standard incrementing function" from NIST SP800-38A,
132 * annex B: the IV length shall be 4 bytes less than the block size
133 * (i.e. 12 bytes for AES) and the counter is the 32-bit value starting
134 * with `cc`. The data length (`len`) is not necessarily a multiple of
135 * the block size. The new counter value is returned, which supports
136 * chunked processing, provided that each chunk length (except possibly
137 * the last one) is a multiple of the block size.
140 * It shall be noted that the key expansion functions return `void`. If
141 * the provided key length is not allowed, then there will be no error
142 * reporting; implementations need not validate the key length, thus an
143 * invalid key length may result in undefined behaviour (e.g. buffer
146 * Subkey structures contain no interior pointer, and no external
147 * resources are allocated upon key expansion. They can thus be
148 * discarded without any explicit deallocation.
151 * ## Object-Oriented API
153 * Each context structure begins with a field (called `vtable`) that
154 * points to an instance of a structure that references the relevant
155 * functions through pointers. Each such structure contains the
160 * The size (in bytes) of the context structure for subkeys.
164 * The cipher block size (in bytes).
168 * The base-2 logarithm of cipher block size (e.g. 4 for blocks
173 * Pointer to the key expansion function.
177 * Pointer to the encryption/decryption function.
180 * For block cipher "`xxx`", static, constant instances of these
181 * structures are defined, under the names:
183 * - `br_xxx_cbcenc_vtable`
184 * - `br_xxx_cbcdec_vtable`
185 * - `br_xxx_ctr_vtable`
188 * ## Implemented Block Ciphers
190 * Provided implementations are:
192 * | Name | Function | Block Size (bytes) | Key lengths (bytes) |
193 * | :-------- | :------- | :----------------: | :-----------------: |
194 * | aes_big | AES | 16 | 16, 24 and 32 |
195 * | aes_small | AES | 16 | 16, 24 and 32 |
196 * | aes_ct | AES | 16 | 16, 24 and 32 |
197 * | aes_ct64 | AES | 16 | 16, 24 and 32 |
198 * | aes_x86ni | AES | 16 | 16, 24 and 32 |
199 * | aes_pwr8 | AES | 16 | 16, 24 and 32 |
200 * | des_ct | DES/3DES | 8 | 8, 16 and 24 |
201 * | des_tab | DES/3DES | 8 | 8, 16 and 24 |
203 * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8,
204 * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so
205 * the _effective_ key lengths, from a security point of view, are 56,
206 * 112 and 168 bits, respectively.
208 * `aes_big` is a "classical" AES implementation, using tables. It
209 * is fast but not constant-time, since it makes data-dependent array
212 * `aes_small` is an AES implementation optimized for code size. It
213 * is substantially slower than `aes_big`; it is not constant-time
216 * `aes_ct` is a constant-time implementation of AES; its code is about
217 * as big as that of `aes_big`, while its performance is comparable to
218 * that of `aes_small`. However, it is constant-time. This
219 * implementation should thus be considered to be the "default" AES in
220 * BearSSL, to be used unless the operational context guarantees that a
221 * non-constant-time implementation is safe, or an architecture-specific
222 * constant-time implementation can be used (e.g. using dedicated
225 * `aes_ct64` is another constant-time implementation of AES. It is
226 * similar to `aes_ct` but uses 64-bit values. On 32-bit machines,
227 * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has
228 * a larger footprint; however, on 64-bit architectures, `aes_ct64`
229 * is typically twice faster than `aes_ct` for modes that allow parallel
230 * operations (i.e. CTR, and CBC decryption, but not CBC encryption).
232 * `aes_x86ni` exists only on x86 architectures (32-bit and 64-bit). It
233 * uses the AES-NI opcodes when available.
235 * `aes_pwr8` exists only on PowerPC / POWER architectures (32-bit and
236 * 64-bit, both little-endian and big-endian). It uses the AES opcodes
237 * present in POWER8 and later.
239 * `des_tab` is a classic, table-based implementation of DES/3DES. It
240 * is not constant-time.
242 * `des_ct` is an constant-time implementation of DES/3DES. It is
243 * substantially slower than `des_tab`.
245 * ## ChaCha20 and Poly1305
247 * ChaCha20 is a stream cipher. Poly1305 is a MAC algorithm. They
248 * are described in [RFC 7539](https://tools.ietf.org/html/rfc7539).
250 * Two function pointer types are defined:
252 * - `br_chacha20_run` describes a function that implements ChaCha20
255 * - `br_poly1305_run` describes an implementation of Poly1305,
256 * in the AEAD combination with ChaCha20 specified in RFC 7539
257 * (the ChaCha20 implementation is provided as a function pointer).
259 * `chacha20_ct` is a straightforward implementation of ChaCha20 in
260 * plain C; it is constant-time, small, and reasonably fast.
262 * `chacha20_sse2` leverages SSE2 opcodes (on x86 architectures that
263 * support these opcodes). It is faster than `chacha20_ct`.
265 * `poly1305_ctmul` is an implementation of the ChaCha20+Poly1305 AEAD
266 * construction, where the Poly1305 part is performed with mixed 32-bit
267 * multiplications (operands are 32-bit, result is 64-bit).
269 * `poly1305_ctmul32` implements ChaCha20+Poly1305 using pure 32-bit
270 * multiplications (32-bit operands, 32-bit result). It is slower than
271 * `poly1305_ctmul`, except on some specific architectures such as
272 * the ARM Cortex M0+.
274 * `poly1305_ctmulq` implements ChaCha20+Poly1305 with mixed 64-bit
275 * multiplications (operands are 64-bit, result is 128-bit) on 64-bit
276 * platforms that support such operations.
278 * `poly1305_i15` implements ChaCha20+Poly1305 with the generic "i15"
279 * big integer implementation. It is meant mostly for testing purposes,
280 * although it can help with saving a few hundred bytes of code footprint
281 * on systems where code size is scarce.
285 * \brief Class type for CBC encryption implementations.
287 * A `br_block_cbcenc_class` instance points to the functions implementing
288 * a specific block cipher, when used in CBC mode for encrypting data.
290 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class
;
291 struct br_block_cbcenc_class_
{
293 * \brief Size (in bytes) of the context structure appropriate
294 * for containing subkeys.
299 * \brief Size of individual blocks (in bytes).
304 * \brief Base-2 logarithm of the size of individual blocks,
305 * expressed in bytes.
307 unsigned log_block_size
;
310 * \brief Initialisation function.
312 * This function sets the `vtable` field in the context structure.
313 * The key length MUST be one of the key lengths supported by
314 * the implementation.
316 * \param ctx context structure to initialise.
317 * \param key secret key.
318 * \param key_len key length (in bytes).
320 void (*init
)(const br_block_cbcenc_class
**ctx
,
321 const void *key
, size_t key_len
);
324 * \brief Run the CBC encryption.
326 * The `iv` parameter points to the IV for this run; it is
327 * updated with a copy of the last encrypted block. The data
328 * is encrypted "in place"; its length (`len`) MUST be a
329 * multiple of the block size.
331 * \param ctx context structure (already initialised).
332 * \param iv IV for CBC encryption (updated).
333 * \param data data to encrypt.
334 * \param len data length (in bytes, multiple of block size).
336 void (*run
)(const br_block_cbcenc_class
*const *ctx
,
337 void *iv
, void *data
, size_t len
);
341 * \brief Class type for CBC decryption implementations.
343 * A `br_block_cbcdec_class` instance points to the functions implementing
344 * a specific block cipher, when used in CBC mode for decrypting data.
346 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class
;
347 struct br_block_cbcdec_class_
{
349 * \brief Size (in bytes) of the context structure appropriate
350 * for containing subkeys.
355 * \brief Size of individual blocks (in bytes).
360 * \brief Base-2 logarithm of the size of individual blocks,
361 * expressed in bytes.
363 unsigned log_block_size
;
366 * \brief Initialisation function.
368 * This function sets the `vtable` field in the context structure.
369 * The key length MUST be one of the key lengths supported by
370 * the implementation.
372 * \param ctx context structure to initialise.
373 * \param key secret key.
374 * \param key_len key length (in bytes).
376 void (*init
)(const br_block_cbcdec_class
**ctx
,
377 const void *key
, size_t key_len
);
380 * \brief Run the CBC decryption.
382 * The `iv` parameter points to the IV for this run; it is
383 * updated with a copy of the last encrypted block. The data
384 * is decrypted "in place"; its length (`len`) MUST be a
385 * multiple of the block size.
387 * \param ctx context structure (already initialised).
388 * \param iv IV for CBC decryption (updated).
389 * \param data data to decrypt.
390 * \param len data length (in bytes, multiple of block size).
392 void (*run
)(const br_block_cbcdec_class
*const *ctx
,
393 void *iv
, void *data
, size_t len
);
397 * \brief Class type for CTR encryption/decryption implementations.
399 * A `br_block_ctr_class` instance points to the functions implementing
400 * a specific block cipher, when used in CTR mode for encrypting or
403 typedef struct br_block_ctr_class_ br_block_ctr_class
;
404 struct br_block_ctr_class_
{
406 * \brief Size (in bytes) of the context structure appropriate
407 * for containing subkeys.
412 * \brief Size of individual blocks (in bytes).
417 * \brief Base-2 logarithm of the size of individual blocks,
418 * expressed in bytes.
420 unsigned log_block_size
;
423 * \brief Initialisation function.
425 * This function sets the `vtable` field in the context structure.
426 * The key length MUST be one of the key lengths supported by
427 * the implementation.
429 * \param ctx context structure to initialise.
430 * \param key secret key.
431 * \param key_len key length (in bytes).
433 void (*init
)(const br_block_ctr_class
**ctx
,
434 const void *key
, size_t key_len
);
437 * \brief Run the CTR encryption or decryption.
439 * The `iv` parameter points to the IV for this run; its
440 * length is exactly 4 bytes less than the block size (e.g.
441 * 12 bytes for AES/CTR). The IV is combined with a 32-bit
442 * block counter to produce the block value which is processed
443 * with the block cipher.
445 * The data to encrypt or decrypt is updated "in place". Its
446 * length (`len` bytes) is not required to be a multiple of
447 * the block size; if the final block is partial, then the
448 * corresponding key stream bits are dropped.
450 * The resulting counter value is returned.
452 * \param ctx context structure (already initialised).
453 * \param iv IV for CTR encryption/decryption.
454 * \param cc initial value for the block counter.
455 * \param data data to encrypt or decrypt.
456 * \param len data length (in bytes).
457 * \return the new block counter value.
459 uint32_t (*run
)(const br_block_ctr_class
*const *ctx
,
460 const void *iv
, uint32_t cc
, void *data
, size_t len
);
464 * Traditional, table-based AES implementation. It is fast, but uses
465 * internal tables (in particular a 1 kB table for encryption, another
466 * 1 kB table for decryption, and a 256-byte table for key schedule),
467 * and it is not constant-time. In contexts where cache-timing attacks
468 * apply, this implementation may leak the secret key.
471 /** \brief AES block size (16 bytes). */
472 #define br_aes_big_BLOCK_SIZE 16
475 * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption).
477 * First field is a pointer to the vtable; it is set by the initialisation
478 * function. Other fields are not supposed to be accessed by user code.
481 /** \brief Pointer to vtable for this context. */
482 const br_block_cbcenc_class
*vtable
;
483 #ifndef BR_DOXYGEN_IGNORE
487 } br_aes_big_cbcenc_keys
;
490 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption).
492 * First field is a pointer to the vtable; it is set by the initialisation
493 * function. Other fields are not supposed to be accessed by user code.
496 /** \brief Pointer to vtable for this context. */
497 const br_block_cbcdec_class
*vtable
;
498 #ifndef BR_DOXYGEN_IGNORE
502 } br_aes_big_cbcdec_keys
;
505 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption
508 * First field is a pointer to the vtable; it is set by the initialisation
509 * function. Other fields are not supposed to be accessed by user code.
512 /** \brief Pointer to vtable for this context. */
513 const br_block_ctr_class
*vtable
;
514 #ifndef BR_DOXYGEN_IGNORE
518 } br_aes_big_ctr_keys
;
521 * \brief Class instance for AES CBC encryption (`aes_big` implementation).
523 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable
;
526 * \brief Class instance for AES CBC decryption (`aes_big` implementation).
528 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable
;
531 * \brief Class instance for AES CTR encryption and decryption
532 * (`aes_big` implementation).
534 extern const br_block_ctr_class br_aes_big_ctr_vtable
;
537 * \brief Context initialisation (key schedule) for AES CBC encryption
538 * (`aes_big` implementation).
540 * \param ctx context to initialise.
541 * \param key secret key.
542 * \param len secret key length (in bytes).
544 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys
*ctx
,
545 const void *key
, size_t len
);
548 * \brief Context initialisation (key schedule) for AES CBC decryption
549 * (`aes_big` implementation).
551 * \param ctx context to initialise.
552 * \param key secret key.
553 * \param len secret key length (in bytes).
555 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys
*ctx
,
556 const void *key
, size_t len
);
559 * \brief Context initialisation (key schedule) for AES CTR encryption
560 * and decryption (`aes_big` implementation).
562 * \param ctx context to initialise.
563 * \param key secret key.
564 * \param len secret key length (in bytes).
566 void br_aes_big_ctr_init(br_aes_big_ctr_keys
*ctx
,
567 const void *key
, size_t len
);
570 * \brief CBC encryption with AES (`aes_big` implementation).
572 * \param ctx context (already initialised).
573 * \param iv IV (updated).
574 * \param data data to encrypt (updated).
575 * \param len data length (in bytes, MUST be multiple of 16).
577 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys
*ctx
, void *iv
,
578 void *data
, size_t len
);
581 * \brief CBC decryption with AES (`aes_big` implementation).
583 * \param ctx context (already initialised).
584 * \param iv IV (updated).
585 * \param data data to decrypt (updated).
586 * \param len data length (in bytes, MUST be multiple of 16).
588 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys
*ctx
, void *iv
,
589 void *data
, size_t len
);
592 * \brief CTR encryption and decryption with AES (`aes_big` implementation).
594 * \param ctx context (already initialised).
595 * \param iv IV (constant, 12 bytes).
596 * \param cc initial block counter value.
597 * \param data data to decrypt (updated).
598 * \param len data length (in bytes).
599 * \return new block counter value.
601 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys
*ctx
,
602 const void *iv
, uint32_t cc
, void *data
, size_t len
);
605 * AES implementation optimized for size. It is slower than the
606 * traditional table-based AES implementation, but requires much less
607 * code. It still uses data-dependent table accesses (albeit within a
608 * much smaller 256-byte table), which makes it conceptually vulnerable
609 * to cache-timing attacks.
612 /** \brief AES block size (16 bytes). */
613 #define br_aes_small_BLOCK_SIZE 16
616 * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption).
618 * First field is a pointer to the vtable; it is set by the initialisation
619 * function. Other fields are not supposed to be accessed by user code.
622 /** \brief Pointer to vtable for this context. */
623 const br_block_cbcenc_class
*vtable
;
624 #ifndef BR_DOXYGEN_IGNORE
628 } br_aes_small_cbcenc_keys
;
631 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption).
633 * First field is a pointer to the vtable; it is set by the initialisation
634 * function. Other fields are not supposed to be accessed by user code.
637 /** \brief Pointer to vtable for this context. */
638 const br_block_cbcdec_class
*vtable
;
639 #ifndef BR_DOXYGEN_IGNORE
643 } br_aes_small_cbcdec_keys
;
646 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption
649 * First field is a pointer to the vtable; it is set by the initialisation
650 * function. Other fields are not supposed to be accessed by user code.
653 /** \brief Pointer to vtable for this context. */
654 const br_block_ctr_class
*vtable
;
655 #ifndef BR_DOXYGEN_IGNORE
659 } br_aes_small_ctr_keys
;
662 * \brief Class instance for AES CBC encryption (`aes_small` implementation).
664 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable
;
667 * \brief Class instance for AES CBC decryption (`aes_small` implementation).
669 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable
;
672 * \brief Class instance for AES CTR encryption and decryption
673 * (`aes_small` implementation).
675 extern const br_block_ctr_class br_aes_small_ctr_vtable
;
678 * \brief Context initialisation (key schedule) for AES CBC encryption
679 * (`aes_small` implementation).
681 * \param ctx context to initialise.
682 * \param key secret key.
683 * \param len secret key length (in bytes).
685 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys
*ctx
,
686 const void *key
, size_t len
);
689 * \brief Context initialisation (key schedule) for AES CBC decryption
690 * (`aes_small` implementation).
692 * \param ctx context to initialise.
693 * \param key secret key.
694 * \param len secret key length (in bytes).
696 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys
*ctx
,
697 const void *key
, size_t len
);
700 * \brief Context initialisation (key schedule) for AES CTR encryption
701 * and decryption (`aes_small` implementation).
703 * \param ctx context to initialise.
704 * \param key secret key.
705 * \param len secret key length (in bytes).
707 void br_aes_small_ctr_init(br_aes_small_ctr_keys
*ctx
,
708 const void *key
, size_t len
);
711 * \brief CBC encryption with AES (`aes_small` implementation).
713 * \param ctx context (already initialised).
714 * \param iv IV (updated).
715 * \param data data to encrypt (updated).
716 * \param len data length (in bytes, MUST be multiple of 16).
718 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys
*ctx
, void *iv
,
719 void *data
, size_t len
);
722 * \brief CBC decryption with AES (`aes_small` implementation).
724 * \param ctx context (already initialised).
725 * \param iv IV (updated).
726 * \param data data to decrypt (updated).
727 * \param len data length (in bytes, MUST be multiple of 16).
729 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys
*ctx
, void *iv
,
730 void *data
, size_t len
);
733 * \brief CTR encryption and decryption with AES (`aes_small` implementation).
735 * \param ctx context (already initialised).
736 * \param iv IV (constant, 12 bytes).
737 * \param cc initial block counter value.
738 * \param data data to decrypt (updated).
739 * \param len data length (in bytes).
740 * \return new block counter value.
742 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys
*ctx
,
743 const void *iv
, uint32_t cc
, void *data
, size_t len
);
746 * Constant-time AES implementation. Its size is similar to that of
747 * 'aes_big', and its performance is similar to that of 'aes_small' (faster
748 * decryption, slower encryption). However, it is constant-time, i.e.
749 * immune to cache-timing and similar attacks.
752 /** \brief AES block size (16 bytes). */
753 #define br_aes_ct_BLOCK_SIZE 16
756 * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption).
758 * First field is a pointer to the vtable; it is set by the initialisation
759 * function. Other fields are not supposed to be accessed by user code.
762 /** \brief Pointer to vtable for this context. */
763 const br_block_cbcenc_class
*vtable
;
764 #ifndef BR_DOXYGEN_IGNORE
768 } br_aes_ct_cbcenc_keys
;
771 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption).
773 * First field is a pointer to the vtable; it is set by the initialisation
774 * function. Other fields are not supposed to be accessed by user code.
777 /** \brief Pointer to vtable for this context. */
778 const br_block_cbcdec_class
*vtable
;
779 #ifndef BR_DOXYGEN_IGNORE
783 } br_aes_ct_cbcdec_keys
;
786 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption
789 * First field is a pointer to the vtable; it is set by the initialisation
790 * function. Other fields are not supposed to be accessed by user code.
793 /** \brief Pointer to vtable for this context. */
794 const br_block_ctr_class
*vtable
;
795 #ifndef BR_DOXYGEN_IGNORE
799 } br_aes_ct_ctr_keys
;
802 * \brief Class instance for AES CBC encryption (`aes_ct` implementation).
804 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable
;
807 * \brief Class instance for AES CBC decryption (`aes_ct` implementation).
809 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable
;
812 * \brief Class instance for AES CTR encryption and decryption
813 * (`aes_ct` implementation).
815 extern const br_block_ctr_class br_aes_ct_ctr_vtable
;
818 * \brief Context initialisation (key schedule) for AES CBC encryption
819 * (`aes_ct` implementation).
821 * \param ctx context to initialise.
822 * \param key secret key.
823 * \param len secret key length (in bytes).
825 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys
*ctx
,
826 const void *key
, size_t len
);
829 * \brief Context initialisation (key schedule) for AES CBC decryption
830 * (`aes_ct` implementation).
832 * \param ctx context to initialise.
833 * \param key secret key.
834 * \param len secret key length (in bytes).
836 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys
*ctx
,
837 const void *key
, size_t len
);
840 * \brief Context initialisation (key schedule) for AES CTR encryption
841 * and decryption (`aes_ct` implementation).
843 * \param ctx context to initialise.
844 * \param key secret key.
845 * \param len secret key length (in bytes).
847 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys
*ctx
,
848 const void *key
, size_t len
);
851 * \brief CBC encryption with AES (`aes_ct` implementation).
853 * \param ctx context (already initialised).
854 * \param iv IV (updated).
855 * \param data data to encrypt (updated).
856 * \param len data length (in bytes, MUST be multiple of 16).
858 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys
*ctx
, void *iv
,
859 void *data
, size_t len
);
862 * \brief CBC decryption with AES (`aes_ct` implementation).
864 * \param ctx context (already initialised).
865 * \param iv IV (updated).
866 * \param data data to decrypt (updated).
867 * \param len data length (in bytes, MUST be multiple of 16).
869 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys
*ctx
, void *iv
,
870 void *data
, size_t len
);
873 * \brief CTR encryption and decryption with AES (`aes_ct` implementation).
875 * \param ctx context (already initialised).
876 * \param iv IV (constant, 12 bytes).
877 * \param cc initial block counter value.
878 * \param data data to decrypt (updated).
879 * \param len data length (in bytes).
880 * \return new block counter value.
882 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys
*ctx
,
883 const void *iv
, uint32_t cc
, void *data
, size_t len
);
886 * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
887 * but uses 64-bit registers, making it about twice faster than 'aes_ct'
888 * on 64-bit platforms, while remaining constant-time and with a similar
889 * code size. (The doubling in performance is only for CBC decryption
890 * and CTR mode; CBC encryption is non-parallel and cannot benefit from
891 * the larger registers.)
894 /** \brief AES block size (16 bytes). */
895 #define br_aes_ct64_BLOCK_SIZE 16
898 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption).
900 * First field is a pointer to the vtable; it is set by the initialisation
901 * function. Other fields are not supposed to be accessed by user code.
904 /** \brief Pointer to vtable for this context. */
905 const br_block_cbcenc_class
*vtable
;
906 #ifndef BR_DOXYGEN_IGNORE
910 } br_aes_ct64_cbcenc_keys
;
913 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption).
915 * First field is a pointer to the vtable; it is set by the initialisation
916 * function. Other fields are not supposed to be accessed by user code.
919 /** \brief Pointer to vtable for this context. */
920 const br_block_cbcdec_class
*vtable
;
921 #ifndef BR_DOXYGEN_IGNORE
925 } br_aes_ct64_cbcdec_keys
;
928 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption
931 * First field is a pointer to the vtable; it is set by the initialisation
932 * function. Other fields are not supposed to be accessed by user code.
935 /** \brief Pointer to vtable for this context. */
936 const br_block_ctr_class
*vtable
;
937 #ifndef BR_DOXYGEN_IGNORE
941 } br_aes_ct64_ctr_keys
;
944 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation).
946 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable
;
949 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation).
951 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable
;
954 * \brief Class instance for AES CTR encryption and decryption
955 * (`aes_ct64` implementation).
957 extern const br_block_ctr_class br_aes_ct64_ctr_vtable
;
960 * \brief Context initialisation (key schedule) for AES CBC encryption
961 * (`aes_ct64` implementation).
963 * \param ctx context to initialise.
964 * \param key secret key.
965 * \param len secret key length (in bytes).
967 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys
*ctx
,
968 const void *key
, size_t len
);
971 * \brief Context initialisation (key schedule) for AES CBC decryption
972 * (`aes_ct64` implementation).
974 * \param ctx context to initialise.
975 * \param key secret key.
976 * \param len secret key length (in bytes).
978 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys
*ctx
,
979 const void *key
, size_t len
);
982 * \brief Context initialisation (key schedule) for AES CTR encryption
983 * and decryption (`aes_ct64` implementation).
985 * \param ctx context to initialise.
986 * \param key secret key.
987 * \param len secret key length (in bytes).
989 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys
*ctx
,
990 const void *key
, size_t len
);
993 * \brief CBC encryption with AES (`aes_ct64` implementation).
995 * \param ctx context (already initialised).
996 * \param iv IV (updated).
997 * \param data data to encrypt (updated).
998 * \param len data length (in bytes, MUST be multiple of 16).
1000 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys
*ctx
, void *iv
,
1001 void *data
, size_t len
);
1004 * \brief CBC decryption with AES (`aes_ct64` implementation).
1006 * \param ctx context (already initialised).
1007 * \param iv IV (updated).
1008 * \param data data to decrypt (updated).
1009 * \param len data length (in bytes, MUST be multiple of 16).
1011 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys
*ctx
, void *iv
,
1012 void *data
, size_t len
);
1015 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation).
1017 * \param ctx context (already initialised).
1018 * \param iv IV (constant, 12 bytes).
1019 * \param cc initial block counter value.
1020 * \param data data to decrypt (updated).
1021 * \param len data length (in bytes).
1022 * \return new block counter value.
1024 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys
*ctx
,
1025 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1028 * AES implementation using AES-NI opcodes (x86 platform).
1031 /** \brief AES block size (16 bytes). */
1032 #define br_aes_x86ni_BLOCK_SIZE 16
1035 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC encryption).
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_cbcenc_class
*vtable
;
1043 #ifndef BR_DOXYGEN_IGNORE
1045 unsigned char skni
[16 * 15];
1047 unsigned num_rounds
;
1049 } br_aes_x86ni_cbcenc_keys
;
1052 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC decryption).
1054 * First field is a pointer to the vtable; it is set by the initialisation
1055 * function. Other fields are not supposed to be accessed by user code.
1058 /** \brief Pointer to vtable for this context. */
1059 const br_block_cbcdec_class
*vtable
;
1060 #ifndef BR_DOXYGEN_IGNORE
1062 unsigned char skni
[16 * 15];
1064 unsigned num_rounds
;
1066 } br_aes_x86ni_cbcdec_keys
;
1069 * \brief Context for AES subkeys (`aes_x86ni` implementation, CTR encryption
1072 * First field is a pointer to the vtable; it is set by the initialisation
1073 * function. Other fields are not supposed to be accessed by user code.
1076 /** \brief Pointer to vtable for this context. */
1077 const br_block_ctr_class
*vtable
;
1078 #ifndef BR_DOXYGEN_IGNORE
1080 unsigned char skni
[16 * 15];
1082 unsigned num_rounds
;
1084 } br_aes_x86ni_ctr_keys
;
1087 * \brief Class instance for AES CBC encryption (`aes_x86ni` implementation).
1089 * Since this implementation might be omitted from the library, or the
1090 * AES opcode unavailable on the current CPU, a pointer to this class
1091 * instance should be obtained through `br_aes_x86ni_cbcenc_get_vtable()`.
1093 extern const br_block_cbcenc_class br_aes_x86ni_cbcenc_vtable
;
1096 * \brief Class instance for AES CBC decryption (`aes_x86ni` implementation).
1098 * Since this implementation might be omitted from the library, or the
1099 * AES opcode unavailable on the current CPU, a pointer to this class
1100 * instance should be obtained through `br_aes_x86ni_cbcdec_get_vtable()`.
1102 extern const br_block_cbcdec_class br_aes_x86ni_cbcdec_vtable
;
1105 * \brief Class instance for AES CTR encryption and decryption
1106 * (`aes_x86ni` implementation).
1108 * Since this implementation might be omitted from the library, or the
1109 * AES opcode unavailable on the current CPU, a pointer to this class
1110 * instance should be obtained through `br_aes_x86ni_ctr_get_vtable()`.
1112 extern const br_block_ctr_class br_aes_x86ni_ctr_vtable
;
1115 * \brief Context initialisation (key schedule) for AES CBC encryption
1116 * (`aes_x86ni` implementation).
1118 * \param ctx context to initialise.
1119 * \param key secret key.
1120 * \param len secret key length (in bytes).
1122 void br_aes_x86ni_cbcenc_init(br_aes_x86ni_cbcenc_keys
*ctx
,
1123 const void *key
, size_t len
);
1126 * \brief Context initialisation (key schedule) for AES CBC decryption
1127 * (`aes_x86ni` implementation).
1129 * \param ctx context to initialise.
1130 * \param key secret key.
1131 * \param len secret key length (in bytes).
1133 void br_aes_x86ni_cbcdec_init(br_aes_x86ni_cbcdec_keys
*ctx
,
1134 const void *key
, size_t len
);
1137 * \brief Context initialisation (key schedule) for AES CTR encryption
1138 * and decryption (`aes_x86ni` implementation).
1140 * \param ctx context to initialise.
1141 * \param key secret key.
1142 * \param len secret key length (in bytes).
1144 void br_aes_x86ni_ctr_init(br_aes_x86ni_ctr_keys
*ctx
,
1145 const void *key
, size_t len
);
1148 * \brief CBC encryption with AES (`aes_x86ni` implementation).
1150 * \param ctx context (already initialised).
1151 * \param iv IV (updated).
1152 * \param data data to encrypt (updated).
1153 * \param len data length (in bytes, MUST be multiple of 16).
1155 void br_aes_x86ni_cbcenc_run(const br_aes_x86ni_cbcenc_keys
*ctx
, void *iv
,
1156 void *data
, size_t len
);
1159 * \brief CBC decryption with AES (`aes_x86ni` implementation).
1161 * \param ctx context (already initialised).
1162 * \param iv IV (updated).
1163 * \param data data to decrypt (updated).
1164 * \param len data length (in bytes, MUST be multiple of 16).
1166 void br_aes_x86ni_cbcdec_run(const br_aes_x86ni_cbcdec_keys
*ctx
, void *iv
,
1167 void *data
, size_t len
);
1170 * \brief CTR encryption and decryption with AES (`aes_x86ni` implementation).
1172 * \param ctx context (already initialised).
1173 * \param iv IV (constant, 12 bytes).
1174 * \param cc initial block counter value.
1175 * \param data data to decrypt (updated).
1176 * \param len data length (in bytes).
1177 * \return new block counter value.
1179 uint32_t br_aes_x86ni_ctr_run(const br_aes_x86ni_ctr_keys
*ctx
,
1180 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1183 * \brief Obtain the `aes_x86ni` AES-CBC (encryption) implementation, if
1186 * This function returns a pointer to `br_aes_x86ni_cbcenc_vtable`, if
1187 * that implementation was compiled in the library _and_ the x86 AES
1188 * opcodes are available on the currently running CPU. If either of
1189 * these conditions is not met, then this function returns `NULL`.
1191 * \return the `aes_x868ni` AES-CBC (encryption) implementation, or `NULL`.
1193 const br_block_cbcenc_class
*br_aes_x86ni_cbcenc_get_vtable(void);
1196 * \brief Obtain the `aes_x86ni` AES-CBC (decryption) implementation, if
1199 * This function returns a pointer to `br_aes_x86ni_cbcdec_vtable`, if
1200 * that implementation was compiled in the library _and_ the x86 AES
1201 * opcodes are available on the currently running CPU. If either of
1202 * these conditions is not met, then this function returns `NULL`.
1204 * \return the `aes_x868ni` AES-CBC (decryption) implementation, or `NULL`.
1206 const br_block_cbcdec_class
*br_aes_x86ni_cbcdec_get_vtable(void);
1209 * \brief Obtain the `aes_x86ni` AES-CTR implementation, if available.
1211 * This function returns a pointer to `br_aes_x86ni_ctr_vtable`, if
1212 * that implementation was compiled in the library _and_ the x86 AES
1213 * opcodes are available on the currently running CPU. If either of
1214 * these conditions is not met, then this function returns `NULL`.
1216 * \return the `aes_x868ni` AES-CTR implementation, or `NULL`.
1218 const br_block_ctr_class
*br_aes_x86ni_ctr_get_vtable(void);
1221 * AES implementation using POWER8 opcodes.
1224 /** \brief AES block size (16 bytes). */
1225 #define br_aes_pwr8_BLOCK_SIZE 16
1228 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC encryption).
1230 * First field is a pointer to the vtable; it is set by the initialisation
1231 * function. Other fields are not supposed to be accessed by user code.
1234 /** \brief Pointer to vtable for this context. */
1235 const br_block_cbcenc_class
*vtable
;
1236 #ifndef BR_DOXYGEN_IGNORE
1238 unsigned char skni
[16 * 15];
1240 unsigned num_rounds
;
1242 } br_aes_pwr8_cbcenc_keys
;
1245 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC decryption).
1247 * First field is a pointer to the vtable; it is set by the initialisation
1248 * function. Other fields are not supposed to be accessed by user code.
1251 /** \brief Pointer to vtable for this context. */
1252 const br_block_cbcdec_class
*vtable
;
1253 #ifndef BR_DOXYGEN_IGNORE
1255 unsigned char skni
[16 * 15];
1257 unsigned num_rounds
;
1259 } br_aes_pwr8_cbcdec_keys
;
1262 * \brief Context for AES subkeys (`aes_pwr8` implementation, CTR encryption
1265 * First field is a pointer to the vtable; it is set by the initialisation
1266 * function. Other fields are not supposed to be accessed by user code.
1269 /** \brief Pointer to vtable for this context. */
1270 const br_block_ctr_class
*vtable
;
1271 #ifndef BR_DOXYGEN_IGNORE
1273 unsigned char skni
[16 * 15];
1275 unsigned num_rounds
;
1277 } br_aes_pwr8_ctr_keys
;
1280 * \brief Class instance for AES CBC encryption (`aes_pwr8` implementation).
1282 * Since this implementation might be omitted from the library, or the
1283 * AES opcode unavailable on the current CPU, a pointer to this class
1284 * instance should be obtained through `br_aes_pwr8_cbcenc_get_vtable()`.
1286 extern const br_block_cbcenc_class br_aes_pwr8_cbcenc_vtable
;
1289 * \brief Class instance for AES CBC decryption (`aes_pwr8` implementation).
1291 * Since this implementation might be omitted from the library, or the
1292 * AES opcode unavailable on the current CPU, a pointer to this class
1293 * instance should be obtained through `br_aes_pwr8_cbcdec_get_vtable()`.
1295 extern const br_block_cbcdec_class br_aes_pwr8_cbcdec_vtable
;
1298 * \brief Class instance for AES CTR encryption and decryption
1299 * (`aes_pwr8` implementation).
1301 * Since this implementation might be omitted from the library, or the
1302 * AES opcode unavailable on the current CPU, a pointer to this class
1303 * instance should be obtained through `br_aes_pwr8_ctr_get_vtable()`.
1305 extern const br_block_ctr_class br_aes_pwr8_ctr_vtable
;
1308 * \brief Context initialisation (key schedule) for AES CBC encryption
1309 * (`aes_pwr8` implementation).
1311 * \param ctx context to initialise.
1312 * \param key secret key.
1313 * \param len secret key length (in bytes).
1315 void br_aes_pwr8_cbcenc_init(br_aes_pwr8_cbcenc_keys
*ctx
,
1316 const void *key
, size_t len
);
1319 * \brief Context initialisation (key schedule) for AES CBC decryption
1320 * (`aes_pwr8` implementation).
1322 * \param ctx context to initialise.
1323 * \param key secret key.
1324 * \param len secret key length (in bytes).
1326 void br_aes_pwr8_cbcdec_init(br_aes_pwr8_cbcdec_keys
*ctx
,
1327 const void *key
, size_t len
);
1330 * \brief Context initialisation (key schedule) for AES CTR encryption
1331 * and decryption (`aes_pwr8` implementation).
1333 * \param ctx context to initialise.
1334 * \param key secret key.
1335 * \param len secret key length (in bytes).
1337 void br_aes_pwr8_ctr_init(br_aes_pwr8_ctr_keys
*ctx
,
1338 const void *key
, size_t len
);
1341 * \brief CBC encryption with AES (`aes_pwr8` implementation).
1343 * \param ctx context (already initialised).
1344 * \param iv IV (updated).
1345 * \param data data to encrypt (updated).
1346 * \param len data length (in bytes, MUST be multiple of 16).
1348 void br_aes_pwr8_cbcenc_run(const br_aes_pwr8_cbcenc_keys
*ctx
, void *iv
,
1349 void *data
, size_t len
);
1352 * \brief CBC decryption with AES (`aes_pwr8` implementation).
1354 * \param ctx context (already initialised).
1355 * \param iv IV (updated).
1356 * \param data data to decrypt (updated).
1357 * \param len data length (in bytes, MUST be multiple of 16).
1359 void br_aes_pwr8_cbcdec_run(const br_aes_pwr8_cbcdec_keys
*ctx
, void *iv
,
1360 void *data
, size_t len
);
1363 * \brief CTR encryption and decryption with AES (`aes_pwr8` implementation).
1365 * \param ctx context (already initialised).
1366 * \param iv IV (constant, 12 bytes).
1367 * \param cc initial block counter value.
1368 * \param data data to decrypt (updated).
1369 * \param len data length (in bytes).
1370 * \return new block counter value.
1372 uint32_t br_aes_pwr8_ctr_run(const br_aes_pwr8_ctr_keys
*ctx
,
1373 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1376 * \brief Obtain the `aes_pwr8` AES-CBC (encryption) implementation, if
1379 * This function returns a pointer to `br_aes_pwr8_cbcenc_vtable`, if
1380 * that implementation was compiled in the library _and_ the POWER8
1381 * crypto opcodes are available on the currently running CPU. If either
1382 * of these conditions is not met, then this function returns `NULL`.
1384 * \return the `aes_pwr8` AES-CBC (encryption) implementation, or `NULL`.
1386 const br_block_cbcenc_class
*br_aes_pwr8_cbcenc_get_vtable(void);
1389 * \brief Obtain the `aes_pwr8` AES-CBC (decryption) implementation, if
1392 * This function returns a pointer to `br_aes_pwr8_cbcdec_vtable`, if
1393 * that implementation was compiled in the library _and_ the POWER8
1394 * crypto opcodes are available on the currently running CPU. If either
1395 * of these conditions is not met, then this function returns `NULL`.
1397 * \return the `aes_pwr8` AES-CBC (decryption) implementation, or `NULL`.
1399 const br_block_cbcdec_class
*br_aes_pwr8_cbcdec_get_vtable(void);
1402 * \brief Obtain the `aes_pwr8` AES-CTR implementation, if available.
1404 * This function returns a pointer to `br_aes_pwr8_ctr_vtable`, if that
1405 * implementation was compiled in the library _and_ the POWER8 crypto
1406 * opcodes are available on the currently running CPU. If either of
1407 * these conditions is not met, then this function returns `NULL`.
1409 * \return the `aes_pwr8` AES-CTR implementation, or `NULL`.
1411 const br_block_ctr_class
*br_aes_pwr8_ctr_get_vtable(void);
1414 * \brief Aggregate structure large enough to be used as context for
1415 * subkeys (CBC encryption) for all AES implementations.
1418 const br_block_cbcenc_class
*vtable
;
1419 br_aes_big_cbcenc_keys c_big
;
1420 br_aes_small_cbcenc_keys c_small
;
1421 br_aes_ct_cbcenc_keys c_ct
;
1422 br_aes_ct64_cbcenc_keys c_ct64
;
1423 br_aes_x86ni_cbcenc_keys c_x86ni
;
1424 br_aes_pwr8_cbcenc_keys c_pwr8
;
1425 } br_aes_gen_cbcenc_keys
;
1428 * \brief Aggregate structure large enough to be used as context for
1429 * subkeys (CBC decryption) for all AES implementations.
1432 const br_block_cbcdec_class
*vtable
;
1433 br_aes_big_cbcdec_keys c_big
;
1434 br_aes_small_cbcdec_keys c_small
;
1435 br_aes_ct_cbcdec_keys c_ct
;
1436 br_aes_ct64_cbcdec_keys c_ct64
;
1437 br_aes_x86ni_cbcdec_keys c_x86ni
;
1438 br_aes_pwr8_cbcdec_keys c_pwr8
;
1439 } br_aes_gen_cbcdec_keys
;
1442 * \brief Aggregate structure large enough to be used as context for
1443 * subkeys (CTR encryption and decryption) for all AES implementations.
1446 const br_block_ctr_class
*vtable
;
1447 br_aes_big_ctr_keys c_big
;
1448 br_aes_small_ctr_keys c_small
;
1449 br_aes_ct_ctr_keys c_ct
;
1450 br_aes_ct64_ctr_keys c_ct64
;
1451 br_aes_x86ni_ctr_keys c_x86ni
;
1452 br_aes_pwr8_ctr_keys c_pwr8
;
1453 } br_aes_gen_ctr_keys
;
1456 * Traditional, table-based implementation for DES/3DES. Since tables are
1457 * used, cache-timing attacks are conceptually possible.
1460 /** \brief DES/3DES block size (8 bytes). */
1461 #define br_des_tab_BLOCK_SIZE 8
1464 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption).
1466 * First field is a pointer to the vtable; it is set by the initialisation
1467 * function. Other fields are not supposed to be accessed by user code.
1470 /** \brief Pointer to vtable for this context. */
1471 const br_block_cbcenc_class
*vtable
;
1472 #ifndef BR_DOXYGEN_IGNORE
1474 unsigned num_rounds
;
1476 } br_des_tab_cbcenc_keys
;
1479 * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption).
1481 * First field is a pointer to the vtable; it is set by the initialisation
1482 * function. Other fields are not supposed to be accessed by user code.
1485 /** \brief Pointer to vtable for this context. */
1486 const br_block_cbcdec_class
*vtable
;
1487 #ifndef BR_DOXYGEN_IGNORE
1489 unsigned num_rounds
;
1491 } br_des_tab_cbcdec_keys
;
1494 * \brief Class instance for DES CBC encryption (`des_tab` implementation).
1496 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable
;
1499 * \brief Class instance for DES CBC decryption (`des_tab` implementation).
1501 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable
;
1504 * \brief Context initialisation (key schedule) for DES CBC encryption
1505 * (`des_tab` implementation).
1507 * \param ctx context to initialise.
1508 * \param key secret key.
1509 * \param len secret key length (in bytes).
1511 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys
*ctx
,
1512 const void *key
, size_t len
);
1515 * \brief Context initialisation (key schedule) for DES CBC decryption
1516 * (`des_tab` implementation).
1518 * \param ctx context to initialise.
1519 * \param key secret key.
1520 * \param len secret key length (in bytes).
1522 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys
*ctx
,
1523 const void *key
, size_t len
);
1526 * \brief CBC encryption with DES (`des_tab` implementation).
1528 * \param ctx context (already initialised).
1529 * \param iv IV (updated).
1530 * \param data data to encrypt (updated).
1531 * \param len data length (in bytes, MUST be multiple of 8).
1533 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys
*ctx
, void *iv
,
1534 void *data
, size_t len
);
1537 * \brief CBC decryption with DES (`des_tab` implementation).
1539 * \param ctx context (already initialised).
1540 * \param iv IV (updated).
1541 * \param data data to decrypt (updated).
1542 * \param len data length (in bytes, MUST be multiple of 8).
1544 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys
*ctx
, void *iv
,
1545 void *data
, size_t len
);
1548 * Constant-time implementation for DES/3DES. It is substantially slower
1549 * (by a factor of about 4x), but also immune to cache-timing attacks.
1552 /** \brief DES/3DES block size (8 bytes). */
1553 #define br_des_ct_BLOCK_SIZE 8
1556 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption).
1558 * First field is a pointer to the vtable; it is set by the initialisation
1559 * function. Other fields are not supposed to be accessed by user code.
1562 /** \brief Pointer to vtable for this context. */
1563 const br_block_cbcenc_class
*vtable
;
1564 #ifndef BR_DOXYGEN_IGNORE
1566 unsigned num_rounds
;
1568 } br_des_ct_cbcenc_keys
;
1571 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption).
1573 * First field is a pointer to the vtable; it is set by the initialisation
1574 * function. Other fields are not supposed to be accessed by user code.
1577 /** \brief Pointer to vtable for this context. */
1578 const br_block_cbcdec_class
*vtable
;
1579 #ifndef BR_DOXYGEN_IGNORE
1581 unsigned num_rounds
;
1583 } br_des_ct_cbcdec_keys
;
1586 * \brief Class instance for DES CBC encryption (`des_ct` implementation).
1588 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable
;
1591 * \brief Class instance for DES CBC decryption (`des_ct` implementation).
1593 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable
;
1596 * \brief Context initialisation (key schedule) for DES CBC encryption
1597 * (`des_ct` implementation).
1599 * \param ctx context to initialise.
1600 * \param key secret key.
1601 * \param len secret key length (in bytes).
1603 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys
*ctx
,
1604 const void *key
, size_t len
);
1607 * \brief Context initialisation (key schedule) for DES CBC decryption
1608 * (`des_ct` implementation).
1610 * \param ctx context to initialise.
1611 * \param key secret key.
1612 * \param len secret key length (in bytes).
1614 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys
*ctx
,
1615 const void *key
, size_t len
);
1618 * \brief CBC encryption with DES (`des_ct` implementation).
1620 * \param ctx context (already initialised).
1621 * \param iv IV (updated).
1622 * \param data data to encrypt (updated).
1623 * \param len data length (in bytes, MUST be multiple of 8).
1625 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys
*ctx
, void *iv
,
1626 void *data
, size_t len
);
1629 * \brief CBC decryption with DES (`des_ct` implementation).
1631 * \param ctx context (already initialised).
1632 * \param iv IV (updated).
1633 * \param data data to decrypt (updated).
1634 * \param len data length (in bytes, MUST be multiple of 8).
1636 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys
*ctx
, void *iv
,
1637 void *data
, size_t len
);
1640 * These structures are large enough to accommodate subkeys for all
1641 * DES/3DES implementations.
1645 * \brief Aggregate structure large enough to be used as context for
1646 * subkeys (CBC encryption) for all DES implementations.
1649 const br_block_cbcenc_class
*vtable
;
1650 br_des_tab_cbcenc_keys tab
;
1651 br_des_ct_cbcenc_keys ct
;
1652 } br_des_gen_cbcenc_keys
;
1655 * \brief Aggregate structure large enough to be used as context for
1656 * subkeys (CBC decryption) for all DES implementations.
1659 const br_block_cbcdec_class
*vtable
;
1660 br_des_tab_cbcdec_keys c_tab
;
1661 br_des_ct_cbcdec_keys c_ct
;
1662 } br_des_gen_cbcdec_keys
;
1665 * \brief Type for a ChaCha20 implementation.
1667 * An implementation follows the description in RFC 7539:
1669 * - Key is 256 bits (`key` points to exactly 32 bytes).
1671 * - IV is 96 bits (`iv` points to exactly 12 bytes).
1673 * - Block counter is over 32 bits and starts at value `cc`; the
1674 * resulting value is returned.
1676 * Data (pointed to by `data`, of length `len`) is encrypted/decrypted
1677 * in place. If `len` is not a multiple of 64, then the excess bytes from
1678 * the last block processing are dropped (therefore, "chunked" processing
1679 * works only as long as each non-final chunk has a length multiple of 64).
1681 * \param key secret key (32 bytes).
1682 * \param iv IV (12 bytes).
1683 * \param cc initial counter value.
1684 * \param data data to encrypt or decrypt.
1685 * \param len data length (in bytes).
1687 typedef uint32_t (*br_chacha20_run
)(const void *key
,
1688 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1691 * \brief ChaCha20 implementation (straightforward C code, constant-time).
1693 * \see br_chacha20_run
1695 * \param key secret key (32 bytes).
1696 * \param iv IV (12 bytes).
1697 * \param cc initial counter value.
1698 * \param data data to encrypt or decrypt.
1699 * \param len data length (in bytes).
1701 uint32_t br_chacha20_ct_run(const void *key
,
1702 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1705 * \brief ChaCha20 implementation (SSE2 code, constant-time).
1707 * This implementation is available only on x86 platforms, depending on
1708 * compiler support. Moreover, in 32-bit mode, it might not actually run,
1709 * if the underlying hardware does not implement the SSE2 opcode (in
1710 * 64-bit mode, SSE2 is part of the ABI, so if the code could be compiled
1711 * at all, then it can run). Use `br_chacha20_sse2_get()` to safely obtain
1712 * a pointer to that function.
1714 * \see br_chacha20_run
1716 * \param key secret key (32 bytes).
1717 * \param iv IV (12 bytes).
1718 * \param cc initial counter value.
1719 * \param data data to encrypt or decrypt.
1720 * \param len data length (in bytes).
1722 uint32_t br_chacha20_sse2_run(const void *key
,
1723 const void *iv
, uint32_t cc
, void *data
, size_t len
);
1726 * \brief Obtain the `sse2` ChaCha20 implementation, if available.
1728 * This function returns a pointer to `br_chacha20_sse2_run`, if
1729 * that implementation was compiled in the library _and_ the SSE2
1730 * opcodes are available on the currently running CPU. If either of
1731 * these conditions is not met, then this function returns `0`.
1733 * \return the `sse2` ChaCha20 implementation, or `0`.
1735 br_chacha20_run
br_chacha20_sse2_get(void);
1738 * \brief Type for a ChaCha20+Poly1305 AEAD implementation.
1740 * The provided data is encrypted or decrypted with ChaCha20. The
1741 * authentication tag is computed on the concatenation of the
1742 * additional data and the ciphertext, with the padding and lengths
1743 * as described in RFC 7539 (section 2.8).
1745 * After decryption, the caller is responsible for checking that the
1746 * computed tag matches the expected value.
1748 * \param key secret key (32 bytes).
1749 * \param iv nonce (12 bytes).
1750 * \param data data to encrypt or decrypt.
1751 * \param len data length (in bytes).
1752 * \param aad additional authenticated data.
1753 * \param aad_len length of additional authenticated data (in bytes).
1754 * \param tag output buffer for the authentication tag.
1755 * \param ichacha implementation of ChaCha20.
1756 * \param encrypt non-zero for encryption, zero for decryption.
1758 typedef void (*br_poly1305_run
)(const void *key
, const void *iv
,
1759 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1760 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1763 * \brief ChaCha20+Poly1305 AEAD implementation (mixed 32-bit multiplications).
1765 * \see br_poly1305_run
1767 * \param key secret key (32 bytes).
1768 * \param iv nonce (12 bytes).
1769 * \param data data to encrypt or decrypt.
1770 * \param len data length (in bytes).
1771 * \param aad additional authenticated data.
1772 * \param aad_len length of additional authenticated data (in bytes).
1773 * \param tag output buffer for the authentication tag.
1774 * \param ichacha implementation of ChaCha20.
1775 * \param encrypt non-zero for encryption, zero for decryption.
1777 void br_poly1305_ctmul_run(const void *key
, const void *iv
,
1778 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1779 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1782 * \brief ChaCha20+Poly1305 AEAD implementation (pure 32-bit multiplications).
1784 * \see br_poly1305_run
1786 * \param key secret key (32 bytes).
1787 * \param iv nonce (12 bytes).
1788 * \param data data to encrypt or decrypt.
1789 * \param len data length (in bytes).
1790 * \param aad additional authenticated data.
1791 * \param aad_len length of additional authenticated data (in bytes).
1792 * \param tag output buffer for the authentication tag.
1793 * \param ichacha implementation of ChaCha20.
1794 * \param encrypt non-zero for encryption, zero for decryption.
1796 void br_poly1305_ctmul32_run(const void *key
, const void *iv
,
1797 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1798 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1801 * \brief ChaCha20+Poly1305 AEAD implementation (i15).
1803 * This implementation relies on the generic big integer code "i15"
1804 * (which uses pure 32-bit multiplications). As such, it may save a
1805 * little code footprint in a context where "i15" is already included
1806 * (e.g. for elliptic curves or for RSA); however, it is also
1807 * substantially slower than the ctmul and ctmul32 implementations.
1809 * \see br_poly1305_run
1811 * \param key secret key (32 bytes).
1812 * \param iv nonce (12 bytes).
1813 * \param data data to encrypt or decrypt.
1814 * \param len data length (in bytes).
1815 * \param aad additional authenticated data.
1816 * \param aad_len length of additional authenticated data (in bytes).
1817 * \param tag output buffer for the authentication tag.
1818 * \param ichacha implementation of ChaCha20.
1819 * \param encrypt non-zero for encryption, zero for decryption.
1821 void br_poly1305_i15_run(const void *key
, const void *iv
,
1822 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1823 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1826 * \brief ChaCha20+Poly1305 AEAD implementation (ctmulq).
1828 * This implementation uses 64-bit multiplications (result over 128 bits).
1829 * It is available only on platforms that offer such a primitive (in
1830 * practice, 64-bit architectures). Use `br_poly1305_ctmulq_get()` to
1831 * dynamically obtain a pointer to that function, or 0 if not supported.
1833 * \see br_poly1305_run
1835 * \param key secret key (32 bytes).
1836 * \param iv nonce (12 bytes).
1837 * \param data data to encrypt or decrypt.
1838 * \param len data length (in bytes).
1839 * \param aad additional authenticated data.
1840 * \param aad_len length of additional authenticated data (in bytes).
1841 * \param tag output buffer for the authentication tag.
1842 * \param ichacha implementation of ChaCha20.
1843 * \param encrypt non-zero for encryption, zero for decryption.
1845 void br_poly1305_ctmulq_run(const void *key
, const void *iv
,
1846 void *data
, size_t len
, const void *aad
, size_t aad_len
,
1847 void *tag
, br_chacha20_run ichacha
, int encrypt
);
1850 * \brief Get the ChaCha20+Poly1305 "ctmulq" implementation, if available.
1852 * This function returns a pointer to the `br_poly1305_ctmulq_run()`
1853 * function if supported on the current platform; otherwise, it returns 0.
1855 * \return the ctmulq ChaCha20+Poly1305 implementation, or 0.
1857 br_poly1305_run
br_poly1305_ctmulq_get(void);