_ Git - BearSSL/blob - inc/bearssl_block.h

   1 /*
   2  * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining
   5  * a copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sublicense, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 #ifndef BR_BEARSSL_BLOCK_H__
  26 #define BR_BEARSSL_BLOCK_H__
  27
  28 #include <stddef.h>
  29 #include <stdint.h>
  30
  31 /*
  32  * Block Ciphers
  33  * -------------
  34  *
  35  * For a block cipher implementation, up to three separate sets of
  36  * functions are provided, for CBC encryption, CBC decryption, and CTR
  37  * encryption/decryption. Each set has its own context structure,
  38  * initialized with the encryption key. Each set of functions is
  39  * provided both as named functions, and through an OOP interface.
  40  *
  41  * For CBC encryption and decryption, the data to encrypt or decrypt is
  42  * referenced as a sequence of blocks. The implementations assume that
  43  * there is no partial block; no padding is applied or removed. The
  44  * caller is responsible for handling any kind of padding.
  45  *
  46  * Function for CTR encryption are defined only for block ciphers with
  47  * blocks of 16 bytes or more (i.e. AES, but not DES/3DES).
  48  *
  49  * Each implemented block cipher is identified by an "internal name"
  50  * from which are derived the names of structures and functions that
  51  * implement the cipher. For the block cipher of internal name "xxx",
  52  * the following are defined:
  53  *
  54  * br_xxx_BLOCK_SIZE
  55  *    A macro that evaluates to the block size (in bytes) of the
  56  *    cipher. For all implemented block ciphers, this value is a
  57  *    power of two.
  58  *
  59  * br_xxx_cbcenc_keys
  60  *    Context structure that contains the subkeys resulting from the key
  61  *    expansion. These subkeys are appropriate for CBC encryption. The
  62  *    structure first field is called 'vtable' and points to the
  63  *    appropriate OOP structure.
  64  *
  65  * br_xxx_cbcenc_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)
  66  *    Perform key expansion: subkeys for CBC encryption are computed and
  67  *    written in the provided context structure. The key length MUST be
  68  *    adequate for the implemented block cipher. This function also sets
  69  *    the 'vtable' field.
  70  *
  71  * br_xxx_cbcenc_run(const br_xxx_cbcenc_keys *ctx,
  72  *                   void *iv, void *data, size_t len)
  73  *    Perform CBC encryption of 'len' bytes, in place. The encrypted data
  74  *    replaces the cleartext. 'len' MUST be a multiple of the block length
  75  *    (if it is not, the function may loop forever or overflow a buffer).
  76  *    The IV is provided with the 'iv' pointer; it is also updated with
  77  *    a copy of the last encrypted block.
  78  *
  79  * br_xxx_cbcdec_keys
  80  *    Context structure that contains the subkeys resulting from the key
  81  *    expansion. These subkeys are appropriate for CBC decryption. The
  82  *    structure first field is called 'vtable' and points to the
  83  *    appropriate OOP structure.
  84  *
  85  * br_xxx_cbcdec_init(br_xxx_cbcenc_keys *ctx, const void *key, size_t len)
  86  *    Perform key expansion: subkeys for CBC decryption are computed and
  87  *    written in the provided context structure. The key length MUST be
  88  *    adequate for the implemented block cipher. This function also sets
  89  *    the 'vtable' field.
  90  *
  91  * br_xxx_cbcdec_run(const br_xxx_cbcdec_keys *ctx,
  92  *                   void *iv, void *data, size_t num_blocks)
  93  *    Perform CBC decryption of 'len' bytes, in place. The decrypted data
  94  *    replaces the ciphertext. 'len' MUST be a multiple of the block length
  95  *    (if it is not, the function may loop forever or overflow a buffer).
  96  *    The IV is provided with the 'iv' pointer; it is also updated with
  97  *    a copy of the last encrypted block.
  98  *
  99  * br_xxx_ctr_keys
 100  *    Context structure that contains the subkeys resulting from the key
 101  *    expansion. These subkeys are appropriate for CTR encryption and
 102  *    decryption. The structure first field is called 'vtable' and
 103  *    points to the appropriate OOP structure.
 104  *
 105  * br_xxx_ctr_init(br_xxx_ctr_keys *ctx, const void *key, size_t len)
 106  *    Perform key expansion: subkeys for CTR encryption and decryption
 107  *    are computed and written in the provided context structure. The
 108  *    key length MUST be adequate for the implemented block cipher. This
 109  *    function also sets the 'vtable' field.
 110  *
 111  * br_xxx_ctr_run(const br_xxx_ctr_keys *ctx, const void *iv,
 112  *                uint32_t cc, void *data, size_t len) [returns uint32_t]
 113  *    Perform CTR encryption/decryption of some data. Processing is done
 114  *    "in place" (the output data replaces the input data). This function
 115  *    implements the "standard incrementing function" from NIST SP800-38A,
 116  *    annex B: the IV length shall be 4 bytes less than the block size
 117  *    (i.e. 12 bytes for AES) and the counter is the 32-bit value starting
 118  *    with 'cc'. The data length ('len') is not necessarily a multiple of
 119  *    the block size. The new counter value is returned, which supports
 120  *    chunked processing, provided that each chunk length (except possibly
 121  *    the last one) is a multiple of the block size.
 122  *
 123  *
 124  * It shall be noted that the key expansion functions return 'void'. If
 125  * the provided key length is not allowed, then there will be no error
 126  * reporting; implementations need not validate the key length, thus an
 127  * invalid key length may result in undefined behaviour (e.g. buffer
 128  * overflow).
 129  *
 130  * Subkey structures contain no interior pointer, and no external
 131  * resources are allocated upon key expansion. They can thus be
 132  * discarded without any explicit deallocation.
 133  *
 134  *
 135  * Object-oriented API: each context structure begins with a field
 136  * (called 'vtable') that points to an instance of a structure that
 137  * references the relevant functions through pointers. Each such
 138  * structure contains the following:
 139  *
 140  *   context_size     size (in bytes) of the context structure for subkeys
 141  *   block_size       cipher block size (in bytes)
 142  *   log_block_size   base-2 logarithm of cipher block size
 143  *   init             pointer to the key expansion function
 144  *   run              pointer to the encryption/decryption function
 145  *
 146  * Static, constant instances of these structures are defined, under
 147  * the names:
 148  *
 149  *   br_xxx_cbcenc_vtable
 150  *   br_xxx_cbcdec_vtable
 151  *   br_xxx_ctr_vtable
 152  *
 153  *
 154  * Implemented Block Ciphers
 155  * -------------------------
 156  *
 157  *   Function   Name         Allowed key lengths (bytes)
 158  *
 159  *   AES        aes_ct       16, 24 and 32
 160  *   AES        aes_ct64     16, 24 and 32
 161  *   AES        aes_big      16, 24 and 32
 162  *   AES        aes_small    16, 24 and 32
 163  *   DES        des_ct       8, 16 and 24
 164  *   DES        des_tab      8, 16 and 24
 165  *
 166  * 'aes_big' is a "classical" AES implementation, using tables. It
 167  * is fast but not constant-time, since it makes data-dependent array
 168  * accesses.
 169  *
 170  * 'aes_small' is an AES implementation optimized for code size. It
 171  * is substantially slower than 'aes_big'; it is not constant-time
 172  * either.
 173  *
 174  * 'aes_ct' is a constant-time implementation of AES; its code is about
 175  * as big as that of 'aes_big', while its performance is comparable to
 176  * that of 'aes_small'. However, it is constant-time. This
 177  * implementation should thus be considered to be the "default" AES in
 178  * BearSSL, to be used unless the operational context guarantees that a
 179  * non-constant-time implementation is safe, or an architecture-specific
 180  * constant-time implementation can be used (e.g. using dedicated
 181  * hardware opcodes).
 182  *
 183  * 'aes_ct64' is another constant-time implementation of AES. It is
 184  * similar to 'aes_ct' but uses 64-bit values, for faster processing
 185  * on 64-bit machines.
 186  *
 187  * 'des_tab' is a classic, table-based implementation of DES/3DES. It
 188  * is not constant-time.
 189  *
 190  * 'des_ct' is an constant-time implementation of DES/3DES. It is
 191  * substantially slower than 'des_tab'.
 192  */
 193
 194 typedef struct br_block_cbcenc_class_ br_block_cbcenc_class;
 195 struct br_block_cbcenc_class_ {
 196         size_t context_size;
 197         unsigned block_size;
 198         unsigned log_block_size;
 199         void (*init)(const br_block_cbcenc_class **ctx,
 200                 const void *key, size_t key_len);
 201         void (*run)(const br_block_cbcenc_class *const *ctx,
 202                 void *iv, void *data, size_t len);
 203 };
 204
 205 typedef struct br_block_cbcdec_class_ br_block_cbcdec_class;
 206 struct br_block_cbcdec_class_ {
 207         size_t context_size;
 208         unsigned block_size;
 209         unsigned log_block_size;
 210         void (*init)(const br_block_cbcdec_class **ctx,
 211                 const void *key, size_t key_len);
 212         void (*run)(const br_block_cbcdec_class *const *ctx,
 213                 void *iv, void *data, size_t len);
 214 };
 215
 216 typedef struct br_block_ctr_class_ br_block_ctr_class;
 217 struct br_block_ctr_class_ {
 218         size_t context_size;
 219         unsigned block_size;
 220         unsigned log_block_size;
 221         void (*init)(const br_block_ctr_class **ctx,
 222                 const void *key, size_t key_len);
 223         uint32_t (*run)(const br_block_ctr_class *const *ctx,
 224                 const void *iv, uint32_t cc, void *data, size_t len);
 225 };
 226
 227 /*
 228  * Traditional, table-based AES implementation. It is fast, but uses
 229  * internal tables (in particular a 1 kB table for encryption, another
 230  * 1 kB table for decryption, and a 256-byte table for key schedule),
 231  * and it is not constant-time. In contexts where cache-timing attacks
 232  * apply, this implementation may leak the secret key.
 233  */
 234 #define br_aes_big_BLOCK_SIZE   16
 235 typedef struct {
 236         const br_block_cbcenc_class *vtable;
 237         uint32_t skey[60];
 238         unsigned num_rounds;
 239 } br_aes_big_cbcenc_keys;
 240 typedef struct {
 241         const br_block_cbcdec_class *vtable;
 242         uint32_t skey[60];
 243         unsigned num_rounds;
 244 } br_aes_big_cbcdec_keys;
 245 typedef struct {
 246         const br_block_ctr_class *vtable;
 247         uint32_t skey[60];
 248         unsigned num_rounds;
 249 } br_aes_big_ctr_keys;
 250 extern const br_block_cbcenc_class br_aes_big_cbcenc_vtable;
 251 extern const br_block_cbcdec_class br_aes_big_cbcdec_vtable;
 252 extern const br_block_ctr_class br_aes_big_ctr_vtable;
 253 void br_aes_big_cbcenc_init(br_aes_big_cbcenc_keys *ctx,
 254         const void *key, size_t len);
 255 void br_aes_big_cbcdec_init(br_aes_big_cbcdec_keys *ctx,
 256         const void *key, size_t len);
 257 void br_aes_big_ctr_init(br_aes_big_ctr_keys *ctx,
 258         const void *key, size_t len);
 259 void br_aes_big_cbcenc_run(const br_aes_big_cbcenc_keys *ctx, void *iv,
 260         void *data, size_t len);
 261 void br_aes_big_cbcdec_run(const br_aes_big_cbcdec_keys *ctx, void *iv,
 262         void *data, size_t len);
 263 uint32_t br_aes_big_ctr_run(const br_aes_big_ctr_keys *ctx,
 264         const void *iv, uint32_t cc, void *data, size_t len);
 265
 266 /*
 267  * AES implementation optimized for size. It is slower than the
 268  * traditional table-based AES implementation, but requires much less
 269  * code. It still uses data-dependent table accesses (albeit within a
 270  * much smaller 256-byte table), which makes it conceptually vulnerable
 271  * to cache-timing attacks.
 272  */
 273 #define br_aes_small_BLOCK_SIZE   16
 274 typedef struct {
 275         const br_block_cbcenc_class *vtable;
 276         uint32_t skey[60];
 277         unsigned num_rounds;
 278 } br_aes_small_cbcenc_keys;
 279 typedef struct {
 280         const br_block_cbcdec_class *vtable;
 281         uint32_t skey[60];
 282         unsigned num_rounds;
 283 } br_aes_small_cbcdec_keys;
 284 typedef struct {
 285         const br_block_ctr_class *vtable;
 286         uint32_t skey[60];
 287         unsigned num_rounds;
 288 } br_aes_small_ctr_keys;
 289 extern const br_block_cbcenc_class br_aes_small_cbcenc_vtable;
 290 extern const br_block_cbcdec_class br_aes_small_cbcdec_vtable;
 291 extern const br_block_ctr_class br_aes_small_ctr_vtable;
 292 void br_aes_small_cbcenc_init(br_aes_small_cbcenc_keys *ctx,
 293         const void *key, size_t len);
 294 void br_aes_small_cbcdec_init(br_aes_small_cbcdec_keys *ctx,
 295         const void *key, size_t len);
 296 void br_aes_small_ctr_init(br_aes_small_ctr_keys *ctx,
 297         const void *key, size_t len);
 298 void br_aes_small_cbcenc_run(const br_aes_small_cbcenc_keys *ctx, void *iv,
 299         void *data, size_t len);
 300 void br_aes_small_cbcdec_run(const br_aes_small_cbcdec_keys *ctx, void *iv,
 301         void *data, size_t len);
 302 uint32_t br_aes_small_ctr_run(const br_aes_small_ctr_keys *ctx,
 303         const void *iv, uint32_t cc, void *data, size_t len);
 304
 305 /*
 306  * Constant-time AES implementation. Its size is similar to that of
 307  * 'aes_big', and its performance is similar to that of 'aes_small' (faster
 308  * decryption, slower encryption). However, it is constant-time, i.e.
 309  * immune to cache-timing and similar attacks.
 310  */
 311 #define br_aes_ct_BLOCK_SIZE   16
 312 typedef struct {
 313         const br_block_cbcenc_class *vtable;
 314         uint32_t skey[60];
 315         unsigned num_rounds;
 316 } br_aes_ct_cbcenc_keys;
 317 typedef struct {
 318         const br_block_cbcdec_class *vtable;
 319         uint32_t skey[60];
 320         unsigned num_rounds;
 321 } br_aes_ct_cbcdec_keys;
 322 typedef struct {
 323         const br_block_ctr_class *vtable;
 324         uint32_t skey[60];
 325         unsigned num_rounds;
 326 } br_aes_ct_ctr_keys;
 327 extern const br_block_cbcenc_class br_aes_ct_cbcenc_vtable;
 328 extern const br_block_cbcdec_class br_aes_ct_cbcdec_vtable;
 329 extern const br_block_ctr_class br_aes_ct_ctr_vtable;
 330 void br_aes_ct_cbcenc_init(br_aes_ct_cbcenc_keys *ctx,
 331         const void *key, size_t len);
 332 void br_aes_ct_cbcdec_init(br_aes_ct_cbcdec_keys *ctx,
 333         const void *key, size_t len);
 334 void br_aes_ct_ctr_init(br_aes_ct_ctr_keys *ctx,
 335         const void *key, size_t len);
 336 void br_aes_ct_cbcenc_run(const br_aes_ct_cbcenc_keys *ctx, void *iv,
 337         void *data, size_t len);
 338 void br_aes_ct_cbcdec_run(const br_aes_ct_cbcdec_keys *ctx, void *iv,
 339         void *data, size_t len);
 340 uint32_t br_aes_ct_ctr_run(const br_aes_ct_ctr_keys *ctx,
 341         const void *iv, uint32_t cc, void *data, size_t len);
 342
 343 /*
 344  * 64-bit constant-time AES implementation. It is similar to 'aes_ct'
 345  * but uses 64-bit registers, making it about twice faster than 'aes_ct'
 346  * on 64-bit platforms, while remaining constant-time and with a similar
 347  * code size. (The doubling in performance is only for CBC decryption
 348  * and CTR mode; CBC encryption is non-parallel and cannot benefit from
 349  * the larger registers.)
 350  */
 351 #define br_aes_ct64_BLOCK_SIZE   16
 352 typedef struct {
 353         const br_block_cbcenc_class *vtable;
 354         uint64_t skey[30];
 355         unsigned num_rounds;
 356 } br_aes_ct64_cbcenc_keys;
 357 typedef struct {
 358         const br_block_cbcdec_class *vtable;
 359         uint64_t skey[30];
 360         unsigned num_rounds;
 361 } br_aes_ct64_cbcdec_keys;
 362 typedef struct {
 363         const br_block_ctr_class *vtable;
 364         uint64_t skey[30];
 365         unsigned num_rounds;
 366 } br_aes_ct64_ctr_keys;
 367 extern const br_block_cbcenc_class br_aes_ct64_cbcenc_vtable;
 368 extern const br_block_cbcdec_class br_aes_ct64_cbcdec_vtable;
 369 extern const br_block_ctr_class br_aes_ct64_ctr_vtable;
 370 void br_aes_ct64_cbcenc_init(br_aes_ct64_cbcenc_keys *ctx,
 371         const void *key, size_t len);
 372 void br_aes_ct64_cbcdec_init(br_aes_ct64_cbcdec_keys *ctx,
 373         const void *key, size_t len);
 374 void br_aes_ct64_ctr_init(br_aes_ct64_ctr_keys *ctx,
 375         const void *key, size_t len);
 376 void br_aes_ct64_cbcenc_run(const br_aes_ct64_cbcenc_keys *ctx, void *iv,
 377         void *data, size_t len);
 378 void br_aes_ct64_cbcdec_run(const br_aes_ct64_cbcdec_keys *ctx, void *iv,
 379         void *data, size_t len);
 380 uint32_t br_aes_ct64_ctr_run(const br_aes_ct64_ctr_keys *ctx,
 381         const void *iv, uint32_t cc, void *data, size_t len);
 382
 383 /*
 384  * These structures are large enough to accommodate subkeys for all
 385  * AES implementations.
 386  */
 387 typedef union {
 388         const br_block_cbcenc_class *vtable;
 389         br_aes_big_cbcenc_keys big;
 390         br_aes_small_cbcenc_keys small;
 391         br_aes_ct_cbcenc_keys ct;
 392         br_aes_ct64_cbcenc_keys ct64;
 393 } br_aes_gen_cbcenc_keys;
 394 typedef union {
 395         const br_block_cbcdec_class *vtable;
 396         br_aes_big_cbcdec_keys big;
 397         br_aes_small_cbcdec_keys small;
 398         br_aes_ct_cbcdec_keys ct;
 399         br_aes_ct64_cbcdec_keys ct64;
 400 } br_aes_gen_cbcdec_keys;
 401 typedef union {
 402         const br_block_ctr_class *vtable;
 403         br_aes_big_ctr_keys big;
 404         br_aes_small_ctr_keys small;
 405         br_aes_ct_ctr_keys ct;
 406         br_aes_ct64_ctr_keys ct64;
 407 } br_aes_gen_ctr_keys;
 408
 409 /*
 410  * Traditional, table-based implementation for DES/3DES. Since tables are
 411  * used, cache-timing attacks are conceptually possible.
 412  */
 413 #define br_des_tab_BLOCK_SIZE   8
 414 typedef struct {
 415         const br_block_cbcenc_class *vtable;
 416         uint32_t skey[96];
 417         unsigned num_rounds;
 418 } br_des_tab_cbcenc_keys;
 419 typedef struct {
 420         const br_block_cbcdec_class *vtable;
 421         uint32_t skey[96];
 422         unsigned num_rounds;
 423 } br_des_tab_cbcdec_keys;
 424 extern const br_block_cbcenc_class br_des_tab_cbcenc_vtable;
 425 extern const br_block_cbcdec_class br_des_tab_cbcdec_vtable;
 426 void br_des_tab_cbcenc_init(br_des_tab_cbcenc_keys *ctx,
 427         const void *key, size_t len);
 428 void br_des_tab_cbcdec_init(br_des_tab_cbcdec_keys *ctx,
 429         const void *key, size_t len);
 430 void br_des_tab_cbcenc_run(const br_des_tab_cbcenc_keys *ctx, void *iv,
 431         void *data, size_t len);
 432 void br_des_tab_cbcdec_run(const br_des_tab_cbcdec_keys *ctx, void *iv,
 433         void *data, size_t len);
 434
 435 /*
 436  * Constant-time implementation for DES/3DES. It is substantially slower
 437  * (by a factor of about 4x), but also immune to cache-timing attacks.
 438  */
 439 #define br_des_ct_BLOCK_SIZE   8
 440 typedef struct {
 441         const br_block_cbcenc_class *vtable;
 442         uint32_t skey[96];
 443         unsigned num_rounds;
 444 } br_des_ct_cbcenc_keys;
 445 typedef struct {
 446         const br_block_cbcdec_class *vtable;
 447         uint32_t skey[96];
 448         unsigned num_rounds;
 449 } br_des_ct_cbcdec_keys;
 450 extern const br_block_cbcenc_class br_des_ct_cbcenc_vtable;
 451 extern const br_block_cbcdec_class br_des_ct_cbcdec_vtable;
 452 void br_des_ct_cbcenc_init(br_des_ct_cbcenc_keys *ctx,
 453         const void *key, size_t len);
 454 void br_des_ct_cbcdec_init(br_des_ct_cbcdec_keys *ctx,
 455         const void *key, size_t len);
 456 void br_des_ct_cbcenc_run(const br_des_ct_cbcenc_keys *ctx, void *iv,
 457         void *data, size_t len);
 458 void br_des_ct_cbcdec_run(const br_des_ct_cbcdec_keys *ctx, void *iv,
 459         void *data, size_t len);
 460
 461 /*
 462  * These structures are large enough to accommodate subkeys for all
 463  * DES/3DES implementations.
 464  */
 465 typedef union {
 466         const br_block_cbcenc_class *vtable;
 467         br_des_tab_cbcenc_keys tab;
 468         br_des_ct_cbcenc_keys ct;
 469 } br_des_gen_cbcenc_keys;
 470 typedef union {
 471         const br_block_cbcdec_class *vtable;
 472         br_des_tab_cbcdec_keys tab;
 473         br_des_ct_cbcdec_keys ct;
 474 } br_des_gen_cbcdec_keys;
 475
 476 #endif