New AES and GHASH implementations using POWER8 crypto opcodes.
[BearSSL] / inc / bearssl_block.h
1 /*
2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
3 *
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:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
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
22 * SOFTWARE.
23 */
24
25 #ifndef BR_BEARSSL_BLOCK_H__
26 #define BR_BEARSSL_BLOCK_H__
27
28 #include <stddef.h>
29 #include <stdint.h>
30
31 /** \file bearssl_block.h
32 *
33 * # Block Ciphers and Symmetric Ciphers
34 *
35 * This file documents the API for block ciphers and other symmetric
36 * ciphers.
37 *
38 *
39 * ## Procedural API
40 *
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.
45 *
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.
50 *
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).
53 *
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:
58 *
59 * - `br_xxx_BLOCK_SIZE`
60 *
61 * A macro that evaluates to the block size (in bytes) of the
62 * cipher. For all implemented block ciphers, this value is a
63 * power of two.
64 *
65 * - `br_xxx_cbcenc_keys`
66 *
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.
71 *
72 * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
73 *
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
77 * the `vtable` field.
78 *
79 * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)`
80 *
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.
86 *
87 * - `br_xxx_cbcdec_keys`
88 *
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.
93 *
94 * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)`
95 *
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
99 * the `vtable` field.
100 *
101 * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)`
102 *
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.
108 *
109 * - `br_xxx_ctr_keys`
110 *
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.
115 *
116 * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)`
117 *
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.
122 *
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`)
124 *
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.
134 *
135 *
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
140 * overflow).
141 *
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.
145 *
146 *
147 * ## Object-Oriented API
148 *
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
152 * following:
153 *
154 * - `context_size`
155 *
156 * The size (in bytes) of the context structure for subkeys.
157 *
158 * - `block_size`
159 *
160 * The cipher block size (in bytes).
161 *
162 * - `log_block_size`
163 *
164 * The base-2 logarithm of cipher block size (e.g. 4 for blocks
165 * of 16 bytes).
166 *
167 * - `init`
168 *
169 * Pointer to the key expansion function.
170 *
171 * - `run`
172 *
173 * Pointer to the encryption/decryption function.
174 *
175 *
176 * For block cipher "`xxx`", static, constant instances of these
177 * structures are defined, under the names:
178 *
179 * - `br_xxx_cbcenc_vtable`
180 * - `br_xxx_cbcdec_vtable`
181 * - `br_xxx_ctr_vtable`
182 *
183 *
184 * ## Implemented Block Ciphers
185 *
186 * Provided implementations are:
187 *
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 |
198 *
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.
203 *
204 * `aes_big` is a "classical" AES implementation, using tables. It
205 * is fast but not constant-time, since it makes data-dependent array
206 * accesses.
207 *
208 * `aes_small` is an AES implementation optimized for code size. It
209 * is substantially slower than `aes_big`; it is not constant-time
210 * either.
211 *
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
219 * hardware opcodes).
220 *
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).
227 *
228 * `aes_x86ni` exists only on x86 architectures (32-bit and 64-bit). It
229 * uses the AES-NI opcodes when available.
230 *
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.
234 *
235 * `des_tab` is a classic, table-based implementation of DES/3DES. It
236 * is not constant-time.
237 *
238 * `des_ct` is an constant-time implementation of DES/3DES. It is
239 * substantially slower than `des_tab`.
240 *
241 * ## ChaCha20 and Poly1305
242 *
243 * ChaCha20 is a stream cipher. Poly1305 is a MAC algorithm. They
244 * are described in [RFC 7539](https://tools.ietf.org/html/rfc7539).
245 *
246 * Two function pointer types are defined:
247 *
248 * - `br_chacha20_run` describes a function that implements ChaCha20
249 * only.
250 *
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).
254 *
255 * `chacha20_ct` is a straightforward implementation of ChaCha20 in
256 * plain C; it is constant-time, small, and reasonably fast.
257 *
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).
261 */
262
263 /**
264 * \brief Class type for CBC encryption implementations.
265 *
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.
268 */
269 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class;
270 struct br_block_cbcenc_class_ {
271 /**
272 * \brief Size (in bytes) of the context structure appropriate
273 * for containing subkeys.
274 */
275 size_t context_size;
276
277 /**
278 * \brief Size of individual blocks (in bytes).
279 */
280 unsigned block_size;
281
282 /**
283 * \brief Base-2 logarithm of the size of individual blocks,
284 * expressed in bytes.
285 */
286 unsigned log_block_size;
287
288 /**
289 * \brief Initialisation function.
290 *
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.
294 *
295 * \param ctx context structure to initialise.
296 * \param key secret key.
297 * \param key_len key length (in bytes).
298 */
299 void (*init)(const br_block_cbcenc_class **ctx,
300 const void *key, size_t key_len);
301
302 /**
303 * \brief Run the CBC encryption.
304 *
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.
309 *
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).
314 */
315 void (*run)(const br_block_cbcenc_class *const *ctx,
316 void *iv, void *data, size_t len);
317 };
318
319 /**
320 * \brief Class type for CBC decryption implementations.
321 *
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.
324 */
325 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class;
326 struct br_block_cbcdec_class_ {
327 /**
328 * \brief Size (in bytes) of the context structure appropriate
329 * for containing subkeys.
330 */
331 size_t context_size;
332
333 /**
334 * \brief Size of individual blocks (in bytes).
335 */
336 unsigned block_size;
337
338 /**
339 * \brief Base-2 logarithm of the size of individual blocks,
340 * expressed in bytes.
341 */
342 unsigned log_block_size;
343
344 /**
345 * \brief Initialisation function.
346 *
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.
350 *
351 * \param ctx context structure to initialise.
352 * \param key secret key.
353 * \param key_len key length (in bytes).
354 */
355 void (*init)(const br_block_cbcdec_class **ctx,
356 const void *key, size_t key_len);
357
358 /**
359 * \brief Run the CBC decryption.
360 *
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.
365 *
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).
370 */
371 void (*run)(const br_block_cbcdec_class *const *ctx,
372 void *iv, void *data, size_t len);
373 };
374
375 /**
376 * \brief Class type for CTR encryption/decryption implementations.
377 *
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
380 * decrypting data.
381 */
382 typedef struct br_block_ctr_class_ br_block_ctr_class;
383 struct br_block_ctr_class_ {
384 /**
385 * \brief Size (in bytes) of the context structure appropriate
386 * for containing subkeys.
387 */
388 size_t context_size;
389
390 /**
391 * \brief Size of individual blocks (in bytes).
392 */
393 unsigned block_size;
394
395 /**
396 * \brief Base-2 logarithm of the size of individual blocks,
397 * expressed in bytes.
398 */
399 unsigned log_block_size;
400
401 /**
402 * \brief Initialisation function.
403 *
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.
407 *
408 * \param ctx context structure to initialise.
409 * \param key secret key.
410 * \param key_len key length (in bytes).
411 */
412 void (*init)(const br_block_ctr_class **ctx,
413 const void *key, size_t key_len);
414
415 /**
416 * \brief Run the CTR encryption or decryption.
417 *
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.
423 *
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.
428 *
429 * The resulting counter value is returned.
430 *
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.
437 */
438 uint32_t (*run)(const br_block_ctr_class *const *ctx,
439 const void *iv, uint32_t cc, void *data, size_t len);
440 };
441
442 /*
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.
448 */
449
450 /** \brief AES block size (16 bytes). */
451 #define br_aes_big_BLOCK_SIZE 16
452
453 /**
454 * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption).
455 *
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.
458 */
459 typedef struct {
460 /** \brief Pointer to vtable for this context. */
461 const br_block_cbcenc_class *vtable;
462 #ifndef BR_DOXYGEN_IGNORE
463 uint32_t skey[60];
464 unsigned num_rounds;
465 #endif
466 } br_aes_big_cbcenc_keys;
467
468 /**
469 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption).
470 *
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.
473 */
474 typedef struct {
475 /** \brief Pointer to vtable for this context. */
476 const br_block_cbcdec_class *vtable;
477 #ifndef BR_DOXYGEN_IGNORE
478 uint32_t skey[60];
479 unsigned num_rounds;
480 #endif
481 } br_aes_big_cbcdec_keys;
482
483 /**
484 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption
485 * and decryption).
486 *
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.
489 */
490 typedef struct {
491 /** \brief Pointer to vtable for this context. */
492 const br_block_ctr_class *vtable;
493 #ifndef BR_DOXYGEN_IGNORE
494 uint32_t skey[60];
495 unsigned num_rounds;
496 #endif
497 } br_aes_big_ctr_keys;
498
499 /**
500 * \brief Class instance for AES CBC encryption (`aes_big` implementation).
501 */
502 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable;
503
504 /**
505 * \brief Class instance for AES CBC decryption (`aes_big` implementation).
506 */
507 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable;
508
509 /**
510 * \brief Class instance for AES CTR encryption and decryption
511 * (`aes_big` implementation).
512 */
513 extern const br_block_ctr_class br_aes_big_ctr_vtable;
514
515 /**
516 * \brief Context initialisation (key schedule) for AES CBC encryption
517 * (`aes_big` implementation).
518 *
519 * \param ctx context to initialise.
520 * \param key secret key.
521 * \param len secret key length (in bytes).
522 */
523 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys *ctx,
524 const void *key, size_t len);
525
526 /**
527 * \brief Context initialisation (key schedule) for AES CBC decryption
528 * (`aes_big` implementation).
529 *
530 * \param ctx context to initialise.
531 * \param key secret key.
532 * \param len secret key length (in bytes).
533 */
534 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys *ctx,
535 const void *key, size_t len);
536
537 /**
538 * \brief Context initialisation (key schedule) for AES CTR encryption
539 * and decryption (`aes_big` implementation).
540 *
541 * \param ctx context to initialise.
542 * \param key secret key.
543 * \param len secret key length (in bytes).
544 */
545 void br_aes_big_ctr_init(br_aes_big_ctr_keys *ctx,
546 const void *key, size_t len);
547
548 /**
549 * \brief CBC encryption with AES (`aes_big` implementation).
550 *
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).
555 */
556 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys *ctx, void *iv,
557 void *data, size_t len);
558
559 /**
560 * \brief CBC decryption with AES (`aes_big` implementation).
561 *
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).
566 */
567 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys *ctx, void *iv,
568 void *data, size_t len);
569
570 /**
571 * \brief CTR encryption and decryption with AES (`aes_big` implementation).
572 *
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.
579 */
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);
582
583 /*
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.
589 */
590
591 /** \brief AES block size (16 bytes). */
592 #define br_aes_small_BLOCK_SIZE 16
593
594 /**
595 * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption).
596 *
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.
599 */
600 typedef struct {
601 /** \brief Pointer to vtable for this context. */
602 const br_block_cbcenc_class *vtable;
603 #ifndef BR_DOXYGEN_IGNORE
604 uint32_t skey[60];
605 unsigned num_rounds;
606 #endif
607 } br_aes_small_cbcenc_keys;
608
609 /**
610 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption).
611 *
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.
614 */
615 typedef struct {
616 /** \brief Pointer to vtable for this context. */
617 const br_block_cbcdec_class *vtable;
618 #ifndef BR_DOXYGEN_IGNORE
619 uint32_t skey[60];
620 unsigned num_rounds;
621 #endif
622 } br_aes_small_cbcdec_keys;
623
624 /**
625 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption
626 * and decryption).
627 *
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.
630 */
631 typedef struct {
632 /** \brief Pointer to vtable for this context. */
633 const br_block_ctr_class *vtable;
634 #ifndef BR_DOXYGEN_IGNORE
635 uint32_t skey[60];
636 unsigned num_rounds;
637 #endif
638 } br_aes_small_ctr_keys;
639
640 /**
641 * \brief Class instance for AES CBC encryption (`aes_small` implementation).
642 */
643 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable;
644
645 /**
646 * \brief Class instance for AES CBC decryption (`aes_small` implementation).
647 */
648 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable;
649
650 /**
651 * \brief Class instance for AES CTR encryption and decryption
652 * (`aes_small` implementation).
653 */
654 extern const br_block_ctr_class br_aes_small_ctr_vtable;
655
656 /**
657 * \brief Context initialisation (key schedule) for AES CBC encryption
658 * (`aes_small` implementation).
659 *
660 * \param ctx context to initialise.
661 * \param key secret key.
662 * \param len secret key length (in bytes).
663 */
664 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys *ctx,
665 const void *key, size_t len);
666
667 /**
668 * \brief Context initialisation (key schedule) for AES CBC decryption
669 * (`aes_small` implementation).
670 *
671 * \param ctx context to initialise.
672 * \param key secret key.
673 * \param len secret key length (in bytes).
674 */
675 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys *ctx,
676 const void *key, size_t len);
677
678 /**
679 * \brief Context initialisation (key schedule) for AES CTR encryption
680 * and decryption (`aes_small` implementation).
681 *
682 * \param ctx context to initialise.
683 * \param key secret key.
684 * \param len secret key length (in bytes).
685 */
686 void br_aes_small_ctr_init(br_aes_small_ctr_keys *ctx,
687 const void *key, size_t len);
688
689 /**
690 * \brief CBC encryption with AES (`aes_small` implementation).
691 *
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).
696 */
697 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys *ctx, void *iv,
698 void *data, size_t len);
699
700 /**
701 * \brief CBC decryption with AES (`aes_small` implementation).
702 *
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).
707 */
708 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys *ctx, void *iv,
709 void *data, size_t len);
710
711 /**
712 * \brief CTR encryption and decryption with AES (`aes_small` implementation).
713 *
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.
720 */
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);
723
724 /*
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.
729 */
730
731 /** \brief AES block size (16 bytes). */
732 #define br_aes_ct_BLOCK_SIZE 16
733
734 /**
735 * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption).
736 *
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.
739 */
740 typedef struct {
741 /** \brief Pointer to vtable for this context. */
742 const br_block_cbcenc_class *vtable;
743 #ifndef BR_DOXYGEN_IGNORE
744 uint32_t skey[60];
745 unsigned num_rounds;
746 #endif
747 } br_aes_ct_cbcenc_keys;
748
749 /**
750 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption).
751 *
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.
754 */
755 typedef struct {
756 /** \brief Pointer to vtable for this context. */
757 const br_block_cbcdec_class *vtable;
758 #ifndef BR_DOXYGEN_IGNORE
759 uint32_t skey[60];
760 unsigned num_rounds;
761 #endif
762 } br_aes_ct_cbcdec_keys;
763
764 /**
765 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption
766 * and decryption).
767 *
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.
770 */
771 typedef struct {
772 /** \brief Pointer to vtable for this context. */
773 const br_block_ctr_class *vtable;
774 #ifndef BR_DOXYGEN_IGNORE
775 uint32_t skey[60];
776 unsigned num_rounds;
777 #endif
778 } br_aes_ct_ctr_keys;
779
780 /**
781 * \brief Class instance for AES CBC encryption (`aes_ct` implementation).
782 */
783 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable;
784
785 /**
786 * \brief Class instance for AES CBC decryption (`aes_ct` implementation).
787 */
788 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable;
789
790 /**
791 * \brief Class instance for AES CTR encryption and decryption
792 * (`aes_ct` implementation).
793 */
794 extern const br_block_ctr_class br_aes_ct_ctr_vtable;
795
796 /**
797 * \brief Context initialisation (key schedule) for AES CBC encryption
798 * (`aes_ct` implementation).
799 *
800 * \param ctx context to initialise.
801 * \param key secret key.
802 * \param len secret key length (in bytes).
803 */
804 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys *ctx,
805 const void *key, size_t len);
806
807 /**
808 * \brief Context initialisation (key schedule) for AES CBC decryption
809 * (`aes_ct` implementation).
810 *
811 * \param ctx context to initialise.
812 * \param key secret key.
813 * \param len secret key length (in bytes).
814 */
815 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys *ctx,
816 const void *key, size_t len);
817
818 /**
819 * \brief Context initialisation (key schedule) for AES CTR encryption
820 * and decryption (`aes_ct` implementation).
821 *
822 * \param ctx context to initialise.
823 * \param key secret key.
824 * \param len secret key length (in bytes).
825 */
826 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys *ctx,
827 const void *key, size_t len);
828
829 /**
830 * \brief CBC encryption with AES (`aes_ct` implementation).
831 *
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).
836 */
837 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys *ctx, void *iv,
838 void *data, size_t len);
839
840 /**
841 * \brief CBC decryption with AES (`aes_ct` implementation).
842 *
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).
847 */
848 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys *ctx, void *iv,
849 void *data, size_t len);
850
851 /**
852 * \brief CTR encryption and decryption with AES (`aes_ct` implementation).
853 *
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.
860 */
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);
863
864 /*
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.)
871 */
872
873 /** \brief AES block size (16 bytes). */
874 #define br_aes_ct64_BLOCK_SIZE 16
875
876 /**
877 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption).
878 *
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.
881 */
882 typedef struct {
883 /** \brief Pointer to vtable for this context. */
884 const br_block_cbcenc_class *vtable;
885 #ifndef BR_DOXYGEN_IGNORE
886 uint64_t skey[30];
887 unsigned num_rounds;
888 #endif
889 } br_aes_ct64_cbcenc_keys;
890
891 /**
892 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption).
893 *
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.
896 */
897 typedef struct {
898 /** \brief Pointer to vtable for this context. */
899 const br_block_cbcdec_class *vtable;
900 #ifndef BR_DOXYGEN_IGNORE
901 uint64_t skey[30];
902 unsigned num_rounds;
903 #endif
904 } br_aes_ct64_cbcdec_keys;
905
906 /**
907 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption
908 * and decryption).
909 *
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.
912 */
913 typedef struct {
914 /** \brief Pointer to vtable for this context. */
915 const br_block_ctr_class *vtable;
916 #ifndef BR_DOXYGEN_IGNORE
917 uint64_t skey[30];
918 unsigned num_rounds;
919 #endif
920 } br_aes_ct64_ctr_keys;
921
922 /**
923 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation).
924 */
925 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable;
926
927 /**
928 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation).
929 */
930 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable;
931
932 /**
933 * \brief Class instance for AES CTR encryption and decryption
934 * (`aes_ct64` implementation).
935 */
936 extern const br_block_ctr_class br_aes_ct64_ctr_vtable;
937
938 /**
939 * \brief Context initialisation (key schedule) for AES CBC encryption
940 * (`aes_ct64` implementation).
941 *
942 * \param ctx context to initialise.
943 * \param key secret key.
944 * \param len secret key length (in bytes).
945 */
946 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys *ctx,
947 const void *key, size_t len);
948
949 /**
950 * \brief Context initialisation (key schedule) for AES CBC decryption
951 * (`aes_ct64` implementation).
952 *
953 * \param ctx context to initialise.
954 * \param key secret key.
955 * \param len secret key length (in bytes).
956 */
957 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys *ctx,
958 const void *key, size_t len);
959
960 /**
961 * \brief Context initialisation (key schedule) for AES CTR encryption
962 * and decryption (`aes_ct64` implementation).
963 *
964 * \param ctx context to initialise.
965 * \param key secret key.
966 * \param len secret key length (in bytes).
967 */
968 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys *ctx,
969 const void *key, size_t len);
970
971 /**
972 * \brief CBC encryption with AES (`aes_ct64` implementation).
973 *
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).
978 */
979 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys *ctx, void *iv,
980 void *data, size_t len);
981
982 /**
983 * \brief CBC decryption with AES (`aes_ct64` implementation).
984 *
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).
989 */
990 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys *ctx, void *iv,
991 void *data, size_t len);
992
993 /**
994 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation).
995 *
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.
1002 */
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);
1005
1006 /*
1007 * AES implementation using AES-NI opcodes (x86 platform).
1008 */
1009
1010 /** \brief AES block size (16 bytes). */
1011 #define br_aes_x86ni_BLOCK_SIZE 16
1012
1013 /**
1014 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC encryption).
1015 *
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.
1018 */
1019 typedef struct {
1020 /** \brief Pointer to vtable for this context. */
1021 const br_block_cbcenc_class *vtable;
1022 #ifndef BR_DOXYGEN_IGNORE
1023 union {
1024 unsigned char skni[16 * 15];
1025 } skey;
1026 unsigned num_rounds;
1027 #endif
1028 } br_aes_x86ni_cbcenc_keys;
1029
1030 /**
1031 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC decryption).
1032 *
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.
1035 */
1036 typedef struct {
1037 /** \brief Pointer to vtable for this context. */
1038 const br_block_cbcdec_class *vtable;
1039 #ifndef BR_DOXYGEN_IGNORE
1040 union {
1041 unsigned char skni[16 * 15];
1042 } skey;
1043 unsigned num_rounds;
1044 #endif
1045 } br_aes_x86ni_cbcdec_keys;
1046
1047 /**
1048 * \brief Context for AES subkeys (`aes_x86ni` implementation, CTR encryption
1049 * and decryption).
1050 *
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.
1053 */
1054 typedef struct {
1055 /** \brief Pointer to vtable for this context. */
1056 const br_block_ctr_class *vtable;
1057 #ifndef BR_DOXYGEN_IGNORE
1058 union {
1059 unsigned char skni[16 * 15];
1060 } skey;
1061 unsigned num_rounds;
1062 #endif
1063 } br_aes_x86ni_ctr_keys;
1064
1065 /**
1066 * \brief Class instance for AES CBC encryption (`aes_x86ni` implementation).
1067 *
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()`.
1071 */
1072 extern const br_block_cbcenc_class br_aes_x86ni_cbcenc_vtable;
1073
1074 /**
1075 * \brief Class instance for AES CBC decryption (`aes_x86ni` implementation).
1076 *
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()`.
1080 */
1081 extern const br_block_cbcdec_class br_aes_x86ni_cbcdec_vtable;
1082
1083 /**
1084 * \brief Class instance for AES CTR encryption and decryption
1085 * (`aes_x86ni` implementation).
1086 *
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()`.
1090 */
1091 extern const br_block_ctr_class br_aes_x86ni_ctr_vtable;
1092
1093 /**
1094 * \brief Context initialisation (key schedule) for AES CBC encryption
1095 * (`aes_x86ni` implementation).
1096 *
1097 * \param ctx context to initialise.
1098 * \param key secret key.
1099 * \param len secret key length (in bytes).
1100 */
1101 void br_aes_x86ni_cbcenc_init(br_aes_x86ni_cbcenc_keys *ctx,
1102 const void *key, size_t len);
1103
1104 /**
1105 * \brief Context initialisation (key schedule) for AES CBC decryption
1106 * (`aes_x86ni` implementation).
1107 *
1108 * \param ctx context to initialise.
1109 * \param key secret key.
1110 * \param len secret key length (in bytes).
1111 */
1112 void br_aes_x86ni_cbcdec_init(br_aes_x86ni_cbcdec_keys *ctx,
1113 const void *key, size_t len);
1114
1115 /**
1116 * \brief Context initialisation (key schedule) for AES CTR encryption
1117 * and decryption (`aes_x86ni` implementation).
1118 *
1119 * \param ctx context to initialise.
1120 * \param key secret key.
1121 * \param len secret key length (in bytes).
1122 */
1123 void br_aes_x86ni_ctr_init(br_aes_x86ni_ctr_keys *ctx,
1124 const void *key, size_t len);
1125
1126 /**
1127 * \brief CBC encryption with AES (`aes_x86ni` implementation).
1128 *
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).
1133 */
1134 void br_aes_x86ni_cbcenc_run(const br_aes_x86ni_cbcenc_keys *ctx, void *iv,
1135 void *data, size_t len);
1136
1137 /**
1138 * \brief CBC decryption with AES (`aes_x86ni` implementation).
1139 *
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).
1144 */
1145 void br_aes_x86ni_cbcdec_run(const br_aes_x86ni_cbcdec_keys *ctx, void *iv,
1146 void *data, size_t len);
1147
1148 /**
1149 * \brief CTR encryption and decryption with AES (`aes_x86ni` implementation).
1150 *
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.
1157 */
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);
1160
1161 /**
1162 * \brief Obtain the `aes_x86ni` AES-CBC (encryption) implementation, if
1163 * available.
1164 *
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`.
1169 *
1170 * \return the `aes_x868ni` AES-CBC (encryption) implementation, or `NULL`.
1171 */
1172 const br_block_cbcenc_class *br_aes_x86ni_cbcenc_get_vtable(void);
1173
1174 /**
1175 * \brief Obtain the `aes_x86ni` AES-CBC (decryption) implementation, if
1176 * available.
1177 *
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`.
1182 *
1183 * \return the `aes_x868ni` AES-CBC (decryption) implementation, or `NULL`.
1184 */
1185 const br_block_cbcdec_class *br_aes_x86ni_cbcdec_get_vtable(void);
1186
1187 /**
1188 * \brief Obtain the `aes_x86ni` AES-CTR implementation, if available.
1189 *
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`.
1194 *
1195 * \return the `aes_x868ni` AES-CTR implementation, or `NULL`.
1196 */
1197 const br_block_ctr_class *br_aes_x86ni_ctr_get_vtable(void);
1198
1199 /*
1200 * AES implementation using POWER8 opcodes.
1201 */
1202
1203 /** \brief AES block size (16 bytes). */
1204 #define br_aes_pwr8_BLOCK_SIZE 16
1205
1206 /**
1207 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC encryption).
1208 *
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.
1211 */
1212 typedef struct {
1213 /** \brief Pointer to vtable for this context. */
1214 const br_block_cbcenc_class *vtable;
1215 #ifndef BR_DOXYGEN_IGNORE
1216 union {
1217 unsigned char skni[16 * 15];
1218 } skey;
1219 unsigned num_rounds;
1220 #endif
1221 } br_aes_pwr8_cbcenc_keys;
1222
1223 /**
1224 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC decryption).
1225 *
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.
1228 */
1229 typedef struct {
1230 /** \brief Pointer to vtable for this context. */
1231 const br_block_cbcdec_class *vtable;
1232 #ifndef BR_DOXYGEN_IGNORE
1233 union {
1234 unsigned char skni[16 * 15];
1235 } skey;
1236 unsigned num_rounds;
1237 #endif
1238 } br_aes_pwr8_cbcdec_keys;
1239
1240 /**
1241 * \brief Context for AES subkeys (`aes_pwr8` implementation, CTR encryption
1242 * and decryption).
1243 *
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.
1246 */
1247 typedef struct {
1248 /** \brief Pointer to vtable for this context. */
1249 const br_block_ctr_class *vtable;
1250 #ifndef BR_DOXYGEN_IGNORE
1251 union {
1252 unsigned char skni[16 * 15];
1253 } skey;
1254 unsigned num_rounds;
1255 #endif
1256 } br_aes_pwr8_ctr_keys;
1257
1258 /**
1259 * \brief Class instance for AES CBC encryption (`aes_pwr8` implementation).
1260 *
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()`.
1264 */
1265 extern const br_block_cbcenc_class br_aes_pwr8_cbcenc_vtable;
1266
1267 /**
1268 * \brief Class instance for AES CBC decryption (`aes_pwr8` implementation).
1269 *
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()`.
1273 */
1274 extern const br_block_cbcdec_class br_aes_pwr8_cbcdec_vtable;
1275
1276 /**
1277 * \brief Class instance for AES CTR encryption and decryption
1278 * (`aes_pwr8` implementation).
1279 *
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()`.
1283 */
1284 extern const br_block_ctr_class br_aes_pwr8_ctr_vtable;
1285
1286 /**
1287 * \brief Context initialisation (key schedule) for AES CBC encryption
1288 * (`aes_pwr8` implementation).
1289 *
1290 * \param ctx context to initialise.
1291 * \param key secret key.
1292 * \param len secret key length (in bytes).
1293 */
1294 void br_aes_pwr8_cbcenc_init(br_aes_pwr8_cbcenc_keys *ctx,
1295 const void *key, size_t len);
1296
1297 /**
1298 * \brief Context initialisation (key schedule) for AES CBC decryption
1299 * (`aes_pwr8` implementation).
1300 *
1301 * \param ctx context to initialise.
1302 * \param key secret key.
1303 * \param len secret key length (in bytes).
1304 */
1305 void br_aes_pwr8_cbcdec_init(br_aes_pwr8_cbcdec_keys *ctx,
1306 const void *key, size_t len);
1307
1308 /**
1309 * \brief Context initialisation (key schedule) for AES CTR encryption
1310 * and decryption (`aes_pwr8` implementation).
1311 *
1312 * \param ctx context to initialise.
1313 * \param key secret key.
1314 * \param len secret key length (in bytes).
1315 */
1316 void br_aes_pwr8_ctr_init(br_aes_pwr8_ctr_keys *ctx,
1317 const void *key, size_t len);
1318
1319 /**
1320 * \brief CBC encryption with AES (`aes_pwr8` implementation).
1321 *
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).
1326 */
1327 void br_aes_pwr8_cbcenc_run(const br_aes_pwr8_cbcenc_keys *ctx, void *iv,
1328 void *data, size_t len);
1329
1330 /**
1331 * \brief CBC decryption with AES (`aes_pwr8` implementation).
1332 *
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).
1337 */
1338 void br_aes_pwr8_cbcdec_run(const br_aes_pwr8_cbcdec_keys *ctx, void *iv,
1339 void *data, size_t len);
1340
1341 /**
1342 * \brief CTR encryption and decryption with AES (`aes_pwr8` implementation).
1343 *
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.
1350 */
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);
1353
1354 /**
1355 * \brief Obtain the `aes_pwr8` AES-CBC (encryption) implementation, if
1356 * available.
1357 *
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`.
1362 *
1363 * \return the `aes_x868ni` AES-CBC (encryption) implementation, or `NULL`.
1364 */
1365 const br_block_cbcenc_class *br_aes_pwr8_cbcenc_get_vtable(void);
1366
1367 /**
1368 * \brief Obtain the `aes_pwr8` AES-CBC (decryption) implementation, if
1369 * available.
1370 *
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`.
1375 *
1376 * \return the `aes_x868ni` AES-CBC (decryption) implementation, or `NULL`.
1377 */
1378 const br_block_cbcdec_class *br_aes_pwr8_cbcdec_get_vtable(void);
1379
1380 /**
1381 * \brief Obtain the `aes_pwr8` AES-CTR implementation, if available.
1382 *
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`.
1387 *
1388 * \return the `aes_x868ni` AES-CTR implementation, or `NULL`.
1389 */
1390 const br_block_ctr_class *br_aes_pwr8_ctr_get_vtable(void);
1391
1392 /**
1393 * \brief Aggregate structure large enough to be used as context for
1394 * subkeys (CBC encryption) for all AES implementations.
1395 */
1396 typedef union {
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;
1405
1406 /**
1407 * \brief Aggregate structure large enough to be used as context for
1408 * subkeys (CBC decryption) for all AES implementations.
1409 */
1410 typedef union {
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;
1419
1420 /**
1421 * \brief Aggregate structure large enough to be used as context for
1422 * subkeys (CTR encryption and decryption) for all AES implementations.
1423 */
1424 typedef union {
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;
1433
1434 /*
1435 * Traditional, table-based implementation for DES/3DES. Since tables are
1436 * used, cache-timing attacks are conceptually possible.
1437 */
1438
1439 /** \brief DES/3DES block size (8 bytes). */
1440 #define br_des_tab_BLOCK_SIZE 8
1441
1442 /**
1443 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption).
1444 *
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.
1447 */
1448 typedef struct {
1449 /** \brief Pointer to vtable for this context. */
1450 const br_block_cbcenc_class *vtable;
1451 #ifndef BR_DOXYGEN_IGNORE
1452 uint32_t skey[96];
1453 unsigned num_rounds;
1454 #endif
1455 } br_des_tab_cbcenc_keys;
1456
1457 /**
1458 * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption).
1459 *
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.
1462 */
1463 typedef struct {
1464 /** \brief Pointer to vtable for this context. */
1465 const br_block_cbcdec_class *vtable;
1466 #ifndef BR_DOXYGEN_IGNORE
1467 uint32_t skey[96];
1468 unsigned num_rounds;
1469 #endif
1470 } br_des_tab_cbcdec_keys;
1471
1472 /**
1473 * \brief Class instance for DES CBC encryption (`des_tab` implementation).
1474 */
1475 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable;
1476
1477 /**
1478 * \brief Class instance for DES CBC decryption (`des_tab` implementation).
1479 */
1480 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable;
1481
1482 /**
1483 * \brief Context initialisation (key schedule) for DES CBC encryption
1484 * (`des_tab` implementation).
1485 *
1486 * \param ctx context to initialise.
1487 * \param key secret key.
1488 * \param len secret key length (in bytes).
1489 */
1490 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys *ctx,
1491 const void *key, size_t len);
1492
1493 /**
1494 * \brief Context initialisation (key schedule) for DES CBC decryption
1495 * (`des_tab` implementation).
1496 *
1497 * \param ctx context to initialise.
1498 * \param key secret key.
1499 * \param len secret key length (in bytes).
1500 */
1501 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys *ctx,
1502 const void *key, size_t len);
1503
1504 /**
1505 * \brief CBC encryption with DES (`des_tab` implementation).
1506 *
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).
1511 */
1512 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys *ctx, void *iv,
1513 void *data, size_t len);
1514
1515 /**
1516 * \brief CBC decryption with DES (`des_tab` implementation).
1517 *
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).
1522 */
1523 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys *ctx, void *iv,
1524 void *data, size_t len);
1525
1526 /*
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.
1529 */
1530
1531 /** \brief DES/3DES block size (8 bytes). */
1532 #define br_des_ct_BLOCK_SIZE 8
1533
1534 /**
1535 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption).
1536 *
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.
1539 */
1540 typedef struct {
1541 /** \brief Pointer to vtable for this context. */
1542 const br_block_cbcenc_class *vtable;
1543 #ifndef BR_DOXYGEN_IGNORE
1544 uint32_t skey[96];
1545 unsigned num_rounds;
1546 #endif
1547 } br_des_ct_cbcenc_keys;
1548
1549 /**
1550 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption).
1551 *
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.
1554 */
1555 typedef struct {
1556 /** \brief Pointer to vtable for this context. */
1557 const br_block_cbcdec_class *vtable;
1558 #ifndef BR_DOXYGEN_IGNORE
1559 uint32_t skey[96];
1560 unsigned num_rounds;
1561 #endif
1562 } br_des_ct_cbcdec_keys;
1563
1564 /**
1565 * \brief Class instance for DES CBC encryption (`des_ct` implementation).
1566 */
1567 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable;
1568
1569 /**
1570 * \brief Class instance for DES CBC decryption (`des_ct` implementation).
1571 */
1572 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable;
1573
1574 /**
1575 * \brief Context initialisation (key schedule) for DES CBC encryption
1576 * (`des_ct` implementation).
1577 *
1578 * \param ctx context to initialise.
1579 * \param key secret key.
1580 * \param len secret key length (in bytes).
1581 */
1582 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys *ctx,
1583 const void *key, size_t len);
1584
1585 /**
1586 * \brief Context initialisation (key schedule) for DES CBC decryption
1587 * (`des_ct` implementation).
1588 *
1589 * \param ctx context to initialise.
1590 * \param key secret key.
1591 * \param len secret key length (in bytes).
1592 */
1593 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys *ctx,
1594 const void *key, size_t len);
1595
1596 /**
1597 * \brief CBC encryption with DES (`des_ct` implementation).
1598 *
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).
1603 */
1604 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys *ctx, void *iv,
1605 void *data, size_t len);
1606
1607 /**
1608 * \brief CBC decryption with DES (`des_ct` implementation).
1609 *
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).
1614 */
1615 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys *ctx, void *iv,
1616 void *data, size_t len);
1617
1618 /*
1619 * These structures are large enough to accommodate subkeys for all
1620 * DES/3DES implementations.
1621 */
1622
1623 /**
1624 * \brief Aggregate structure large enough to be used as context for
1625 * subkeys (CBC encryption) for all DES implementations.
1626 */
1627 typedef union {
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;
1632
1633 /**
1634 * \brief Aggregate structure large enough to be used as context for
1635 * subkeys (CBC decryption) for all DES implementations.
1636 */
1637 typedef union {
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;
1642
1643 /**
1644 * \brief Type for a ChaCha20 implementation.
1645 *
1646 * An implementation follows the description in RFC 7539:
1647 *
1648 * - Key is 256 bits (`key` points to exactly 32 bytes).
1649 *
1650 * - IV is 96 bits (`iv` points to exactly 12 bytes).
1651 *
1652 * - Block counter is over 32 bits and starts at value `cc`; the
1653 * resulting value is returned.
1654 *
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).
1659 *
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).
1665 */
1666 typedef uint32_t (*br_chacha20_run)(const void *key,
1667 const void *iv, uint32_t cc, void *data, size_t len);
1668
1669 /**
1670 * \brief ChaCha20 implementation (straightforward C code, constant-time).
1671 *
1672 * \see br_chacha20_run
1673 *
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).
1679 */
1680 uint32_t br_chacha20_ct_run(const void *key,
1681 const void *iv, uint32_t cc, void *data, size_t len);
1682
1683 /**
1684 * \brief Type for a ChaCha20+Poly1305 AEAD implementation.
1685 *
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).
1690 *
1691 * After decryption, the caller is responsible for checking that the
1692 * computed tag matches the expected value.
1693 *
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.
1703 */
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);
1707
1708 /**
1709 * \brief ChaCha20+Poly1305 AEAD implementation (mixed 32-bit multiplications).
1710 *
1711 * \see br_poly1305_run
1712 *
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.
1722 */
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);
1726
1727 /**
1728 * \brief ChaCha20+Poly1305 AEAD implementation (pure 32-bit multiplications).
1729 *
1730 * \see br_poly1305_run
1731 *
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.
1741 */
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);
1745
1746 /**
1747 * \brief ChaCha20+Poly1305 AEAD implementation (i15).
1748 *
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.
1754 *
1755 * \see br_poly1305_run
1756 *
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.
1766 */
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);
1770
1771 #endif