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#ifdef __cplusplus 32extern "C" { 33#endif 34 35/** \file bearssl_block.h 36 * 37 * # Block Ciphers and Symmetric Ciphers 38 * 39 * This file documents the API for block ciphers and other symmetric 40 * ciphers. 41 * 42 * 43 * ## Procedural API 44 * 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. 49 * 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. 54 * 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). 57 * 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: 62 * 63 * - `br_xxx_BLOCK_SIZE` 64 * 65 * A macro that evaluates to the block size (in bytes) of the 66 * cipher. For all implemented block ciphers, this value is a 67 * power of two. 68 * 69 * - `br_xxx_cbcenc_keys` 70 * 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. 75 * 76 * - `br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)` 77 * 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 81 * the `vtable` field. 82 * 83 * - `br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx, void *iv, void *data, size_t len)` 84 * 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. 90 * 91 * - `br_xxx_cbcdec_keys` 92 * 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. 97 * 98 * - `br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)` 99 * 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. 104 * 105 * - `br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx, void *iv, void *data, size_t num_blocks)` 106 * 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. 112 * 113 * - `br_xxx_ctr_keys` 114 * 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. 119 * 120 * - `br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)` 121 * 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. 126 * 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`) 128 * 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. 138 * 139 * - `br_xxx_ctrcbc_keys` 140 * 141 * Context structure that contains the subkeys resulting from the 142 * key expansion. These subkeys are appropriate for doing combined 143 * CTR encryption/decryption and CBC-MAC, as used in the CCM and EAX 144 * authenticated encryption modes. The structure first field is 145 * called `vtable` and points to the appropriate OOP structure. 146 * 147 * - `br_xxx_ctrcbc_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)` 148 * 149 * Perform key expansion: subkeys for combined CTR 150 * encryption/decryption and CBC-MAC are computed and written in the 151 * provided context structure. The key length MUST be adequate for 152 * the implemented block cipher. This function also sets the 153 * `vtable` field. 154 * 155 * - `br_xxx_ctrcbc_encrypt(const br_xxx_ctrcbc_keys *ctx, void *ctr, void *cbcmac, void *data, size_t len)` 156 * 157 * Perform CTR encryption of some data, and CBC-MAC. Processing is 158 * done "in place" (the output data replaces the input data). This 159 * function applies CTR encryption on the data, using a full 160 * block-size counter (i.e. for 128-bit blocks, the counter is 161 * incremented as a 128-bit value). The 'ctr' array contains the 162 * initial value for the counter (used in the first block) and it is 163 * updated with the new value after data processing. The 'cbcmac' 164 * value shall point to a block-sized value which is used as IV for 165 * CBC-MAC, computed over the encrypted data (output of CTR 166 * encryption); the resulting CBC-MAC is written over 'cbcmac' on 167 * output. 168 * 169 * The data length MUST be a multiple of the block size. 170 * 171 * - `br_xxx_ctrcbc_decrypt(const br_xxx_ctrcbc_keys *ctx, void *ctr, void *cbcmac, void *data, size_t len)` 172 * 173 * Perform CTR decryption of some data, and CBC-MAC. Processing is 174 * done "in place" (the output data replaces the input data). This 175 * function applies CTR decryption on the data, using a full 176 * block-size counter (i.e. for 128-bit blocks, the counter is 177 * incremented as a 128-bit value). The 'ctr' array contains the 178 * initial value for the counter (used in the first block) and it is 179 * updated with the new value after data processing. The 'cbcmac' 180 * value shall point to a block-sized value which is used as IV for 181 * CBC-MAC, computed over the encrypted data (input of CTR 182 * encryption); the resulting CBC-MAC is written over 'cbcmac' on 183 * output. 184 * 185 * The data length MUST be a multiple of the block size. 186 * 187 * - `br_xxx_ctrcbc_ctr(const br_xxx_ctrcbc_keys *ctx, void *ctr, void *data, size_t len)` 188 * 189 * Perform CTR encryption or decryption of the provided data. The 190 * data is processed "in place" (the output data replaces the input 191 * data). A full block-sized counter is applied (i.e. for 128-bit 192 * blocks, the counter is incremented as a 128-bit value). The 'ctr' 193 * array contains the initial value for the counter (used in the 194 * first block), and it is updated with the new value after data 195 * processing. 196 * 197 * The data length MUST be a multiple of the block size. 198 * 199 * - `br_xxx_ctrcbc_mac(const br_xxx_ctrcbc_keys *ctx, void *cbcmac, const void *data, size_t len)` 200 * 201 * Compute CBC-MAC over the provided data. The IV for CBC-MAC is 202 * provided as 'cbcmac'; the output is written over the same array. 203 * The data itself is untouched. The data length MUST be a multiple 204 * of the block size. 205 * 206 * 207 * It shall be noted that the key expansion functions return `void`. If 208 * the provided key length is not allowed, then there will be no error 209 * reporting; implementations need not validate the key length, thus an 210 * invalid key length may result in undefined behaviour (e.g. buffer 211 * overflow). 212 * 213 * Subkey structures contain no interior pointer, and no external 214 * resources are allocated upon key expansion. They can thus be 215 * discarded without any explicit deallocation. 216 * 217 * 218 * ## Object-Oriented API 219 * 220 * Each context structure begins with a field (called `vtable`) that 221 * points to an instance of a structure that references the relevant 222 * functions through pointers. Each such structure contains the 223 * following: 224 * 225 * - `context_size` 226 * 227 * The size (in bytes) of the context structure for subkeys. 228 * 229 * - `block_size` 230 * 231 * The cipher block size (in bytes). 232 * 233 * - `log_block_size` 234 * 235 * The base-2 logarithm of cipher block size (e.g. 4 for blocks 236 * of 16 bytes). 237 * 238 * - `init` 239 * 240 * Pointer to the key expansion function. 241 * 242 * - `run` 243 * 244 * Pointer to the encryption/decryption function. 245 * 246 * For combined CTR/CBC-MAC encryption, the `vtable` has a slightly 247 * different structure: 248 * 249 * - `context_size` 250 * 251 * The size (in bytes) of the context structure for subkeys. 252 * 253 * - `block_size` 254 * 255 * The cipher block size (in bytes). 256 * 257 * - `log_block_size` 258 * 259 * The base-2 logarithm of cipher block size (e.g. 4 for blocks 260 * of 16 bytes). 261 * 262 * - `init` 263 * 264 * Pointer to the key expansion function. 265 * 266 * - `encrypt` 267 * 268 * Pointer to the CTR encryption + CBC-MAC function. 269 * 270 * - `decrypt` 271 * 272 * Pointer to the CTR decryption + CBC-MAC function. 273 * 274 * - `ctr` 275 * 276 * Pointer to the CTR encryption/decryption function. 277 * 278 * - `mac` 279 * 280 * Pointer to the CBC-MAC function. 281 * 282 * For block cipher "`xxx`", static, constant instances of these 283 * structures are defined, under the names: 284 * 285 * - `br_xxx_cbcenc_vtable` 286 * - `br_xxx_cbcdec_vtable` 287 * - `br_xxx_ctr_vtable` 288 * - `br_xxx_ctrcbc_vtable` 289 * 290 * 291 * ## Implemented Block Ciphers 292 * 293 * Provided implementations are: 294 * 295 * | Name | Function | Block Size (bytes) | Key lengths (bytes) | 296 * | :-------- | :------- | :----------------: | :-----------------: | 297 * | aes_big | AES | 16 | 16, 24 and 32 | 298 * | aes_small | AES | 16 | 16, 24 and 32 | 299 * | aes_ct | AES | 16 | 16, 24 and 32 | 300 * | aes_ct64 | AES | 16 | 16, 24 and 32 | 301 * | aes_x86ni | AES | 16 | 16, 24 and 32 | 302 * | aes_pwr8 | AES | 16 | 16, 24 and 32 | 303 * | des_ct | DES/3DES | 8 | 8, 16 and 24 | 304 * | des_tab | DES/3DES | 8 | 8, 16 and 24 | 305 * 306 * **Note:** DES/3DES nominally uses keys of 64, 128 and 192 bits (i.e. 8, 307 * 16 and 24 bytes), but some of the bits are ignored by the algorithm, so 308 * the _effective_ key lengths, from a security point of view, are 56, 309 * 112 and 168 bits, respectively. 310 * 311 * `aes_big` is a "classical" AES implementation, using tables. It 312 * is fast but not constant-time, since it makes data-dependent array 313 * accesses. 314 * 315 * `aes_small` is an AES implementation optimized for code size. It 316 * is substantially slower than `aes_big`; it is not constant-time 317 * either. 318 * 319 * `aes_ct` is a constant-time implementation of AES; its code is about 320 * as big as that of `aes_big`, while its performance is comparable to 321 * that of `aes_small`. However, it is constant-time. This 322 * implementation should thus be considered to be the "default" AES in 323 * BearSSL, to be used unless the operational context guarantees that a 324 * non-constant-time implementation is safe, or an architecture-specific 325 * constant-time implementation can be used (e.g. using dedicated 326 * hardware opcodes). 327 * 328 * `aes_ct64` is another constant-time implementation of AES. It is 329 * similar to `aes_ct` but uses 64-bit values. On 32-bit machines, 330 * `aes_ct64` is not faster than `aes_ct`, often a bit slower, and has 331 * a larger footprint; however, on 64-bit architectures, `aes_ct64` 332 * is typically twice faster than `aes_ct` for modes that allow parallel 333 * operations (i.e. CTR, and CBC decryption, but not CBC encryption). 334 * 335 * `aes_x86ni` exists only on x86 architectures (32-bit and 64-bit). It 336 * uses the AES-NI opcodes when available. 337 * 338 * `aes_pwr8` exists only on PowerPC / POWER architectures (32-bit and 339 * 64-bit, both little-endian and big-endian). It uses the AES opcodes 340 * present in POWER8 and later. 341 * 342 * `des_tab` is a classic, table-based implementation of DES/3DES. It 343 * is not constant-time. 344 * 345 * `des_ct` is an constant-time implementation of DES/3DES. It is 346 * substantially slower than `des_tab`. 347 * 348 * ## ChaCha20 and Poly1305 349 * 350 * ChaCha20 is a stream cipher. Poly1305 is a MAC algorithm. They 351 * are described in [RFC 7539](https://tools.ietf.org/html/rfc7539). 352 * 353 * Two function pointer types are defined: 354 * 355 * - `br_chacha20_run` describes a function that implements ChaCha20 356 * only. 357 * 358 * - `br_poly1305_run` describes an implementation of Poly1305, 359 * in the AEAD combination with ChaCha20 specified in RFC 7539 360 * (the ChaCha20 implementation is provided as a function pointer). 361 * 362 * `chacha20_ct` is a straightforward implementation of ChaCha20 in 363 * plain C; it is constant-time, small, and reasonably fast. 364 * 365 * `chacha20_sse2` leverages SSE2 opcodes (on x86 architectures that 366 * support these opcodes). It is faster than `chacha20_ct`. 367 * 368 * `poly1305_ctmul` is an implementation of the ChaCha20+Poly1305 AEAD 369 * construction, where the Poly1305 part is performed with mixed 32-bit 370 * multiplications (operands are 32-bit, result is 64-bit). 371 * 372 * `poly1305_ctmul32` implements ChaCha20+Poly1305 using pure 32-bit 373 * multiplications (32-bit operands, 32-bit result). It is slower than 374 * `poly1305_ctmul`, except on some specific architectures such as 375 * the ARM Cortex M0+. 376 * 377 * `poly1305_ctmulq` implements ChaCha20+Poly1305 with mixed 64-bit 378 * multiplications (operands are 64-bit, result is 128-bit) on 64-bit 379 * platforms that support such operations. 380 * 381 * `poly1305_i15` implements ChaCha20+Poly1305 with the generic "i15" 382 * big integer implementation. It is meant mostly for testing purposes, 383 * although it can help with saving a few hundred bytes of code footprint 384 * on systems where code size is scarce. 385 */ 386 387/** 388 * \brief Class type for CBC encryption implementations. 389 * 390 * A `br_block_cbcenc_class` instance points to the functions implementing 391 * a specific block cipher, when used in CBC mode for encrypting data. 392 */ 393typedef struct br_block_cbcenc_class_ br_block_cbcenc_class; 394struct br_block_cbcenc_class_ { 395 /** 396 * \brief Size (in bytes) of the context structure appropriate 397 * for containing subkeys. 398 */ 399 size_t context_size; 400 401 /** 402 * \brief Size of individual blocks (in bytes). 403 */ 404 unsigned block_size; 405 406 /** 407 * \brief Base-2 logarithm of the size of individual blocks, 408 * expressed in bytes. 409 */ 410 unsigned log_block_size; 411 412 /** 413 * \brief Initialisation function. 414 * 415 * This function sets the `vtable` field in the context structure. 416 * The key length MUST be one of the key lengths supported by 417 * the implementation. 418 * 419 * \param ctx context structure to initialise. 420 * \param key secret key. 421 * \param key_len key length (in bytes). 422 */ 423 void (*init)(const br_block_cbcenc_class **ctx, 424 const void *key, size_t key_len); 425 426 /** 427 * \brief Run the CBC encryption. 428 * 429 * The `iv` parameter points to the IV for this run; it is 430 * updated with a copy of the last encrypted block. The data 431 * is encrypted "in place"; its length (`len`) MUST be a 432 * multiple of the block size. 433 * 434 * \param ctx context structure (already initialised). 435 * \param iv IV for CBC encryption (updated). 436 * \param data data to encrypt. 437 * \param len data length (in bytes, multiple of block size). 438 */ 439 void (*run)(const br_block_cbcenc_class *const *ctx, 440 void *iv, void *data, size_t len); 441}; 442 443/** 444 * \brief Class type for CBC decryption implementations. 445 * 446 * A `br_block_cbcdec_class` instance points to the functions implementing 447 * a specific block cipher, when used in CBC mode for decrypting data. 448 */ 449typedef struct br_block_cbcdec_class_ br_block_cbcdec_class; 450struct br_block_cbcdec_class_ { 451 /** 452 * \brief Size (in bytes) of the context structure appropriate 453 * for containing subkeys. 454 */ 455 size_t context_size; 456 457 /** 458 * \brief Size of individual blocks (in bytes). 459 */ 460 unsigned block_size; 461 462 /** 463 * \brief Base-2 logarithm of the size of individual blocks, 464 * expressed in bytes. 465 */ 466 unsigned log_block_size; 467 468 /** 469 * \brief Initialisation function. 470 * 471 * This function sets the `vtable` field in the context structure. 472 * The key length MUST be one of the key lengths supported by 473 * the implementation. 474 * 475 * \param ctx context structure to initialise. 476 * \param key secret key. 477 * \param key_len key length (in bytes). 478 */ 479 void (*init)(const br_block_cbcdec_class **ctx, 480 const void *key, size_t key_len); 481 482 /** 483 * \brief Run the CBC decryption. 484 * 485 * The `iv` parameter points to the IV for this run; it is 486 * updated with a copy of the last encrypted block. The data 487 * is decrypted "in place"; its length (`len`) MUST be a 488 * multiple of the block size. 489 * 490 * \param ctx context structure (already initialised). 491 * \param iv IV for CBC decryption (updated). 492 * \param data data to decrypt. 493 * \param len data length (in bytes, multiple of block size). 494 */ 495 void (*run)(const br_block_cbcdec_class *const *ctx, 496 void *iv, void *data, size_t len); 497}; 498 499/** 500 * \brief Class type for CTR encryption/decryption implementations. 501 * 502 * A `br_block_ctr_class` instance points to the functions implementing 503 * a specific block cipher, when used in CTR mode for encrypting or 504 * decrypting data. 505 */ 506typedef struct br_block_ctr_class_ br_block_ctr_class; 507struct br_block_ctr_class_ { 508 /** 509 * \brief Size (in bytes) of the context structure appropriate 510 * for containing subkeys. 511 */ 512 size_t context_size; 513 514 /** 515 * \brief Size of individual blocks (in bytes). 516 */ 517 unsigned block_size; 518 519 /** 520 * \brief Base-2 logarithm of the size of individual blocks, 521 * expressed in bytes. 522 */ 523 unsigned log_block_size; 524 525 /** 526 * \brief Initialisation function. 527 * 528 * This function sets the `vtable` field in the context structure. 529 * The key length MUST be one of the key lengths supported by 530 * the implementation. 531 * 532 * \param ctx context structure to initialise. 533 * \param key secret key. 534 * \param key_len key length (in bytes). 535 */ 536 void (*init)(const br_block_ctr_class **ctx, 537 const void *key, size_t key_len); 538 539 /** 540 * \brief Run the CTR encryption or decryption. 541 * 542 * The `iv` parameter points to the IV for this run; its 543 * length is exactly 4 bytes less than the block size (e.g. 544 * 12 bytes for AES/CTR). The IV is combined with a 32-bit 545 * block counter to produce the block value which is processed 546 * with the block cipher. 547 * 548 * The data to encrypt or decrypt is updated "in place". Its 549 * length (`len` bytes) is not required to be a multiple of 550 * the block size; if the final block is partial, then the 551 * corresponding key stream bits are dropped. 552 * 553 * The resulting counter value is returned. 554 * 555 * \param ctx context structure (already initialised). 556 * \param iv IV for CTR encryption/decryption. 557 * \param cc initial value for the block counter. 558 * \param data data to encrypt or decrypt. 559 * \param len data length (in bytes). 560 * \return the new block counter value. 561 */ 562 uint32_t (*run)(const br_block_ctr_class *const *ctx, 563 const void *iv, uint32_t cc, void *data, size_t len); 564}; 565 566/** 567 * \brief Class type for combined CTR and CBC-MAC implementations. 568 * 569 * A `br_block_ctrcbc_class` instance points to the functions implementing 570 * a specific block cipher, when used in CTR mode for encrypting or 571 * decrypting data, along with CBC-MAC. 572 */ 573typedef struct br_block_ctrcbc_class_ br_block_ctrcbc_class; 574struct br_block_ctrcbc_class_ { 575 /** 576 * \brief Size (in bytes) of the context structure appropriate 577 * for containing subkeys. 578 */ 579 size_t context_size; 580 581 /** 582 * \brief Size of individual blocks (in bytes). 583 */ 584 unsigned block_size; 585 586 /** 587 * \brief Base-2 logarithm of the size of individual blocks, 588 * expressed in bytes. 589 */ 590 unsigned log_block_size; 591 592 /** 593 * \brief Initialisation function. 594 * 595 * This function sets the `vtable` field in the context structure. 596 * The key length MUST be one of the key lengths supported by 597 * the implementation. 598 * 599 * \param ctx context structure to initialise. 600 * \param key secret key. 601 * \param key_len key length (in bytes). 602 */ 603 void (*init)(const br_block_ctrcbc_class **ctx, 604 const void *key, size_t key_len); 605 606 /** 607 * \brief Run the CTR encryption + CBC-MAC. 608 * 609 * The `ctr` parameter points to the counter; its length shall 610 * be equal to the block size. It is updated by this function 611 * as encryption proceeds. 612 * 613 * The `cbcmac` parameter points to the IV for CBC-MAC. The MAC 614 * is computed over the encrypted data (output of CTR 615 * encryption). Its length shall be equal to the block size. The 616 * computed CBC-MAC value is written over the `cbcmac` array. 617 * 618 * The data to encrypt is updated "in place". Its length (`len` 619 * bytes) MUST be a multiple of the block size. 620 * 621 * \param ctx context structure (already initialised). 622 * \param ctr counter for CTR encryption (initial and final). 623 * \param cbcmac IV and output buffer for CBC-MAC. 624 * \param data data to encrypt. 625 * \param len data length (in bytes). 626 */ 627 void (*encrypt)(const br_block_ctrcbc_class *const *ctx, 628 void *ctr, void *cbcmac, void *data, size_t len); 629 630 /** 631 * \brief Run the CTR decryption + CBC-MAC. 632 * 633 * The `ctr` parameter points to the counter; its length shall 634 * be equal to the block size. It is updated by this function 635 * as decryption proceeds. 636 * 637 * The `cbcmac` parameter points to the IV for CBC-MAC. The MAC 638 * is computed over the encrypted data (i.e. before CTR 639 * decryption). Its length shall be equal to the block size. The 640 * computed CBC-MAC value is written over the `cbcmac` array. 641 * 642 * The data to decrypt is updated "in place". Its length (`len` 643 * bytes) MUST be a multiple of the block size. 644 * 645 * \param ctx context structure (already initialised). 646 * \param ctr counter for CTR encryption (initial and final). 647 * \param cbcmac IV and output buffer for CBC-MAC. 648 * \param data data to decrypt. 649 * \param len data length (in bytes). 650 */ 651 void (*decrypt)(const br_block_ctrcbc_class *const *ctx, 652 void *ctr, void *cbcmac, void *data, size_t len); 653 654 /** 655 * \brief Run the CTR encryption/decryption only. 656 * 657 * The `ctr` parameter points to the counter; its length shall 658 * be equal to the block size. It is updated by this function 659 * as decryption proceeds. 660 * 661 * The data to decrypt is updated "in place". Its length (`len` 662 * bytes) MUST be a multiple of the block size. 663 * 664 * \param ctx context structure (already initialised). 665 * \param ctr counter for CTR encryption (initial and final). 666 * \param data data to decrypt. 667 * \param len data length (in bytes). 668 */ 669 void (*ctr)(const br_block_ctrcbc_class *const *ctx, 670 void *ctr, void *data, size_t len); 671 672 /** 673 * \brief Run the CBC-MAC only. 674 * 675 * The `cbcmac` parameter points to the IV for CBC-MAC. The MAC 676 * is computed over the encrypted data (i.e. before CTR 677 * decryption). Its length shall be equal to the block size. The 678 * computed CBC-MAC value is written over the `cbcmac` array. 679 * 680 * The data is unmodified. Its length (`len` bytes) MUST be a 681 * multiple of the block size. 682 * 683 * \param ctx context structure (already initialised). 684 * \param cbcmac IV and output buffer for CBC-MAC. 685 * \param data data to decrypt. 686 * \param len data length (in bytes). 687 */ 688 void (*mac)(const br_block_ctrcbc_class *const *ctx, 689 void *cbcmac, const void *data, size_t len); 690}; 691 692/* 693 * Traditional, table-based AES implementation. It is fast, but uses 694 * internal tables (in particular a 1 kB table for encryption, another 695 * 1 kB table for decryption, and a 256-byte table for key schedule), 696 * and it is not constant-time. In contexts where cache-timing attacks 697 * apply, this implementation may leak the secret key. 698 */ 699 700/** \brief AES block size (16 bytes). */ 701#define br_aes_big_BLOCK_SIZE 16 702 703/** 704 * \brief Context for AES subkeys (`aes_big` implementation, CBC encryption). 705 * 706 * First field is a pointer to the vtable; it is set by the initialisation 707 * function. Other fields are not supposed to be accessed by user code. 708 */ 709typedef struct { 710 /** \brief Pointer to vtable for this context. */ 711 const br_block_cbcenc_class *vtable; 712#ifndef BR_DOXYGEN_IGNORE 713 uint32_t skey[60]; 714 unsigned num_rounds; 715#endif 716} br_aes_big_cbcenc_keys; 717 718/** 719 * \brief Context for AES subkeys (`aes_big` implementation, CBC decryption). 720 * 721 * First field is a pointer to the vtable; it is set by the initialisation 722 * function. Other fields are not supposed to be accessed by user code. 723 */ 724typedef struct { 725 /** \brief Pointer to vtable for this context. */ 726 const br_block_cbcdec_class *vtable; 727#ifndef BR_DOXYGEN_IGNORE 728 uint32_t skey[60]; 729 unsigned num_rounds; 730#endif 731} br_aes_big_cbcdec_keys; 732 733/** 734 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption 735 * and decryption). 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 */ 740typedef struct { 741 /** \brief Pointer to vtable for this context. */ 742 const br_block_ctr_class *vtable; 743#ifndef BR_DOXYGEN_IGNORE 744 uint32_t skey[60]; 745 unsigned num_rounds; 746#endif 747} br_aes_big_ctr_keys; 748 749/** 750 * \brief Context for AES subkeys (`aes_big` implementation, CTR encryption 751 * and decryption + CBC-MAC). 752 * 753 * First field is a pointer to the vtable; it is set by the initialisation 754 * function. Other fields are not supposed to be accessed by user code. 755 */ 756typedef struct { 757 /** \brief Pointer to vtable for this context. */ 758 const br_block_ctrcbc_class *vtable; 759#ifndef BR_DOXYGEN_IGNORE 760 uint32_t skey[60]; 761 unsigned num_rounds; 762#endif 763} br_aes_big_ctrcbc_keys; 764 765/** 766 * \brief Class instance for AES CBC encryption (`aes_big` implementation). 767 */ 768extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable; 769 770/** 771 * \brief Class instance for AES CBC decryption (`aes_big` implementation). 772 */ 773extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable; 774 775/** 776 * \brief Class instance for AES CTR encryption and decryption 777 * (`aes_big` implementation). 778 */ 779extern const br_block_ctr_class br_aes_big_ctr_vtable; 780 781/** 782 * \brief Class instance for AES CTR encryption/decryption + CBC-MAC 783 * (`aes_big` implementation). 784 */ 785extern const br_block_ctrcbc_class br_aes_big_ctrcbc_vtable; 786 787/** 788 * \brief Context initialisation (key schedule) for AES CBC encryption 789 * (`aes_big` implementation). 790 * 791 * \param ctx context to initialise. 792 * \param key secret key. 793 * \param len secret key length (in bytes). 794 */ 795void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys *ctx, 796 const void *key, size_t len); 797 798/** 799 * \brief Context initialisation (key schedule) for AES CBC decryption 800 * (`aes_big` implementation). 801 * 802 * \param ctx context to initialise. 803 * \param key secret key. 804 * \param len secret key length (in bytes). 805 */ 806void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys *ctx, 807 const void *key, size_t len); 808 809/** 810 * \brief Context initialisation (key schedule) for AES CTR encryption 811 * and decryption (`aes_big` implementation). 812 * 813 * \param ctx context to initialise. 814 * \param key secret key. 815 * \param len secret key length (in bytes). 816 */ 817void br_aes_big_ctr_init(br_aes_big_ctr_keys *ctx, 818 const void *key, size_t len); 819 820/** 821 * \brief Context initialisation (key schedule) for AES CTR + CBC-MAC 822 * (`aes_big` implementation). 823 * 824 * \param ctx context to initialise. 825 * \param key secret key. 826 * \param len secret key length (in bytes). 827 */ 828void br_aes_big_ctrcbc_init(br_aes_big_ctrcbc_keys *ctx, 829 const void *key, size_t len); 830 831/** 832 * \brief CBC encryption with AES (`aes_big` implementation). 833 * 834 * \param ctx context (already initialised). 835 * \param iv IV (updated). 836 * \param data data to encrypt (updated). 837 * \param len data length (in bytes, MUST be multiple of 16). 838 */ 839void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys *ctx, void *iv, 840 void *data, size_t len); 841 842/** 843 * \brief CBC decryption with AES (`aes_big` implementation). 844 * 845 * \param ctx context (already initialised). 846 * \param iv IV (updated). 847 * \param data data to decrypt (updated). 848 * \param len data length (in bytes, MUST be multiple of 16). 849 */ 850void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys *ctx, void *iv, 851 void *data, size_t len); 852 853/** 854 * \brief CTR encryption and decryption with AES (`aes_big` implementation). 855 * 856 * \param ctx context (already initialised). 857 * \param iv IV (constant, 12 bytes). 858 * \param cc initial block counter value. 859 * \param data data to encrypt or decrypt (updated). 860 * \param len data length (in bytes). 861 * \return new block counter value. 862 */ 863uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys *ctx, 864 const void *iv, uint32_t cc, void *data, size_t len); 865 866/** 867 * \brief CTR encryption + CBC-MAC with AES (`aes_big` implementation). 868 * 869 * \param ctx context (already initialised). 870 * \param ctr counter for CTR (16 bytes, updated). 871 * \param cbcmac IV for CBC-MAC (updated). 872 * \param data data to encrypt (updated). 873 * \param len data length (in bytes, MUST be a multiple of 16). 874 */ 875void br_aes_big_ctrcbc_encrypt(const br_aes_big_ctrcbc_keys *ctx, 876 void *ctr, void *cbcmac, void *data, size_t len); 877 878/** 879 * \brief CTR decryption + CBC-MAC with AES (`aes_big` implementation). 880 * 881 * \param ctx context (already initialised). 882 * \param ctr counter for CTR (16 bytes, updated). 883 * \param cbcmac IV for CBC-MAC (updated). 884 * \param data data to decrypt (updated). 885 * \param len data length (in bytes, MUST be a multiple of 16). 886 */ 887void br_aes_big_ctrcbc_decrypt(const br_aes_big_ctrcbc_keys *ctx, 888 void *ctr, void *cbcmac, void *data, size_t len); 889 890/** 891 * \brief CTR encryption/decryption with AES (`aes_big` implementation). 892 * 893 * \param ctx context (already initialised). 894 * \param ctr counter for CTR (16 bytes, updated). 895 * \param data data to MAC (updated). 896 * \param len data length (in bytes, MUST be a multiple of 16). 897 */ 898void br_aes_big_ctrcbc_ctr(const br_aes_big_ctrcbc_keys *ctx, 899 void *ctr, void *data, size_t len); 900 901/** 902 * \brief CBC-MAC with AES (`aes_big` implementation). 903 * 904 * \param ctx context (already initialised). 905 * \param cbcmac IV for CBC-MAC (updated). 906 * \param data data to MAC (unmodified). 907 * \param len data length (in bytes, MUST be a multiple of 16). 908 */ 909void br_aes_big_ctrcbc_mac(const br_aes_big_ctrcbc_keys *ctx, 910 void *cbcmac, const void *data, size_t len); 911 912/* 913 * AES implementation optimized for size. It is slower than the 914 * traditional table-based AES implementation, but requires much less 915 * code. It still uses data-dependent table accesses (albeit within a 916 * much smaller 256-byte table), which makes it conceptually vulnerable 917 * to cache-timing attacks. 918 */ 919 920/** \brief AES block size (16 bytes). */ 921#define br_aes_small_BLOCK_SIZE 16 922 923/** 924 * \brief Context for AES subkeys (`aes_small` implementation, CBC encryption). 925 * 926 * First field is a pointer to the vtable; it is set by the initialisation 927 * function. Other fields are not supposed to be accessed by user code. 928 */ 929typedef struct { 930 /** \brief Pointer to vtable for this context. */ 931 const br_block_cbcenc_class *vtable; 932#ifndef BR_DOXYGEN_IGNORE 933 uint32_t skey[60]; 934 unsigned num_rounds; 935#endif 936} br_aes_small_cbcenc_keys; 937 938/** 939 * \brief Context for AES subkeys (`aes_small` implementation, CBC decryption). 940 * 941 * First field is a pointer to the vtable; it is set by the initialisation 942 * function. Other fields are not supposed to be accessed by user code. 943 */ 944typedef struct { 945 /** \brief Pointer to vtable for this context. */ 946 const br_block_cbcdec_class *vtable; 947#ifndef BR_DOXYGEN_IGNORE 948 uint32_t skey[60]; 949 unsigned num_rounds; 950#endif 951} br_aes_small_cbcdec_keys; 952 953/** 954 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption 955 * and decryption). 956 * 957 * First field is a pointer to the vtable; it is set by the initialisation 958 * function. Other fields are not supposed to be accessed by user code. 959 */ 960typedef struct { 961 /** \brief Pointer to vtable for this context. */ 962 const br_block_ctr_class *vtable; 963#ifndef BR_DOXYGEN_IGNORE 964 uint32_t skey[60]; 965 unsigned num_rounds; 966#endif 967} br_aes_small_ctr_keys; 968 969/** 970 * \brief Context for AES subkeys (`aes_small` implementation, CTR encryption 971 * and decryption + CBC-MAC). 972 * 973 * First field is a pointer to the vtable; it is set by the initialisation 974 * function. Other fields are not supposed to be accessed by user code. 975 */ 976typedef struct { 977 /** \brief Pointer to vtable for this context. */ 978 const br_block_ctrcbc_class *vtable; 979#ifndef BR_DOXYGEN_IGNORE 980 uint32_t skey[60]; 981 unsigned num_rounds; 982#endif 983} br_aes_small_ctrcbc_keys; 984 985/** 986 * \brief Class instance for AES CBC encryption (`aes_small` implementation). 987 */ 988extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable; 989 990/** 991 * \brief Class instance for AES CBC decryption (`aes_small` implementation). 992 */ 993extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable; 994 995/** 996 * \brief Class instance for AES CTR encryption and decryption 997 * (`aes_small` implementation). 998 */ 999extern const br_block_ctr_class br_aes_small_ctr_vtable; 1000 1001/** 1002 * \brief Class instance for AES CTR encryption/decryption + CBC-MAC 1003 * (`aes_small` implementation). 1004 */ 1005extern const br_block_ctrcbc_class br_aes_small_ctrcbc_vtable; 1006 1007/** 1008 * \brief Context initialisation (key schedule) for AES CBC encryption 1009 * (`aes_small` implementation). 1010 * 1011 * \param ctx context to initialise. 1012 * \param key secret key. 1013 * \param len secret key length (in bytes). 1014 */ 1015void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys *ctx, 1016 const void *key, size_t len); 1017 1018/** 1019 * \brief Context initialisation (key schedule) for AES CBC decryption 1020 * (`aes_small` implementation). 1021 * 1022 * \param ctx context to initialise. 1023 * \param key secret key. 1024 * \param len secret key length (in bytes). 1025 */ 1026void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys *ctx, 1027 const void *key, size_t len); 1028 1029/** 1030 * \brief Context initialisation (key schedule) for AES CTR encryption 1031 * and decryption (`aes_small` implementation). 1032 * 1033 * \param ctx context to initialise. 1034 * \param key secret key. 1035 * \param len secret key length (in bytes). 1036 */ 1037void br_aes_small_ctr_init(br_aes_small_ctr_keys *ctx, 1038 const void *key, size_t len); 1039 1040/** 1041 * \brief Context initialisation (key schedule) for AES CTR + CBC-MAC 1042 * (`aes_small` implementation). 1043 * 1044 * \param ctx context to initialise. 1045 * \param key secret key. 1046 * \param len secret key length (in bytes). 1047 */ 1048void br_aes_small_ctrcbc_init(br_aes_small_ctrcbc_keys *ctx, 1049 const void *key, size_t len); 1050 1051/** 1052 * \brief CBC encryption with AES (`aes_small` implementation). 1053 * 1054 * \param ctx context (already initialised). 1055 * \param iv IV (updated). 1056 * \param data data to encrypt (updated). 1057 * \param len data length (in bytes, MUST be multiple of 16). 1058 */ 1059void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys *ctx, void *iv, 1060 void *data, size_t len); 1061 1062/** 1063 * \brief CBC decryption with AES (`aes_small` implementation). 1064 * 1065 * \param ctx context (already initialised). 1066 * \param iv IV (updated). 1067 * \param data data to decrypt (updated). 1068 * \param len data length (in bytes, MUST be multiple of 16). 1069 */ 1070void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys *ctx, void *iv, 1071 void *data, size_t len); 1072 1073/** 1074 * \brief CTR encryption and decryption with AES (`aes_small` implementation). 1075 * 1076 * \param ctx context (already initialised). 1077 * \param iv IV (constant, 12 bytes). 1078 * \param cc initial block counter value. 1079 * \param data data to decrypt (updated). 1080 * \param len data length (in bytes). 1081 * \return new block counter value. 1082 */ 1083uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys *ctx, 1084 const void *iv, uint32_t cc, void *data, size_t len); 1085 1086/** 1087 * \brief CTR encryption + CBC-MAC with AES (`aes_small` implementation). 1088 * 1089 * \param ctx context (already initialised). 1090 * \param ctr counter for CTR (16 bytes, updated). 1091 * \param cbcmac IV for CBC-MAC (updated). 1092 * \param data data to encrypt (updated). 1093 * \param len data length (in bytes, MUST be a multiple of 16). 1094 */ 1095void br_aes_small_ctrcbc_encrypt(const br_aes_small_ctrcbc_keys *ctx, 1096 void *ctr, void *cbcmac, void *data, size_t len); 1097 1098/** 1099 * \brief CTR decryption + CBC-MAC with AES (`aes_small` implementation). 1100 * 1101 * \param ctx context (already initialised). 1102 * \param ctr counter for CTR (16 bytes, updated). 1103 * \param cbcmac IV for CBC-MAC (updated). 1104 * \param data data to decrypt (updated). 1105 * \param len data length (in bytes, MUST be a multiple of 16). 1106 */ 1107void br_aes_small_ctrcbc_decrypt(const br_aes_small_ctrcbc_keys *ctx, 1108 void *ctr, void *cbcmac, void *data, size_t len); 1109 1110/** 1111 * \brief CTR encryption/decryption with AES (`aes_small` implementation). 1112 * 1113 * \param ctx context (already initialised). 1114 * \param ctr counter for CTR (16 bytes, updated). 1115 * \param data data to MAC (updated). 1116 * \param len data length (in bytes, MUST be a multiple of 16). 1117 */ 1118void br_aes_small_ctrcbc_ctr(const br_aes_small_ctrcbc_keys *ctx, 1119 void *ctr, void *data, size_t len); 1120 1121/** 1122 * \brief CBC-MAC with AES (`aes_small` implementation). 1123 * 1124 * \param ctx context (already initialised). 1125 * \param cbcmac IV for CBC-MAC (updated). 1126 * \param data data to MAC (unmodified). 1127 * \param len data length (in bytes, MUST be a multiple of 16). 1128 */ 1129void br_aes_small_ctrcbc_mac(const br_aes_small_ctrcbc_keys *ctx, 1130 void *cbcmac, const void *data, size_t len); 1131 1132/* 1133 * Constant-time AES implementation. Its size is similar to that of 1134 * 'aes_big', and its performance is similar to that of 'aes_small' (faster 1135 * decryption, slower encryption). However, it is constant-time, i.e. 1136 * immune to cache-timing and similar attacks. 1137 */ 1138 1139/** \brief AES block size (16 bytes). */ 1140#define br_aes_ct_BLOCK_SIZE 16 1141 1142/** 1143 * \brief Context for AES subkeys (`aes_ct` implementation, CBC encryption). 1144 * 1145 * First field is a pointer to the vtable; it is set by the initialisation 1146 * function. Other fields are not supposed to be accessed by user code. 1147 */ 1148typedef struct { 1149 /** \brief Pointer to vtable for this context. */ 1150 const br_block_cbcenc_class *vtable; 1151#ifndef BR_DOXYGEN_IGNORE 1152 uint32_t skey[60]; 1153 unsigned num_rounds; 1154#endif 1155} br_aes_ct_cbcenc_keys; 1156 1157/** 1158 * \brief Context for AES subkeys (`aes_ct` implementation, CBC decryption). 1159 * 1160 * First field is a pointer to the vtable; it is set by the initialisation 1161 * function. Other fields are not supposed to be accessed by user code. 1162 */ 1163typedef struct { 1164 /** \brief Pointer to vtable for this context. */ 1165 const br_block_cbcdec_class *vtable; 1166#ifndef BR_DOXYGEN_IGNORE 1167 uint32_t skey[60]; 1168 unsigned num_rounds; 1169#endif 1170} br_aes_ct_cbcdec_keys; 1171 1172/** 1173 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption 1174 * and decryption). 1175 * 1176 * First field is a pointer to the vtable; it is set by the initialisation 1177 * function. Other fields are not supposed to be accessed by user code. 1178 */ 1179typedef struct { 1180 /** \brief Pointer to vtable for this context. */ 1181 const br_block_ctr_class *vtable; 1182#ifndef BR_DOXYGEN_IGNORE 1183 uint32_t skey[60]; 1184 unsigned num_rounds; 1185#endif 1186} br_aes_ct_ctr_keys; 1187 1188/** 1189 * \brief Context for AES subkeys (`aes_ct` implementation, CTR encryption 1190 * and decryption + CBC-MAC). 1191 * 1192 * First field is a pointer to the vtable; it is set by the initialisation 1193 * function. Other fields are not supposed to be accessed by user code. 1194 */ 1195typedef struct { 1196 /** \brief Pointer to vtable for this context. */ 1197 const br_block_ctrcbc_class *vtable; 1198#ifndef BR_DOXYGEN_IGNORE 1199 uint32_t skey[60]; 1200 unsigned num_rounds; 1201#endif 1202} br_aes_ct_ctrcbc_keys; 1203 1204/** 1205 * \brief Class instance for AES CBC encryption (`aes_ct` implementation). 1206 */ 1207extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable; 1208 1209/** 1210 * \brief Class instance for AES CBC decryption (`aes_ct` implementation). 1211 */ 1212extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable; 1213 1214/** 1215 * \brief Class instance for AES CTR encryption and decryption 1216 * (`aes_ct` implementation). 1217 */ 1218extern const br_block_ctr_class br_aes_ct_ctr_vtable; 1219 1220/** 1221 * \brief Class instance for AES CTR encryption/decryption + CBC-MAC 1222 * (`aes_ct` implementation). 1223 */ 1224extern const br_block_ctrcbc_class br_aes_ct_ctrcbc_vtable; 1225 1226/** 1227 * \brief Context initialisation (key schedule) for AES CBC encryption 1228 * (`aes_ct` implementation). 1229 * 1230 * \param ctx context to initialise. 1231 * \param key secret key. 1232 * \param len secret key length (in bytes). 1233 */ 1234void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys *ctx, 1235 const void *key, size_t len); 1236 1237/** 1238 * \brief Context initialisation (key schedule) for AES CBC decryption 1239 * (`aes_ct` implementation). 1240 * 1241 * \param ctx context to initialise. 1242 * \param key secret key. 1243 * \param len secret key length (in bytes). 1244 */ 1245void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys *ctx, 1246 const void *key, size_t len); 1247 1248/** 1249 * \brief Context initialisation (key schedule) for AES CTR encryption 1250 * and decryption (`aes_ct` implementation). 1251 * 1252 * \param ctx context to initialise. 1253 * \param key secret key. 1254 * \param len secret key length (in bytes). 1255 */ 1256void br_aes_ct_ctr_init(br_aes_ct_ctr_keys *ctx, 1257 const void *key, size_t len); 1258 1259/** 1260 * \brief Context initialisation (key schedule) for AES CTR + CBC-MAC 1261 * (`aes_ct` implementation). 1262 * 1263 * \param ctx context to initialise. 1264 * \param key secret key. 1265 * \param len secret key length (in bytes). 1266 */ 1267void br_aes_ct_ctrcbc_init(br_aes_ct_ctrcbc_keys *ctx, 1268 const void *key, size_t len); 1269 1270/** 1271 * \brief CBC encryption with AES (`aes_ct` implementation). 1272 * 1273 * \param ctx context (already initialised). 1274 * \param iv IV (updated). 1275 * \param data data to encrypt (updated). 1276 * \param len data length (in bytes, MUST be multiple of 16). 1277 */ 1278void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys *ctx, void *iv, 1279 void *data, size_t len); 1280 1281/** 1282 * \brief CBC decryption with AES (`aes_ct` implementation). 1283 * 1284 * \param ctx context (already initialised). 1285 * \param iv IV (updated). 1286 * \param data data to decrypt (updated). 1287 * \param len data length (in bytes, MUST be multiple of 16). 1288 */ 1289void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys *ctx, void *iv, 1290 void *data, size_t len); 1291 1292/** 1293 * \brief CTR encryption and decryption with AES (`aes_ct` implementation). 1294 * 1295 * \param ctx context (already initialised). 1296 * \param iv IV (constant, 12 bytes). 1297 * \param cc initial block counter value. 1298 * \param data data to decrypt (updated). 1299 * \param len data length (in bytes). 1300 * \return new block counter value. 1301 */ 1302uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys *ctx, 1303 const void *iv, uint32_t cc, void *data, size_t len); 1304 1305/** 1306 * \brief CTR encryption + CBC-MAC with AES (`aes_ct` implementation). 1307 * 1308 * \param ctx context (already initialised). 1309 * \param ctr counter for CTR (16 bytes, updated). 1310 * \param cbcmac IV for CBC-MAC (updated). 1311 * \param data data to encrypt (updated). 1312 * \param len data length (in bytes, MUST be a multiple of 16). 1313 */ 1314void br_aes_ct_ctrcbc_encrypt(const br_aes_ct_ctrcbc_keys *ctx, 1315 void *ctr, void *cbcmac, void *data, size_t len); 1316 1317/** 1318 * \brief CTR decryption + CBC-MAC with AES (`aes_ct` implementation). 1319 * 1320 * \param ctx context (already initialised). 1321 * \param ctr counter for CTR (16 bytes, updated). 1322 * \param cbcmac IV for CBC-MAC (updated). 1323 * \param data data to decrypt (updated). 1324 * \param len data length (in bytes, MUST be a multiple of 16). 1325 */ 1326void br_aes_ct_ctrcbc_decrypt(const br_aes_ct_ctrcbc_keys *ctx, 1327 void *ctr, void *cbcmac, void *data, size_t len); 1328 1329/** 1330 * \brief CTR encryption/decryption with AES (`aes_ct` implementation). 1331 * 1332 * \param ctx context (already initialised). 1333 * \param ctr counter for CTR (16 bytes, updated). 1334 * \param data data to MAC (updated). 1335 * \param len data length (in bytes, MUST be a multiple of 16). 1336 */ 1337void br_aes_ct_ctrcbc_ctr(const br_aes_ct_ctrcbc_keys *ctx, 1338 void *ctr, void *data, size_t len); 1339 1340/** 1341 * \brief CBC-MAC with AES (`aes_ct` implementation). 1342 * 1343 * \param ctx context (already initialised). 1344 * \param cbcmac IV for CBC-MAC (updated). 1345 * \param data data to MAC (unmodified). 1346 * \param len data length (in bytes, MUST be a multiple of 16). 1347 */ 1348void br_aes_ct_ctrcbc_mac(const br_aes_ct_ctrcbc_keys *ctx, 1349 void *cbcmac, const void *data, size_t len); 1350 1351/* 1352 * 64-bit constant-time AES implementation. It is similar to 'aes_ct' 1353 * but uses 64-bit registers, making it about twice faster than 'aes_ct' 1354 * on 64-bit platforms, while remaining constant-time and with a similar 1355 * code size. (The doubling in performance is only for CBC decryption 1356 * and CTR mode; CBC encryption is non-parallel and cannot benefit from 1357 * the larger registers.) 1358 */ 1359 1360/** \brief AES block size (16 bytes). */ 1361#define br_aes_ct64_BLOCK_SIZE 16 1362 1363/** 1364 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC encryption). 1365 * 1366 * First field is a pointer to the vtable; it is set by the initialisation 1367 * function. Other fields are not supposed to be accessed by user code. 1368 */ 1369typedef struct { 1370 /** \brief Pointer to vtable for this context. */ 1371 const br_block_cbcenc_class *vtable; 1372#ifndef BR_DOXYGEN_IGNORE 1373 uint64_t skey[30]; 1374 unsigned num_rounds; 1375#endif 1376} br_aes_ct64_cbcenc_keys; 1377 1378/** 1379 * \brief Context for AES subkeys (`aes_ct64` implementation, CBC decryption). 1380 * 1381 * First field is a pointer to the vtable; it is set by the initialisation 1382 * function. Other fields are not supposed to be accessed by user code. 1383 */ 1384typedef struct { 1385 /** \brief Pointer to vtable for this context. */ 1386 const br_block_cbcdec_class *vtable; 1387#ifndef BR_DOXYGEN_IGNORE 1388 uint64_t skey[30]; 1389 unsigned num_rounds; 1390#endif 1391} br_aes_ct64_cbcdec_keys; 1392 1393/** 1394 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption 1395 * and decryption). 1396 * 1397 * First field is a pointer to the vtable; it is set by the initialisation 1398 * function. Other fields are not supposed to be accessed by user code. 1399 */ 1400typedef struct { 1401 /** \brief Pointer to vtable for this context. */ 1402 const br_block_ctr_class *vtable; 1403#ifndef BR_DOXYGEN_IGNORE 1404 uint64_t skey[30]; 1405 unsigned num_rounds; 1406#endif 1407} br_aes_ct64_ctr_keys; 1408 1409/** 1410 * \brief Context for AES subkeys (`aes_ct64` implementation, CTR encryption 1411 * and decryption + CBC-MAC). 1412 * 1413 * First field is a pointer to the vtable; it is set by the initialisation 1414 * function. Other fields are not supposed to be accessed by user code. 1415 */ 1416typedef struct { 1417 /** \brief Pointer to vtable for this context. */ 1418 const br_block_ctrcbc_class *vtable; 1419#ifndef BR_DOXYGEN_IGNORE 1420 uint64_t skey[30]; 1421 unsigned num_rounds; 1422#endif 1423} br_aes_ct64_ctrcbc_keys; 1424 1425/** 1426 * \brief Class instance for AES CBC encryption (`aes_ct64` implementation). 1427 */ 1428extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable; 1429 1430/** 1431 * \brief Class instance for AES CBC decryption (`aes_ct64` implementation). 1432 */ 1433extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable; 1434 1435/** 1436 * \brief Class instance for AES CTR encryption and decryption 1437 * (`aes_ct64` implementation). 1438 */ 1439extern const br_block_ctr_class br_aes_ct64_ctr_vtable; 1440 1441/** 1442 * \brief Class instance for AES CTR encryption/decryption + CBC-MAC 1443 * (`aes_ct64` implementation). 1444 */ 1445extern const br_block_ctrcbc_class br_aes_ct64_ctrcbc_vtable; 1446 1447/** 1448 * \brief Context initialisation (key schedule) for AES CBC encryption 1449 * (`aes_ct64` implementation). 1450 * 1451 * \param ctx context to initialise. 1452 * \param key secret key. 1453 * \param len secret key length (in bytes). 1454 */ 1455void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys *ctx, 1456 const void *key, size_t len); 1457 1458/** 1459 * \brief Context initialisation (key schedule) for AES CBC decryption 1460 * (`aes_ct64` implementation). 1461 * 1462 * \param ctx context to initialise. 1463 * \param key secret key. 1464 * \param len secret key length (in bytes). 1465 */ 1466void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys *ctx, 1467 const void *key, size_t len); 1468 1469/** 1470 * \brief Context initialisation (key schedule) for AES CTR encryption 1471 * and decryption (`aes_ct64` implementation). 1472 * 1473 * \param ctx context to initialise. 1474 * \param key secret key. 1475 * \param len secret key length (in bytes). 1476 */ 1477void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys *ctx, 1478 const void *key, size_t len); 1479 1480/** 1481 * \brief Context initialisation (key schedule) for AES CTR + CBC-MAC 1482 * (`aes_ct64` implementation). 1483 * 1484 * \param ctx context to initialise. 1485 * \param key secret key. 1486 * \param len secret key length (in bytes). 1487 */ 1488void br_aes_ct64_ctrcbc_init(br_aes_ct64_ctrcbc_keys *ctx, 1489 const void *key, size_t len); 1490 1491/** 1492 * \brief CBC encryption with AES (`aes_ct64` implementation). 1493 * 1494 * \param ctx context (already initialised). 1495 * \param iv IV (updated). 1496 * \param data data to encrypt (updated). 1497 * \param len data length (in bytes, MUST be multiple of 16). 1498 */ 1499void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys *ctx, void *iv, 1500 void *data, size_t len); 1501 1502/** 1503 * \brief CBC decryption with AES (`aes_ct64` implementation). 1504 * 1505 * \param ctx context (already initialised). 1506 * \param iv IV (updated). 1507 * \param data data to decrypt (updated). 1508 * \param len data length (in bytes, MUST be multiple of 16). 1509 */ 1510void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys *ctx, void *iv, 1511 void *data, size_t len); 1512 1513/** 1514 * \brief CTR encryption and decryption with AES (`aes_ct64` implementation). 1515 * 1516 * \param ctx context (already initialised). 1517 * \param iv IV (constant, 12 bytes). 1518 * \param cc initial block counter value. 1519 * \param data data to decrypt (updated). 1520 * \param len data length (in bytes). 1521 * \return new block counter value. 1522 */ 1523uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys *ctx, 1524 const void *iv, uint32_t cc, void *data, size_t len); 1525 1526/** 1527 * \brief CTR encryption + CBC-MAC with AES (`aes_ct64` implementation). 1528 * 1529 * \param ctx context (already initialised). 1530 * \param ctr counter for CTR (16 bytes, updated). 1531 * \param cbcmac IV for CBC-MAC (updated). 1532 * \param data data to encrypt (updated). 1533 * \param len data length (in bytes, MUST be a multiple of 16). 1534 */ 1535void br_aes_ct64_ctrcbc_encrypt(const br_aes_ct64_ctrcbc_keys *ctx, 1536 void *ctr, void *cbcmac, void *data, size_t len); 1537 1538/** 1539 * \brief CTR decryption + CBC-MAC with AES (`aes_ct64` implementation). 1540 * 1541 * \param ctx context (already initialised). 1542 * \param ctr counter for CTR (16 bytes, updated). 1543 * \param cbcmac IV for CBC-MAC (updated). 1544 * \param data data to decrypt (updated). 1545 * \param len data length (in bytes, MUST be a multiple of 16). 1546 */ 1547void br_aes_ct64_ctrcbc_decrypt(const br_aes_ct64_ctrcbc_keys *ctx, 1548 void *ctr, void *cbcmac, void *data, size_t len); 1549 1550/** 1551 * \brief CTR encryption/decryption with AES (`aes_ct64` implementation). 1552 * 1553 * \param ctx context (already initialised). 1554 * \param ctr counter for CTR (16 bytes, updated). 1555 * \param data data to MAC (updated). 1556 * \param len data length (in bytes, MUST be a multiple of 16). 1557 */ 1558void br_aes_ct64_ctrcbc_ctr(const br_aes_ct64_ctrcbc_keys *ctx, 1559 void *ctr, void *data, size_t len); 1560 1561/** 1562 * \brief CBC-MAC with AES (`aes_ct64` implementation). 1563 * 1564 * \param ctx context (already initialised). 1565 * \param cbcmac IV for CBC-MAC (updated). 1566 * \param data data to MAC (unmodified). 1567 * \param len data length (in bytes, MUST be a multiple of 16). 1568 */ 1569void br_aes_ct64_ctrcbc_mac(const br_aes_ct64_ctrcbc_keys *ctx, 1570 void *cbcmac, const void *data, size_t len); 1571 1572/* 1573 * AES implementation using AES-NI opcodes (x86 platform). 1574 */ 1575 1576/** \brief AES block size (16 bytes). */ 1577#define br_aes_x86ni_BLOCK_SIZE 16 1578 1579/** 1580 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC encryption). 1581 * 1582 * First field is a pointer to the vtable; it is set by the initialisation 1583 * function. Other fields are not supposed to be accessed by user code. 1584 */ 1585typedef struct { 1586 /** \brief Pointer to vtable for this context. */ 1587 const br_block_cbcenc_class *vtable; 1588#ifndef BR_DOXYGEN_IGNORE 1589 union { 1590 unsigned char skni[16 * 15]; 1591 } skey; 1592 unsigned num_rounds; 1593#endif 1594} br_aes_x86ni_cbcenc_keys; 1595 1596/** 1597 * \brief Context for AES subkeys (`aes_x86ni` implementation, CBC decryption). 1598 * 1599 * First field is a pointer to the vtable; it is set by the initialisation 1600 * function. Other fields are not supposed to be accessed by user code. 1601 */ 1602typedef struct { 1603 /** \brief Pointer to vtable for this context. */ 1604 const br_block_cbcdec_class *vtable; 1605#ifndef BR_DOXYGEN_IGNORE 1606 union { 1607 unsigned char skni[16 * 15]; 1608 } skey; 1609 unsigned num_rounds; 1610#endif 1611} br_aes_x86ni_cbcdec_keys; 1612 1613/** 1614 * \brief Context for AES subkeys (`aes_x86ni` implementation, CTR encryption 1615 * and decryption). 1616 * 1617 * First field is a pointer to the vtable; it is set by the initialisation 1618 * function. Other fields are not supposed to be accessed by user code. 1619 */ 1620typedef struct { 1621 /** \brief Pointer to vtable for this context. */ 1622 const br_block_ctr_class *vtable; 1623#ifndef BR_DOXYGEN_IGNORE 1624 union { 1625 unsigned char skni[16 * 15]; 1626 } skey; 1627 unsigned num_rounds; 1628#endif 1629} br_aes_x86ni_ctr_keys; 1630 1631/** 1632 * \brief Context for AES subkeys (`aes_x86ni` implementation, CTR encryption 1633 * and decryption + CBC-MAC). 1634 * 1635 * First field is a pointer to the vtable; it is set by the initialisation 1636 * function. Other fields are not supposed to be accessed by user code. 1637 */ 1638typedef struct { 1639 /** \brief Pointer to vtable for this context. */ 1640 const br_block_ctrcbc_class *vtable; 1641#ifndef BR_DOXYGEN_IGNORE 1642 union { 1643 unsigned char skni[16 * 15]; 1644 } skey; 1645 unsigned num_rounds; 1646#endif 1647} br_aes_x86ni_ctrcbc_keys; 1648 1649/** 1650 * \brief Class instance for AES CBC encryption (`aes_x86ni` implementation). 1651 * 1652 * Since this implementation might be omitted from the library, or the 1653 * AES opcode unavailable on the current CPU, a pointer to this class 1654 * instance should be obtained through `br_aes_x86ni_cbcenc_get_vtable()`. 1655 */ 1656extern const br_block_cbcenc_class br_aes_x86ni_cbcenc_vtable; 1657 1658/** 1659 * \brief Class instance for AES CBC decryption (`aes_x86ni` implementation). 1660 * 1661 * Since this implementation might be omitted from the library, or the 1662 * AES opcode unavailable on the current CPU, a pointer to this class 1663 * instance should be obtained through `br_aes_x86ni_cbcdec_get_vtable()`. 1664 */ 1665extern const br_block_cbcdec_class br_aes_x86ni_cbcdec_vtable; 1666 1667/** 1668 * \brief Class instance for AES CTR encryption and decryption 1669 * (`aes_x86ni` implementation). 1670 * 1671 * Since this implementation might be omitted from the library, or the 1672 * AES opcode unavailable on the current CPU, a pointer to this class 1673 * instance should be obtained through `br_aes_x86ni_ctr_get_vtable()`. 1674 */ 1675extern const br_block_ctr_class br_aes_x86ni_ctr_vtable; 1676 1677/** 1678 * \brief Class instance for AES CTR encryption/decryption + CBC-MAC 1679 * (`aes_x86ni` implementation). 1680 * 1681 * Since this implementation might be omitted from the library, or the 1682 * AES opcode unavailable on the current CPU, a pointer to this class 1683 * instance should be obtained through `br_aes_x86ni_ctrcbc_get_vtable()`. 1684 */ 1685extern const br_block_ctrcbc_class br_aes_x86ni_ctrcbc_vtable; 1686 1687/** 1688 * \brief Context initialisation (key schedule) for AES CBC encryption 1689 * (`aes_x86ni` implementation). 1690 * 1691 * \param ctx context to initialise. 1692 * \param key secret key. 1693 * \param len secret key length (in bytes). 1694 */ 1695void br_aes_x86ni_cbcenc_init(br_aes_x86ni_cbcenc_keys *ctx, 1696 const void *key, size_t len); 1697 1698/** 1699 * \brief Context initialisation (key schedule) for AES CBC decryption 1700 * (`aes_x86ni` implementation). 1701 * 1702 * \param ctx context to initialise. 1703 * \param key secret key. 1704 * \param len secret key length (in bytes). 1705 */ 1706void br_aes_x86ni_cbcdec_init(br_aes_x86ni_cbcdec_keys *ctx, 1707 const void *key, size_t len); 1708 1709/** 1710 * \brief Context initialisation (key schedule) for AES CTR encryption 1711 * and decryption (`aes_x86ni` implementation). 1712 * 1713 * \param ctx context to initialise. 1714 * \param key secret key. 1715 * \param len secret key length (in bytes). 1716 */ 1717void br_aes_x86ni_ctr_init(br_aes_x86ni_ctr_keys *ctx, 1718 const void *key, size_t len); 1719 1720/** 1721 * \brief Context initialisation (key schedule) for AES CTR + CBC-MAC 1722 * (`aes_x86ni` implementation). 1723 * 1724 * \param ctx context to initialise. 1725 * \param key secret key. 1726 * \param len secret key length (in bytes). 1727 */ 1728void br_aes_x86ni_ctrcbc_init(br_aes_x86ni_ctrcbc_keys *ctx, 1729 const void *key, size_t len); 1730 1731/** 1732 * \brief CBC encryption with AES (`aes_x86ni` implementation). 1733 * 1734 * \param ctx context (already initialised). 1735 * \param iv IV (updated). 1736 * \param data data to encrypt (updated). 1737 * \param len data length (in bytes, MUST be multiple of 16). 1738 */ 1739void br_aes_x86ni_cbcenc_run(const br_aes_x86ni_cbcenc_keys *ctx, void *iv, 1740 void *data, size_t len); 1741 1742/** 1743 * \brief CBC decryption with AES (`aes_x86ni` implementation). 1744 * 1745 * \param ctx context (already initialised). 1746 * \param iv IV (updated). 1747 * \param data data to decrypt (updated). 1748 * \param len data length (in bytes, MUST be multiple of 16). 1749 */ 1750void br_aes_x86ni_cbcdec_run(const br_aes_x86ni_cbcdec_keys *ctx, void *iv, 1751 void *data, size_t len); 1752 1753/** 1754 * \brief CTR encryption and decryption with AES (`aes_x86ni` implementation). 1755 * 1756 * \param ctx context (already initialised). 1757 * \param iv IV (constant, 12 bytes). 1758 * \param cc initial block counter value. 1759 * \param data data to decrypt (updated). 1760 * \param len data length (in bytes). 1761 * \return new block counter value. 1762 */ 1763uint32_t br_aes_x86ni_ctr_run(const br_aes_x86ni_ctr_keys *ctx, 1764 const void *iv, uint32_t cc, void *data, size_t len); 1765 1766/** 1767 * \brief CTR encryption + CBC-MAC with AES (`aes_x86ni` implementation). 1768 * 1769 * \param ctx context (already initialised). 1770 * \param ctr counter for CTR (16 bytes, updated). 1771 * \param cbcmac IV for CBC-MAC (updated). 1772 * \param data data to encrypt (updated). 1773 * \param len data length (in bytes, MUST be a multiple of 16). 1774 */ 1775void br_aes_x86ni_ctrcbc_encrypt(const br_aes_x86ni_ctrcbc_keys *ctx, 1776 void *ctr, void *cbcmac, void *data, size_t len); 1777 1778/** 1779 * \brief CTR decryption + CBC-MAC with AES (`aes_x86ni` implementation). 1780 * 1781 * \param ctx context (already initialised). 1782 * \param ctr counter for CTR (16 bytes, updated). 1783 * \param cbcmac IV for CBC-MAC (updated). 1784 * \param data data to decrypt (updated). 1785 * \param len data length (in bytes, MUST be a multiple of 16). 1786 */ 1787void br_aes_x86ni_ctrcbc_decrypt(const br_aes_x86ni_ctrcbc_keys *ctx, 1788 void *ctr, void *cbcmac, void *data, size_t len); 1789 1790/** 1791 * \brief CTR encryption/decryption with AES (`aes_x86ni` implementation). 1792 * 1793 * \param ctx context (already initialised). 1794 * \param ctr counter for CTR (16 bytes, updated). 1795 * \param data data to MAC (updated). 1796 * \param len data length (in bytes, MUST be a multiple of 16). 1797 */ 1798void br_aes_x86ni_ctrcbc_ctr(const br_aes_x86ni_ctrcbc_keys *ctx, 1799 void *ctr, void *data, size_t len); 1800 1801/** 1802 * \brief CBC-MAC with AES (`aes_x86ni` implementation). 1803 * 1804 * \param ctx context (already initialised). 1805 * \param cbcmac IV for CBC-MAC (updated). 1806 * \param data data to MAC (unmodified). 1807 * \param len data length (in bytes, MUST be a multiple of 16). 1808 */ 1809void br_aes_x86ni_ctrcbc_mac(const br_aes_x86ni_ctrcbc_keys *ctx, 1810 void *cbcmac, const void *data, size_t len); 1811 1812/** 1813 * \brief Obtain the `aes_x86ni` AES-CBC (encryption) implementation, if 1814 * available. 1815 * 1816 * This function returns a pointer to `br_aes_x86ni_cbcenc_vtable`, if 1817 * that implementation was compiled in the library _and_ the x86 AES 1818 * opcodes are available on the currently running CPU. If either of 1819 * these conditions is not met, then this function returns `NULL`. 1820 * 1821 * \return the `aes_x86ni` AES-CBC (encryption) implementation, or `NULL`. 1822 */ 1823const br_block_cbcenc_class *br_aes_x86ni_cbcenc_get_vtable(void); 1824 1825/** 1826 * \brief Obtain the `aes_x86ni` AES-CBC (decryption) implementation, if 1827 * available. 1828 * 1829 * This function returns a pointer to `br_aes_x86ni_cbcdec_vtable`, if 1830 * that implementation was compiled in the library _and_ the x86 AES 1831 * opcodes are available on the currently running CPU. If either of 1832 * these conditions is not met, then this function returns `NULL`. 1833 * 1834 * \return the `aes_x86ni` AES-CBC (decryption) implementation, or `NULL`. 1835 */ 1836const br_block_cbcdec_class *br_aes_x86ni_cbcdec_get_vtable(void); 1837 1838/** 1839 * \brief Obtain the `aes_x86ni` AES-CTR implementation, if available. 1840 * 1841 * This function returns a pointer to `br_aes_x86ni_ctr_vtable`, if 1842 * that implementation was compiled in the library _and_ the x86 AES 1843 * opcodes are available on the currently running CPU. If either of 1844 * these conditions is not met, then this function returns `NULL`. 1845 * 1846 * \return the `aes_x86ni` AES-CTR implementation, or `NULL`. 1847 */ 1848const br_block_ctr_class *br_aes_x86ni_ctr_get_vtable(void); 1849 1850/** 1851 * \brief Obtain the `aes_x86ni` AES-CTR + CBC-MAC implementation, if 1852 * available. 1853 * 1854 * This function returns a pointer to `br_aes_x86ni_ctrcbc_vtable`, if 1855 * that implementation was compiled in the library _and_ the x86 AES 1856 * opcodes are available on the currently running CPU. If either of 1857 * these conditions is not met, then this function returns `NULL`. 1858 * 1859 * \return the `aes_x86ni` AES-CTR implementation, or `NULL`. 1860 */ 1861const br_block_ctrcbc_class *br_aes_x86ni_ctrcbc_get_vtable(void); 1862 1863/* 1864 * AES implementation using POWER8 opcodes. 1865 */ 1866 1867/** \brief AES block size (16 bytes). */ 1868#define br_aes_pwr8_BLOCK_SIZE 16 1869 1870/** 1871 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC encryption). 1872 * 1873 * First field is a pointer to the vtable; it is set by the initialisation 1874 * function. Other fields are not supposed to be accessed by user code. 1875 */ 1876typedef struct { 1877 /** \brief Pointer to vtable for this context. */ 1878 const br_block_cbcenc_class *vtable; 1879#ifndef BR_DOXYGEN_IGNORE 1880 union { 1881 unsigned char skni[16 * 15]; 1882 } skey; 1883 unsigned num_rounds; 1884#endif 1885} br_aes_pwr8_cbcenc_keys; 1886 1887/** 1888 * \brief Context for AES subkeys (`aes_pwr8` implementation, CBC decryption). 1889 * 1890 * First field is a pointer to the vtable; it is set by the initialisation 1891 * function. Other fields are not supposed to be accessed by user code. 1892 */ 1893typedef struct { 1894 /** \brief Pointer to vtable for this context. */ 1895 const br_block_cbcdec_class *vtable; 1896#ifndef BR_DOXYGEN_IGNORE 1897 union { 1898 unsigned char skni[16 * 15]; 1899 } skey; 1900 unsigned num_rounds; 1901#endif 1902} br_aes_pwr8_cbcdec_keys; 1903 1904/** 1905 * \brief Context for AES subkeys (`aes_pwr8` implementation, CTR encryption 1906 * and decryption). 1907 * 1908 * First field is a pointer to the vtable; it is set by the initialisation 1909 * function. Other fields are not supposed to be accessed by user code. 1910 */ 1911typedef struct { 1912 /** \brief Pointer to vtable for this context. */ 1913 const br_block_ctr_class *vtable; 1914#ifndef BR_DOXYGEN_IGNORE 1915 union { 1916 unsigned char skni[16 * 15]; 1917 } skey; 1918 unsigned num_rounds; 1919#endif 1920} br_aes_pwr8_ctr_keys; 1921 1922/** 1923 * \brief Context for AES subkeys (`aes_pwr8` implementation, CTR encryption 1924 * and decryption + CBC-MAC). 1925 * 1926 * First field is a pointer to the vtable; it is set by the initialisation 1927 * function. Other fields are not supposed to be accessed by user code. 1928 */ 1929typedef struct { 1930 /** \brief Pointer to vtable for this context. */ 1931 const br_block_ctrcbc_class *vtable; 1932#ifndef BR_DOXYGEN_IGNORE 1933 union { 1934 unsigned char skni[16 * 15]; 1935 } skey; 1936 unsigned num_rounds; 1937#endif 1938} br_aes_pwr8_ctrcbc_keys; 1939 1940/** 1941 * \brief Class instance for AES CBC encryption (`aes_pwr8` implementation). 1942 * 1943 * Since this implementation might be omitted from the library, or the 1944 * AES opcode unavailable on the current CPU, a pointer to this class 1945 * instance should be obtained through `br_aes_pwr8_cbcenc_get_vtable()`. 1946 */ 1947extern const br_block_cbcenc_class br_aes_pwr8_cbcenc_vtable; 1948 1949/** 1950 * \brief Class instance for AES CBC decryption (`aes_pwr8` implementation). 1951 * 1952 * Since this implementation might be omitted from the library, or the 1953 * AES opcode unavailable on the current CPU, a pointer to this class 1954 * instance should be obtained through `br_aes_pwr8_cbcdec_get_vtable()`. 1955 */ 1956extern const br_block_cbcdec_class br_aes_pwr8_cbcdec_vtable; 1957 1958/** 1959 * \brief Class instance for AES CTR encryption and decryption 1960 * (`aes_pwr8` implementation). 1961 * 1962 * Since this implementation might be omitted from the library, or the 1963 * AES opcode unavailable on the current CPU, a pointer to this class 1964 * instance should be obtained through `br_aes_pwr8_ctr_get_vtable()`. 1965 */ 1966extern const br_block_ctr_class br_aes_pwr8_ctr_vtable; 1967 1968/** 1969 * \brief Class instance for AES CTR encryption/decryption + CBC-MAC 1970 * (`aes_pwr8` implementation). 1971 * 1972 * Since this implementation might be omitted from the library, or the 1973 * AES opcode unavailable on the current CPU, a pointer to this class 1974 * instance should be obtained through `br_aes_pwr8_ctrcbc_get_vtable()`. 1975 */ 1976extern const br_block_ctrcbc_class br_aes_pwr8_ctrcbc_vtable; 1977 1978/** 1979 * \brief Context initialisation (key schedule) for AES CBC encryption 1980 * (`aes_pwr8` implementation). 1981 * 1982 * \param ctx context to initialise. 1983 * \param key secret key. 1984 * \param len secret key length (in bytes). 1985 */ 1986void br_aes_pwr8_cbcenc_init(br_aes_pwr8_cbcenc_keys *ctx, 1987 const void *key, size_t len); 1988 1989/** 1990 * \brief Context initialisation (key schedule) for AES CBC decryption 1991 * (`aes_pwr8` implementation). 1992 * 1993 * \param ctx context to initialise. 1994 * \param key secret key. 1995 * \param len secret key length (in bytes). 1996 */ 1997void br_aes_pwr8_cbcdec_init(br_aes_pwr8_cbcdec_keys *ctx, 1998 const void *key, size_t len); 1999 2000/** 2001 * \brief Context initialisation (key schedule) for AES CTR encryption 2002 * and decryption (`aes_pwr8` implementation). 2003 * 2004 * \param ctx context to initialise. 2005 * \param key secret key. 2006 * \param len secret key length (in bytes). 2007 */ 2008void br_aes_pwr8_ctr_init(br_aes_pwr8_ctr_keys *ctx, 2009 const void *key, size_t len); 2010 2011/** 2012 * \brief Context initialisation (key schedule) for AES CTR + CBC-MAC 2013 * (`aes_pwr8` implementation). 2014 * 2015 * \param ctx context to initialise. 2016 * \param key secret key. 2017 * \param len secret key length (in bytes). 2018 */ 2019void br_aes_pwr8_ctrcbc_init(br_aes_pwr8_ctrcbc_keys *ctx, 2020 const void *key, size_t len); 2021 2022/** 2023 * \brief CBC encryption with AES (`aes_pwr8` implementation). 2024 * 2025 * \param ctx context (already initialised). 2026 * \param iv IV (updated). 2027 * \param data data to encrypt (updated). 2028 * \param len data length (in bytes, MUST be multiple of 16). 2029 */ 2030void br_aes_pwr8_cbcenc_run(const br_aes_pwr8_cbcenc_keys *ctx, void *iv, 2031 void *data, size_t len); 2032 2033/** 2034 * \brief CBC decryption with AES (`aes_pwr8` implementation). 2035 * 2036 * \param ctx context (already initialised). 2037 * \param iv IV (updated). 2038 * \param data data to decrypt (updated). 2039 * \param len data length (in bytes, MUST be multiple of 16). 2040 */ 2041void br_aes_pwr8_cbcdec_run(const br_aes_pwr8_cbcdec_keys *ctx, void *iv, 2042 void *data, size_t len); 2043 2044/** 2045 * \brief CTR encryption and decryption with AES (`aes_pwr8` implementation). 2046 * 2047 * \param ctx context (already initialised). 2048 * \param iv IV (constant, 12 bytes). 2049 * \param cc initial block counter value. 2050 * \param data data to decrypt (updated). 2051 * \param len data length (in bytes). 2052 * \return new block counter value. 2053 */ 2054uint32_t br_aes_pwr8_ctr_run(const br_aes_pwr8_ctr_keys *ctx, 2055 const void *iv, uint32_t cc, void *data, size_t len); 2056 2057/** 2058 * \brief CTR encryption + CBC-MAC with AES (`aes_pwr8` implementation). 2059 * 2060 * \param ctx context (already initialised). 2061 * \param ctr counter for CTR (16 bytes, updated). 2062 * \param cbcmac IV for CBC-MAC (updated). 2063 * \param data data to encrypt (updated). 2064 * \param len data length (in bytes, MUST be a multiple of 16). 2065 */ 2066void br_aes_pwr8_ctrcbc_encrypt(const br_aes_pwr8_ctrcbc_keys *ctx, 2067 void *ctr, void *cbcmac, void *data, size_t len); 2068 2069/** 2070 * \brief CTR decryption + CBC-MAC with AES (`aes_pwr8` implementation). 2071 * 2072 * \param ctx context (already initialised). 2073 * \param ctr counter for CTR (16 bytes, updated). 2074 * \param cbcmac IV for CBC-MAC (updated). 2075 * \param data data to decrypt (updated). 2076 * \param len data length (in bytes, MUST be a multiple of 16). 2077 */ 2078void br_aes_pwr8_ctrcbc_decrypt(const br_aes_pwr8_ctrcbc_keys *ctx, 2079 void *ctr, void *cbcmac, void *data, size_t len); 2080 2081/** 2082 * \brief CTR encryption/decryption with AES (`aes_pwr8` implementation). 2083 * 2084 * \param ctx context (already initialised). 2085 * \param ctr counter for CTR (16 bytes, updated). 2086 * \param data data to MAC (updated). 2087 * \param len data length (in bytes, MUST be a multiple of 16). 2088 */ 2089void br_aes_pwr8_ctrcbc_ctr(const br_aes_pwr8_ctrcbc_keys *ctx, 2090 void *ctr, void *data, size_t len); 2091 2092/** 2093 * \brief CBC-MAC with AES (`aes_pwr8` implementation). 2094 * 2095 * \param ctx context (already initialised). 2096 * \param cbcmac IV for CBC-MAC (updated). 2097 * \param data data to MAC (unmodified). 2098 * \param len data length (in bytes, MUST be a multiple of 16). 2099 */ 2100void br_aes_pwr8_ctrcbc_mac(const br_aes_pwr8_ctrcbc_keys *ctx, 2101 void *cbcmac, const void *data, size_t len); 2102 2103/** 2104 * \brief Obtain the `aes_pwr8` AES-CBC (encryption) implementation, if 2105 * available. 2106 * 2107 * This function returns a pointer to `br_aes_pwr8_cbcenc_vtable`, if 2108 * that implementation was compiled in the library _and_ the POWER8 2109 * crypto opcodes are available on the currently running CPU. If either 2110 * of these conditions is not met, then this function returns `NULL`. 2111 * 2112 * \return the `aes_pwr8` AES-CBC (encryption) implementation, or `NULL`. 2113 */ 2114const br_block_cbcenc_class *br_aes_pwr8_cbcenc_get_vtable(void); 2115 2116/** 2117 * \brief Obtain the `aes_pwr8` AES-CBC (decryption) implementation, if 2118 * available. 2119 * 2120 * This function returns a pointer to `br_aes_pwr8_cbcdec_vtable`, if 2121 * that implementation was compiled in the library _and_ the POWER8 2122 * crypto opcodes are available on the currently running CPU. If either 2123 * of these conditions is not met, then this function returns `NULL`. 2124 * 2125 * \return the `aes_pwr8` AES-CBC (decryption) implementation, or `NULL`. 2126 */ 2127const br_block_cbcdec_class *br_aes_pwr8_cbcdec_get_vtable(void); 2128 2129/** 2130 * \brief Obtain the `aes_pwr8` AES-CTR implementation, if available. 2131 * 2132 * This function returns a pointer to `br_aes_pwr8_ctr_vtable`, if that 2133 * implementation was compiled in the library _and_ the POWER8 crypto 2134 * opcodes are available on the currently running CPU. If either of 2135 * these conditions is not met, then this function returns `NULL`. 2136 * 2137 * \return the `aes_pwr8` AES-CTR implementation, or `NULL`. 2138 */ 2139const br_block_ctr_class *br_aes_pwr8_ctr_get_vtable(void); 2140 2141/** 2142 * \brief Obtain the `aes_pwr8` AES-CTR + CBC-MAC implementation, if 2143 * available. 2144 * 2145 * This function returns a pointer to `br_aes_pwr8_ctrcbc_vtable`, if 2146 * that implementation was compiled in the library _and_ the POWER8 AES 2147 * opcodes are available on the currently running CPU. If either of 2148 * these conditions is not met, then this function returns `NULL`. 2149 * 2150 * \return the `aes_pwr8` AES-CTR implementation, or `NULL`. 2151 */ 2152const br_block_ctrcbc_class *br_aes_pwr8_ctrcbc_get_vtable(void); 2153 2154/** 2155 * \brief Aggregate structure large enough to be used as context for 2156 * subkeys (CBC encryption) for all AES implementations. 2157 */ 2158typedef union { 2159 const br_block_cbcenc_class *vtable; 2160 br_aes_big_cbcenc_keys c_big; 2161 br_aes_small_cbcenc_keys c_small; 2162 br_aes_ct_cbcenc_keys c_ct; 2163 br_aes_ct64_cbcenc_keys c_ct64; 2164 br_aes_x86ni_cbcenc_keys c_x86ni; 2165 br_aes_pwr8_cbcenc_keys c_pwr8; 2166} br_aes_gen_cbcenc_keys; 2167 2168/** 2169 * \brief Aggregate structure large enough to be used as context for 2170 * subkeys (CBC decryption) for all AES implementations. 2171 */ 2172typedef union { 2173 const br_block_cbcdec_class *vtable; 2174 br_aes_big_cbcdec_keys c_big; 2175 br_aes_small_cbcdec_keys c_small; 2176 br_aes_ct_cbcdec_keys c_ct; 2177 br_aes_ct64_cbcdec_keys c_ct64; 2178 br_aes_x86ni_cbcdec_keys c_x86ni; 2179 br_aes_pwr8_cbcdec_keys c_pwr8; 2180} br_aes_gen_cbcdec_keys; 2181 2182/** 2183 * \brief Aggregate structure large enough to be used as context for 2184 * subkeys (CTR encryption and decryption) for all AES implementations. 2185 */ 2186typedef union { 2187 const br_block_ctr_class *vtable; 2188 br_aes_big_ctr_keys c_big; 2189 br_aes_small_ctr_keys c_small; 2190 br_aes_ct_ctr_keys c_ct; 2191 br_aes_ct64_ctr_keys c_ct64; 2192 br_aes_x86ni_ctr_keys c_x86ni; 2193 br_aes_pwr8_ctr_keys c_pwr8; 2194} br_aes_gen_ctr_keys; 2195 2196/** 2197 * \brief Aggregate structure large enough to be used as context for 2198 * subkeys (CTR encryption/decryption + CBC-MAC) for all AES implementations. 2199 */ 2200typedef union { 2201 const br_block_ctrcbc_class *vtable; 2202 br_aes_big_ctrcbc_keys c_big; 2203 br_aes_small_ctrcbc_keys c_small; 2204 br_aes_ct_ctrcbc_keys c_ct; 2205 br_aes_ct64_ctrcbc_keys c_ct64; 2206 br_aes_x86ni_ctrcbc_keys c_x86ni; 2207 br_aes_pwr8_ctrcbc_keys c_pwr8; 2208} br_aes_gen_ctrcbc_keys; 2209 2210/* 2211 * Traditional, table-based implementation for DES/3DES. Since tables are 2212 * used, cache-timing attacks are conceptually possible. 2213 */ 2214 2215/** \brief DES/3DES block size (8 bytes). */ 2216#define br_des_tab_BLOCK_SIZE 8 2217 2218/** 2219 * \brief Context for DES subkeys (`des_tab` implementation, CBC encryption). 2220 * 2221 * First field is a pointer to the vtable; it is set by the initialisation 2222 * function. Other fields are not supposed to be accessed by user code. 2223 */ 2224typedef struct { 2225 /** \brief Pointer to vtable for this context. */ 2226 const br_block_cbcenc_class *vtable; 2227#ifndef BR_DOXYGEN_IGNORE 2228 uint32_t skey[96]; 2229 unsigned num_rounds; 2230#endif 2231} br_des_tab_cbcenc_keys; 2232 2233/** 2234 * \brief Context for DES subkeys (`des_tab` implementation, CBC decryption). 2235 * 2236 * First field is a pointer to the vtable; it is set by the initialisation 2237 * function. Other fields are not supposed to be accessed by user code. 2238 */ 2239typedef struct { 2240 /** \brief Pointer to vtable for this context. */ 2241 const br_block_cbcdec_class *vtable; 2242#ifndef BR_DOXYGEN_IGNORE 2243 uint32_t skey[96]; 2244 unsigned num_rounds; 2245#endif 2246} br_des_tab_cbcdec_keys; 2247 2248/** 2249 * \brief Class instance for DES CBC encryption (`des_tab` implementation). 2250 */ 2251extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable; 2252 2253/** 2254 * \brief Class instance for DES CBC decryption (`des_tab` implementation). 2255 */ 2256extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable; 2257 2258/** 2259 * \brief Context initialisation (key schedule) for DES CBC encryption 2260 * (`des_tab` implementation). 2261 * 2262 * \param ctx context to initialise. 2263 * \param key secret key. 2264 * \param len secret key length (in bytes). 2265 */ 2266void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys *ctx, 2267 const void *key, size_t len); 2268 2269/** 2270 * \brief Context initialisation (key schedule) for DES CBC decryption 2271 * (`des_tab` implementation). 2272 * 2273 * \param ctx context to initialise. 2274 * \param key secret key. 2275 * \param len secret key length (in bytes). 2276 */ 2277void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys *ctx, 2278 const void *key, size_t len); 2279 2280/** 2281 * \brief CBC encryption with DES (`des_tab` implementation). 2282 * 2283 * \param ctx context (already initialised). 2284 * \param iv IV (updated). 2285 * \param data data to encrypt (updated). 2286 * \param len data length (in bytes, MUST be multiple of 8). 2287 */ 2288void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys *ctx, void *iv, 2289 void *data, size_t len); 2290 2291/** 2292 * \brief CBC decryption with DES (`des_tab` implementation). 2293 * 2294 * \param ctx context (already initialised). 2295 * \param iv IV (updated). 2296 * \param data data to decrypt (updated). 2297 * \param len data length (in bytes, MUST be multiple of 8). 2298 */ 2299void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys *ctx, void *iv, 2300 void *data, size_t len); 2301 2302/* 2303 * Constant-time implementation for DES/3DES. It is substantially slower 2304 * (by a factor of about 4x), but also immune to cache-timing attacks. 2305 */ 2306 2307/** \brief DES/3DES block size (8 bytes). */ 2308#define br_des_ct_BLOCK_SIZE 8 2309 2310/** 2311 * \brief Context for DES subkeys (`des_ct` implementation, CBC encryption). 2312 * 2313 * First field is a pointer to the vtable; it is set by the initialisation 2314 * function. Other fields are not supposed to be accessed by user code. 2315 */ 2316typedef struct { 2317 /** \brief Pointer to vtable for this context. */ 2318 const br_block_cbcenc_class *vtable; 2319#ifndef BR_DOXYGEN_IGNORE 2320 uint32_t skey[96]; 2321 unsigned num_rounds; 2322#endif 2323} br_des_ct_cbcenc_keys; 2324 2325/** 2326 * \brief Context for DES subkeys (`des_ct` implementation, CBC decryption). 2327 * 2328 * First field is a pointer to the vtable; it is set by the initialisation 2329 * function. Other fields are not supposed to be accessed by user code. 2330 */ 2331typedef struct { 2332 /** \brief Pointer to vtable for this context. */ 2333 const br_block_cbcdec_class *vtable; 2334#ifndef BR_DOXYGEN_IGNORE 2335 uint32_t skey[96]; 2336 unsigned num_rounds; 2337#endif 2338} br_des_ct_cbcdec_keys; 2339 2340/** 2341 * \brief Class instance for DES CBC encryption (`des_ct` implementation). 2342 */ 2343extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable; 2344 2345/** 2346 * \brief Class instance for DES CBC decryption (`des_ct` implementation). 2347 */ 2348extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable; 2349 2350/** 2351 * \brief Context initialisation (key schedule) for DES CBC encryption 2352 * (`des_ct` implementation). 2353 * 2354 * \param ctx context to initialise. 2355 * \param key secret key. 2356 * \param len secret key length (in bytes). 2357 */ 2358void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys *ctx, 2359 const void *key, size_t len); 2360 2361/** 2362 * \brief Context initialisation (key schedule) for DES CBC decryption 2363 * (`des_ct` implementation). 2364 * 2365 * \param ctx context to initialise. 2366 * \param key secret key. 2367 * \param len secret key length (in bytes). 2368 */ 2369void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys *ctx, 2370 const void *key, size_t len); 2371 2372/** 2373 * \brief CBC encryption with DES (`des_ct` implementation). 2374 * 2375 * \param ctx context (already initialised). 2376 * \param iv IV (updated). 2377 * \param data data to encrypt (updated). 2378 * \param len data length (in bytes, MUST be multiple of 8). 2379 */ 2380void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys *ctx, void *iv, 2381 void *data, size_t len); 2382 2383/** 2384 * \brief CBC decryption with DES (`des_ct` implementation). 2385 * 2386 * \param ctx context (already initialised). 2387 * \param iv IV (updated). 2388 * \param data data to decrypt (updated). 2389 * \param len data length (in bytes, MUST be multiple of 8). 2390 */ 2391void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys *ctx, void *iv, 2392 void *data, size_t len); 2393 2394/* 2395 * These structures are large enough to accommodate subkeys for all 2396 * DES/3DES implementations. 2397 */ 2398 2399/** 2400 * \brief Aggregate structure large enough to be used as context for 2401 * subkeys (CBC encryption) for all DES implementations. 2402 */ 2403typedef union { 2404 const br_block_cbcenc_class *vtable; 2405 br_des_tab_cbcenc_keys tab; 2406 br_des_ct_cbcenc_keys ct; 2407} br_des_gen_cbcenc_keys; 2408 2409/** 2410 * \brief Aggregate structure large enough to be used as context for 2411 * subkeys (CBC decryption) for all DES implementations. 2412 */ 2413typedef union { 2414 const br_block_cbcdec_class *vtable; 2415 br_des_tab_cbcdec_keys c_tab; 2416 br_des_ct_cbcdec_keys c_ct; 2417} br_des_gen_cbcdec_keys; 2418 2419/** 2420 * \brief Type for a ChaCha20 implementation. 2421 * 2422 * An implementation follows the description in RFC 7539: 2423 * 2424 * - Key is 256 bits (`key` points to exactly 32 bytes). 2425 * 2426 * - IV is 96 bits (`iv` points to exactly 12 bytes). 2427 * 2428 * - Block counter is over 32 bits and starts at value `cc`; the 2429 * resulting value is returned. 2430 * 2431 * Data (pointed to by `data`, of length `len`) is encrypted/decrypted 2432 * in place. If `len` is not a multiple of 64, then the excess bytes from 2433 * the last block processing are dropped (therefore, "chunked" processing 2434 * works only as long as each non-final chunk has a length multiple of 64). 2435 * 2436 * \param key secret key (32 bytes). 2437 * \param iv IV (12 bytes). 2438 * \param cc initial counter value. 2439 * \param data data to encrypt or decrypt. 2440 * \param len data length (in bytes). 2441 */ 2442typedef uint32_t (*br_chacha20_run)(const void *key, 2443 const void *iv, uint32_t cc, void *data, size_t len); 2444 2445/** 2446 * \brief ChaCha20 implementation (straightforward C code, constant-time). 2447 * 2448 * \see br_chacha20_run 2449 * 2450 * \param key secret key (32 bytes). 2451 * \param iv IV (12 bytes). 2452 * \param cc initial counter value. 2453 * \param data data to encrypt or decrypt. 2454 * \param len data length (in bytes). 2455 */ 2456uint32_t br_chacha20_ct_run(const void *key, 2457 const void *iv, uint32_t cc, void *data, size_t len); 2458 2459/** 2460 * \brief ChaCha20 implementation (SSE2 code, constant-time). 2461 * 2462 * This implementation is available only on x86 platforms, depending on 2463 * compiler support. Moreover, in 32-bit mode, it might not actually run, 2464 * if the underlying hardware does not implement the SSE2 opcode (in 2465 * 64-bit mode, SSE2 is part of the ABI, so if the code could be compiled 2466 * at all, then it can run). Use `br_chacha20_sse2_get()` to safely obtain 2467 * a pointer to that function. 2468 * 2469 * \see br_chacha20_run 2470 * 2471 * \param key secret key (32 bytes). 2472 * \param iv IV (12 bytes). 2473 * \param cc initial counter value. 2474 * \param data data to encrypt or decrypt. 2475 * \param len data length (in bytes). 2476 */ 2477uint32_t br_chacha20_sse2_run(const void *key, 2478 const void *iv, uint32_t cc, void *data, size_t len); 2479 2480/** 2481 * \brief Obtain the `sse2` ChaCha20 implementation, if available. 2482 * 2483 * This function returns a pointer to `br_chacha20_sse2_run`, if 2484 * that implementation was compiled in the library _and_ the SSE2 2485 * opcodes are available on the currently running CPU. If either of 2486 * these conditions is not met, then this function returns `0`. 2487 * 2488 * \return the `sse2` ChaCha20 implementation, or `0`. 2489 */ 2490br_chacha20_run br_chacha20_sse2_get(void); 2491 2492/** 2493 * \brief Type for a ChaCha20+Poly1305 AEAD implementation. 2494 * 2495 * The provided data is encrypted or decrypted with ChaCha20. The 2496 * authentication tag is computed on the concatenation of the 2497 * additional data and the ciphertext, with the padding and lengths 2498 * as described in RFC 7539 (section 2.8). 2499 * 2500 * After decryption, the caller is responsible for checking that the 2501 * computed tag matches the expected value. 2502 * 2503 * \param key secret key (32 bytes). 2504 * \param iv nonce (12 bytes). 2505 * \param data data to encrypt or decrypt. 2506 * \param len data length (in bytes). 2507 * \param aad additional authenticated data. 2508 * \param aad_len length of additional authenticated data (in bytes). 2509 * \param tag output buffer for the authentication tag. 2510 * \param ichacha implementation of ChaCha20. 2511 * \param encrypt non-zero for encryption, zero for decryption. 2512 */ 2513typedef void (*br_poly1305_run)(const void *key, const void *iv, 2514 void *data, size_t len, const void *aad, size_t aad_len, 2515 void *tag, br_chacha20_run ichacha, int encrypt); 2516 2517/** 2518 * \brief ChaCha20+Poly1305 AEAD implementation (mixed 32-bit multiplications). 2519 * 2520 * \see br_poly1305_run 2521 * 2522 * \param key secret key (32 bytes). 2523 * \param iv nonce (12 bytes). 2524 * \param data data to encrypt or decrypt. 2525 * \param len data length (in bytes). 2526 * \param aad additional authenticated data. 2527 * \param aad_len length of additional authenticated data (in bytes). 2528 * \param tag output buffer for the authentication tag. 2529 * \param ichacha implementation of ChaCha20. 2530 * \param encrypt non-zero for encryption, zero for decryption. 2531 */ 2532void br_poly1305_ctmul_run(const void *key, const void *iv, 2533 void *data, size_t len, const void *aad, size_t aad_len, 2534 void *tag, br_chacha20_run ichacha, int encrypt); 2535 2536/** 2537 * \brief ChaCha20+Poly1305 AEAD implementation (pure 32-bit multiplications). 2538 * 2539 * \see br_poly1305_run 2540 * 2541 * \param key secret key (32 bytes). 2542 * \param iv nonce (12 bytes). 2543 * \param data data to encrypt or decrypt. 2544 * \param len data length (in bytes). 2545 * \param aad additional authenticated data. 2546 * \param aad_len length of additional authenticated data (in bytes). 2547 * \param tag output buffer for the authentication tag. 2548 * \param ichacha implementation of ChaCha20. 2549 * \param encrypt non-zero for encryption, zero for decryption. 2550 */ 2551void br_poly1305_ctmul32_run(const void *key, const void *iv, 2552 void *data, size_t len, const void *aad, size_t aad_len, 2553 void *tag, br_chacha20_run ichacha, int encrypt); 2554 2555/** 2556 * \brief ChaCha20+Poly1305 AEAD implementation (i15). 2557 * 2558 * This implementation relies on the generic big integer code "i15" 2559 * (which uses pure 32-bit multiplications). As such, it may save a 2560 * little code footprint in a context where "i15" is already included 2561 * (e.g. for elliptic curves or for RSA); however, it is also 2562 * substantially slower than the ctmul and ctmul32 implementations. 2563 * 2564 * \see br_poly1305_run 2565 * 2566 * \param key secret key (32 bytes). 2567 * \param iv nonce (12 bytes). 2568 * \param data data to encrypt or decrypt. 2569 * \param len data length (in bytes). 2570 * \param aad additional authenticated data. 2571 * \param aad_len length of additional authenticated data (in bytes). 2572 * \param tag output buffer for the authentication tag. 2573 * \param ichacha implementation of ChaCha20. 2574 * \param encrypt non-zero for encryption, zero for decryption. 2575 */ 2576void br_poly1305_i15_run(const void *key, const void *iv, 2577 void *data, size_t len, const void *aad, size_t aad_len, 2578 void *tag, br_chacha20_run ichacha, int encrypt); 2579 2580/** 2581 * \brief ChaCha20+Poly1305 AEAD implementation (ctmulq). 2582 * 2583 * This implementation uses 64-bit multiplications (result over 128 bits). 2584 * It is available only on platforms that offer such a primitive (in 2585 * practice, 64-bit architectures). Use `br_poly1305_ctmulq_get()` to 2586 * dynamically obtain a pointer to that function, or 0 if not supported. 2587 * 2588 * \see br_poly1305_run 2589 * 2590 * \param key secret key (32 bytes). 2591 * \param iv nonce (12 bytes). 2592 * \param data data to encrypt or decrypt. 2593 * \param len data length (in bytes). 2594 * \param aad additional authenticated data. 2595 * \param aad_len length of additional authenticated data (in bytes). 2596 * \param tag output buffer for the authentication tag. 2597 * \param ichacha implementation of ChaCha20. 2598 * \param encrypt non-zero for encryption, zero for decryption. 2599 */ 2600void br_poly1305_ctmulq_run(const void *key, const void *iv, 2601 void *data, size_t len, const void *aad, size_t aad_len, 2602 void *tag, br_chacha20_run ichacha, int encrypt); 2603 2604/** 2605 * \brief Get the ChaCha20+Poly1305 "ctmulq" implementation, if available. 2606 * 2607 * This function returns a pointer to the `br_poly1305_ctmulq_run()` 2608 * function if supported on the current platform; otherwise, it returns 0. 2609 * 2610 * \return the ctmulq ChaCha20+Poly1305 implementation, or 0. 2611 */ 2612br_poly1305_run br_poly1305_ctmulq_get(void); 2613 2614#ifdef __cplusplus 2615} 2616#endif 2617 2618#endif 2619