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

   1 /*
   2  * Copyright (c) 2017 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_AEAD_H__
  26 #define BR_BEARSSL_AEAD_H__
  27
  28 #include <stddef.h>
  29 #include <stdint.h>
  30
  31 #include "bearssl_block.h"
  32 #include "bearssl_hash.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /** \file bearssl_aead.h
  39  *
  40  * # Authenticated Encryption with Additional Data
  41  *
  42  * This file documents the API for AEAD encryption.
  43  *
  44  *
  45  * ## Procedural API
  46  *
  47  * An AEAD algorithm processes messages and provides confidentiality
  48  * (encryption) and checked integrity (MAC). It uses the following
  49  * parameters:
  50  *
  51  *   - A symmetric key. Exact size depends on the AEAD algorithm.
  52  *
  53  *   - A nonce (IV). Size depends on the AEAD algorithm; for most
  54  *     algorithms, it is crucial for security that any given nonce
  55  *     value is never used twice for the same key and distinct
  56  *     messages.
  57  *
  58  *   - Data to encrypt and protect.
  59  *
  60  *   - Additional authenticated data, which is covered by the MAC but
  61  *     otherwise left untouched (i.e. not encrypted).
  62  *
  63  * The AEAD algorithm encrypts the data, and produces an authentication
  64  * tag. It is assumed that the encrypted data, the tag, the additional
  65  * authenticated data and the nonce are sent to the receiver; the
  66  * additional data and the nonce may be implicit (e.g. using elements of
  67  * the underlying transport protocol, such as record sequence numbers).
  68  * The receiver will recompute the tag value and compare it with the one
  69  * received; if they match, then the data is correct, and can be
  70  * decrypted and used; otherwise, at least one of the elements was
  71  * altered in transit, normally leading to wholesale rejection of the
  72  * complete message.
  73  *
  74  * For each AEAD algorithm, identified by a symbolic name (hereafter
  75  * denoted as "`xxx`"), the following functions are defined:
  76  *
  77  *   - `br_xxx_init()`
  78  *
  79  *     Initialise the AEAD algorithm, on a provided context structure.
  80  *     Exact parameters depend on the algorithm, and may include
  81  *     pointers to extra implementations and context structures. The
  82  *     secret key is provided at this point, either directly or
  83  *     indirectly.
  84  *
  85  *   - `br_xxx_reset()`
  86  *
  87  *     Start a new AEAD computation. The nonce value is provided as
  88  *     parameter to this function.
  89  *
  90  *   - `br_xxx_aad_inject()`
  91  *
  92  *     Inject some additional authenticated data. Additional data may
  93  *     be provided in several chunks of arbitrary length.
  94  *
  95  *   - `br_xxx_flip()`
  96  *
  97  *     This function MUST be called after injecting all additional
  98  *     authenticated data, and before beginning to encrypt the plaintext
  99  *     (or decrypt the ciphertext).
 100  *
 101  *   - `br_xxx_run()`
 102  *
 103  *     Process some plaintext (to encrypt) or ciphertext (to decrypt).
 104  *     Encryption/decryption is done in place. Data may be provided in
 105  *     several chunks of arbitrary length.
 106  *
 107  *   - `br_xxx_get_tag()`
 108  *
 109  *     Compute the authentication tag. All message data (encrypted or
 110  *     decrypted) must have been injected at that point. Also, this
 111  *     call may modify internal context elements, so it may be called
 112  *     only once for a given AEAD computation.
 113  *
 114  *   - `br_xxx_check_tag()`
 115  *
 116  *     An alternative to `br_xxx_get_tag()`, meant to be used by the
 117  *     receiver: the authentication tag is internally recomputed, and
 118  *     compared with the one provided as parameter.
 119  *
 120  * This API makes the following assumptions on the AEAD algorithm:
 121  *
 122  *   - Encryption does not expand the size of the ciphertext; there is
 123  *     no padding. This is true of most modern AEAD modes such as GCM.
 124  *
 125  *   - The additional authenticated data must be processed first,
 126  *     before the encrypted/decrypted data.
 127  *
 128  *   - Nonce, plaintext and additional authenticated data all consist
 129  *     in an integral number of bytes. There is no provision to use
 130  *     elements whose length in bits is not a multiple of 8.
 131  *
 132  * Each AEAD algorithm has its own requirements and limits on the sizes
 133  * of additional data and plaintext. This API does not provide any
 134  * way to report invalid usage; it is up to the caller to ensure that
 135  * the provided key, nonce, and data elements all fit the algorithm's
 136  * requirements.
 137  *
 138  *
 139  * ## Object-Oriented API
 140  *
 141  * Each context structure begins with a field (called `vtable`) that
 142  * points to an instance of a structure that references the relevant
 143  * functions through pointers. Each such structure contains the
 144  * following:
 145  *
 146  *   - `reset`
 147  *
 148  *     Pointer to the reset function, that allows starting a new
 149  *     computation.
 150  *
 151  *   - `aad_inject`
 152  *
 153  *     Pointer to the additional authenticated data injection function.
 154  *
 155  *   - `flip`
 156  *
 157  *     Pointer to the function that transitions from additional data
 158  *     to main message data processing.
 159  *
 160  *   - `get_tag`
 161  *
 162  *     Pointer to the function that computes and returns the tag.
 163  *
 164  *   - `check_tag`
 165  *
 166  *     Pointer to the function that computes and verifies the tag against
 167  *     a received value.
 168  *
 169  * Note that there is no OOP method for context initialisation: the
 170  * various AEAD algorithms have different requirements that would not
 171  * map well to a single initialisation API.
 172  *
 173  * The OOP API is not provided for CCM, due to its specific requirements
 174  * (length of plaintext must be known in advance).
 175  */
 176
 177 /**
 178  * \brief Class type of an AEAD algorithm.
 179  */
 180 typedef struct br_aead_class_ br_aead_class;
 181 struct br_aead_class_ {
 182
 183         /**
 184          * \brief Size (in bytes) of authentication tags created by
 185          * this AEAD algorithm.
 186          */
 187         size_t tag_size;
 188
 189         /**
 190          * \brief Reset an AEAD context.
 191          *
 192          * This function resets an already initialised AEAD context for
 193          * a new computation run. Implementations and keys are
 194          * conserved. This function can be called at any time; it
 195          * cancels any ongoing AEAD computation that uses the provided
 196          * context structure.
 197
 198          * The provided IV is a _nonce_. Each AEAD algorithm has its
 199          * own requirements on IV size and contents; for most of them,
 200          * it is crucial to security that each nonce value is used
 201          * only once for a given secret key.
 202          *
 203          * \param cc    AEAD context structure.
 204          * \param iv    AEAD nonce to use.
 205          * \param len   AEAD nonce length (in bytes).
 206          */
 207         void (*reset)(const br_aead_class **cc, const void *iv, size_t len);
 208
 209         /**
 210          * \brief Inject additional authenticated data.
 211          *
 212          * The provided data is injected into a running AEAD
 213          * computation. Additional data must be injected _before_ the
 214          * call to `flip()`. Additional data can be injected in several
 215          * chunks of arbitrary length.
 216          *
 217          * \param cc     AEAD context structure.
 218          * \param data   pointer to additional authenticated data.
 219          * \param len    length of additional authenticated data (in bytes).
 220          */
 221         void (*aad_inject)(const br_aead_class **cc,
 222                 const void *data, size_t len);
 223
 224         /**
 225          * \brief Finish injection of additional authenticated data.
 226          *
 227          * This function MUST be called before beginning the actual
 228          * encryption or decryption (with `run()`), even if no
 229          * additional authenticated data was injected. No additional
 230          * authenticated data may be injected after this function call.
 231          *
 232          * \param cc   AEAD context structure.
 233          */
 234         void (*flip)(const br_aead_class **cc);
 235
 236         /**
 237          * \brief Encrypt or decrypt some data.
 238          *
 239          * Data encryption or decryption can be done after `flip()` has
 240          * been called on the context. If `encrypt` is non-zero, then
 241          * the provided data shall be plaintext, and it is encrypted in
 242          * place. Otherwise, the data shall be ciphertext, and it is
 243          * decrypted in place.
 244          *
 245          * Data may be provided in several chunks of arbitrary length.
 246          *
 247          * \param cc        AEAD context structure.
 248          * \param encrypt   non-zero for encryption, zero for decryption.
 249          * \param data      data to encrypt or decrypt.
 250          * \param len       data length (in bytes).
 251          */
 252         void (*run)(const br_aead_class **cc, int encrypt,
 253                 void *data, size_t len);
 254
 255         /**
 256          * \brief Compute authentication tag.
 257          *
 258          * Compute the AEAD authentication tag. The tag length depends
 259          * on the AEAD algorithm; it is written in the provided `tag`
 260          * buffer. This call terminates the AEAD run: no data may be
 261          * processed with that AEAD context afterwards, until `reset()`
 262          * is called to initiate a new AEAD run.
 263          *
 264          * The tag value must normally be sent along with the encrypted
 265          * data. When decrypting, the tag value must be recomputed and
 266          * compared with the received tag: if the two tag values differ,
 267          * then either the tag or the encrypted data was altered in
 268          * transit. As an alternative to this function, the
 269          * `check_tag()` function may be used to compute and check the
 270          * tag value.
 271          *
 272          * Tag length depends on the AEAD algorithm.
 273          *
 274          * \param cc    AEAD context structure.
 275          * \param tag   destination buffer for the tag.
 276          */
 277         void (*get_tag)(const br_aead_class **cc, void *tag);
 278
 279         /**
 280          * \brief Compute and check authentication tag.
 281          *
 282          * This function is an alternative to `get_tag()`, and is
 283          * normally used on the receiving end (i.e. when decrypting
 284          * messages). The tag value is recomputed and compared with the
 285          * provided tag value. If they match, 1 is returned; on
 286          * mismatch, 0 is returned. A returned value of 0 means that the
 287          * data or the tag was altered in transit, normally leading to
 288          * wholesale rejection of the complete message.
 289          *
 290          * Tag length depends on the AEAD algorithm.
 291          *
 292          * \param cc    AEAD context structure.
 293          * \param tag   tag value to compare with.
 294          * \return  1 on success (exact match of tag value), 0 otherwise.
 295          */
 296         uint32_t (*check_tag)(const br_aead_class **cc, const void *tag);
 297
 298         /**
 299          * \brief Compute authentication tag (with truncation).
 300          *
 301          * This function is similar to `get_tag()`, except that the tag
 302          * length is provided. Some AEAD algorithms allow several tag
 303          * lengths, usually by truncating the normal tag. Shorter tags
 304          * mechanically increase success probability of forgeries.
 305          * The range of allowed tag lengths depends on the algorithm.
 306          *
 307          * \param cc    AEAD context structure.
 308          * \param tag   destination buffer for the tag.
 309          * \param len   tag length (in bytes).
 310          */
 311         void (*get_tag_trunc)(const br_aead_class **cc, void *tag, size_t len);
 312
 313         /**
 314          * \brief Compute and check authentication tag (with truncation).
 315          *
 316          * This function is similar to `check_tag()` except that it
 317          * works over an explicit tag length. See `get_tag()` for a
 318          * discussion of explicit tag lengths; the range of allowed tag
 319          * lengths depends on the algorithm.
 320          *
 321          * \param cc    AEAD context structure.
 322          * \param tag   tag value to compare with.
 323          * \param len   tag length (in bytes).
 324          * \return  1 on success (exact match of tag value), 0 otherwise.
 325          */
 326         uint32_t (*check_tag_trunc)(const br_aead_class **cc,
 327                 const void *tag, size_t len);
 328 };
 329
 330 /**
 331  * \brief Context structure for GCM.
 332  *
 333  * GCM is an AEAD mode that combines a block cipher in CTR mode with a
 334  * MAC based on GHASH, to provide authenticated encryption:
 335  *
 336  *   - Any block cipher with 16-byte blocks can be used with GCM.
 337  *
 338  *   - The nonce can have any length, from 0 up to 2^64-1 bits; however,
 339  *     96-bit nonces (12 bytes) are recommended (nonces with a length
 340  *     distinct from 12 bytes are internally hashed, which risks reusing
 341  *     nonce value with a small but not always negligible probability).
 342  *
 343  *   - Additional authenticated data may have length up to 2^64-1 bits.
 344  *
 345  *   - Message length may range up to 2^39-256 bits at most.
 346  *
 347  *   - The authentication tag has length 16 bytes.
 348  *
 349  * The GCM initialisation function receives as parameter an
 350  * _initialised_ block cipher implementation context, with the secret
 351  * key already set. A pointer to that context will be kept within the
 352  * GCM context structure. It is up to the caller to allocate and
 353  * initialise that block cipher context.
 354  */
 355 typedef struct {
 356         /** \brief Pointer to vtable for this context. */
 357         const br_aead_class *vtable;
 358
 359 #ifndef BR_DOXYGEN_IGNORE
 360         const br_block_ctr_class **bctx;
 361         br_ghash gh;
 362         unsigned char h[16];
 363         unsigned char j0_1[12];
 364         unsigned char buf[16];
 365         unsigned char y[16];
 366         uint32_t j0_2, jc;
 367         uint64_t count_aad, count_ctr;
 368 #endif
 369 } br_gcm_context;
 370
 371 /**
 372  * \brief Initialize a GCM context.
 373  *
 374  * A block cipher implementation, with its initialised context structure,
 375  * is provided. The block cipher MUST use 16-byte blocks in CTR mode,
 376  * and its secret key MUST have been already set in the provided context.
 377  * A GHASH implementation must also be provided. The parameters are linked
 378  * in the GCM context.
 379  *
 380  * After this function has been called, the `br_gcm_reset()` function must
 381  * be called, to provide the IV for GCM computation.
 382  *
 383  * \param ctx    GCM context structure.
 384  * \param bctx   block cipher context (already initialised with secret key).
 385  * \param gh     GHASH implementation.
 386  */
 387 void br_gcm_init(br_gcm_context *ctx,
 388         const br_block_ctr_class **bctx, br_ghash gh);
 389
 390 /**
 391  * \brief Reset a GCM context.
 392  *
 393  * This function resets an already initialised GCM context for a new
 394  * computation run. Implementations and keys are conserved. This function
 395  * can be called at any time; it cancels any ongoing GCM computation that
 396  * uses the provided context structure.
 397  *
 398  * The provided IV is a _nonce_. It is critical to GCM security that IV
 399  * values are not repeated for the same encryption key. IV can have
 400  * arbitrary length (up to 2^64-1 bits), but the "normal" length is
 401  * 96 bits (12 bytes).
 402  *
 403  * \param ctx   GCM context structure.
 404  * \param iv    GCM nonce to use.
 405  * \param len   GCM nonce length (in bytes).
 406  */
 407 void br_gcm_reset(br_gcm_context *ctx, const void *iv, size_t len);
 408
 409 /**
 410  * \brief Inject additional authenticated data into GCM.
 411  *
 412  * The provided data is injected into a running GCM computation. Additional
 413  * data must be injected _before_ the call to `br_gcm_flip()`.
 414  * Additional data can be injected in several chunks of arbitrary length;
 415  * the maximum total size of additional authenticated data is 2^64-1
 416  * bits.
 417  *
 418  * \param ctx    GCM context structure.
 419  * \param data   pointer to additional authenticated data.
 420  * \param len    length of additional authenticated data (in bytes).
 421  */
 422 void br_gcm_aad_inject(br_gcm_context *ctx, const void *data, size_t len);
 423
 424 /**
 425  * \brief Finish injection of additional authenticated data into GCM.
 426  *
 427  * This function MUST be called before beginning the actual encryption
 428  * or decryption (with `br_gcm_run()`), even if no additional authenticated
 429  * data was injected. No additional authenticated data may be injected
 430  * after this function call.
 431  *
 432  * \param ctx   GCM context structure.
 433  */
 434 void br_gcm_flip(br_gcm_context *ctx);
 435
 436 /**
 437  * \brief Encrypt or decrypt some data with GCM.
 438  *
 439  * Data encryption or decryption can be done after `br_gcm_flip()`
 440  * has been called on the context. If `encrypt` is non-zero, then the
 441  * provided data shall be plaintext, and it is encrypted in place.
 442  * Otherwise, the data shall be ciphertext, and it is decrypted in place.
 443  *
 444  * Data may be provided in several chunks of arbitrary length. The maximum
 445  * total length for data is 2^39-256 bits, i.e. about 65 gigabytes.
 446  *
 447  * \param ctx       GCM context structure.
 448  * \param encrypt   non-zero for encryption, zero for decryption.
 449  * \param data      data to encrypt or decrypt.
 450  * \param len       data length (in bytes).
 451  */
 452 void br_gcm_run(br_gcm_context *ctx, int encrypt, void *data, size_t len);
 453
 454 /**
 455  * \brief Compute GCM authentication tag.
 456  *
 457  * Compute the GCM authentication tag. The tag is a 16-byte value which
 458  * is written in the provided `tag` buffer. This call terminates the
 459  * GCM run: no data may be processed with that GCM context afterwards,
 460  * until `br_gcm_reset()` is called to initiate a new GCM run.
 461  *
 462  * The tag value must normally be sent along with the encrypted data.
 463  * When decrypting, the tag value must be recomputed and compared with
 464  * the received tag: if the two tag values differ, then either the tag
 465  * or the encrypted data was altered in transit. As an alternative to
 466  * this function, the `br_gcm_check_tag()` function can be used to
 467  * compute and check the tag value.
 468  *
 469  * \param ctx   GCM context structure.
 470  * \param tag   destination buffer for the tag (16 bytes).
 471  */
 472 void br_gcm_get_tag(br_gcm_context *ctx, void *tag);
 473
 474 /**
 475  * \brief Compute and check GCM authentication tag.
 476  *
 477  * This function is an alternative to `br_gcm_get_tag()`, normally used
 478  * on the receiving end (i.e. when decrypting value). The tag value is
 479  * recomputed and compared with the provided tag value. If they match, 1
 480  * is returned; on mismatch, 0 is returned. A returned value of 0 means
 481  * that the data or the tag was altered in transit, normally leading to
 482  * wholesale rejection of the complete message.
 483  *
 484  * \param ctx   GCM context structure.
 485  * \param tag   tag value to compare with (16 bytes).
 486  * \return  1 on success (exact match of tag value), 0 otherwise.
 487  */
 488 uint32_t br_gcm_check_tag(br_gcm_context *ctx, const void *tag);
 489
 490 /**
 491  * \brief Compute GCM authentication tag (with truncation).
 492  *
 493  * This function is similar to `br_gcm_get_tag()`, except that it allows
 494  * the tag to be truncated to a smaller length. The intended tag length
 495  * is provided as `len` (in bytes); it MUST be no more than 16, but
 496  * it may be smaller. Note that decreasing tag length mechanically makes
 497  * forgeries easier; NIST SP 800-38D specifies that the tag length shall
 498  * lie between 12 and 16 bytes (inclusive), but may be truncated down to
 499  * 4 or 8 bytes, for specific applications that can tolerate it. It must
 500  * also be noted that successful forgeries leak information on the
 501  * authentication key, making subsequent forgeries easier. Therefore,
 502  * tag truncation, and in particular truncation to sizes lower than 12
 503  * bytes, shall be envisioned only with great care.
 504  *
 505  * The tag is written in the provided `tag` buffer. This call terminates
 506  * the GCM run: no data may be processed with that GCM context
 507  * afterwards, until `br_gcm_reset()` is called to initiate a new GCM
 508  * run.
 509  *
 510  * The tag value must normally be sent along with the encrypted data.
 511  * When decrypting, the tag value must be recomputed and compared with
 512  * the received tag: if the two tag values differ, then either the tag
 513  * or the encrypted data was altered in transit. As an alternative to
 514  * this function, the `br_gcm_check_tag_trunc()` function can be used to
 515  * compute and check the tag value.
 516  *
 517  * \param ctx   GCM context structure.
 518  * \param tag   destination buffer for the tag.
 519  * \param len   tag length (16 bytes or less).
 520  */
 521 void br_gcm_get_tag_trunc(br_gcm_context *ctx, void *tag, size_t len);
 522
 523 /**
 524  * \brief Compute and check GCM authentication tag (with truncation).
 525  *
 526  * This function is an alternative to `br_gcm_get_tag_trunc()`, normally used
 527  * on the receiving end (i.e. when decrypting value). The tag value is
 528  * recomputed and compared with the provided tag value. If they match, 1
 529  * is returned; on mismatch, 0 is returned. A returned value of 0 means
 530  * that the data or the tag was altered in transit, normally leading to
 531  * wholesale rejection of the complete message.
 532  *
 533  * Tag length MUST be 16 bytes or less. The normal GCM tag length is 16
 534  * bytes. See `br_check_tag_trunc()` for some discussion on the potential
 535  * perils of truncating authentication tags.
 536  *
 537  * \param ctx   GCM context structure.
 538  * \param tag   tag value to compare with.
 539  * \param len   tag length (in bytes).
 540  * \return  1 on success (exact match of tag value), 0 otherwise.
 541  */
 542 uint32_t br_gcm_check_tag_trunc(br_gcm_context *ctx,
 543         const void *tag, size_t len);
 544
 545 /**
 546  * \brief Class instance for GCM.
 547  */
 548 extern const br_aead_class br_gcm_vtable;
 549
 550 /**
 551  * \brief Context structure for EAX.
 552  *
 553  * EAX is an AEAD mode that combines a block cipher in CTR mode with
 554  * CBC-MAC using the same block cipher and the same key, to provide
 555  * authenticated encryption:
 556  *
 557  *   - Any block cipher with 16-byte blocks can be used with EAX
 558  *     (technically, other block sizes are defined as well, but this
 559  *     is not implemented by these functions; shorter blocks also
 560  *     imply numerous security issues).
 561  *
 562  *   - The nonce can have any length, as long as nonce values are
 563  *     not reused (thus, if nonces are randomly selected, the nonce
 564  *     size should be such that reuse probability is negligible).
 565  *
 566  *   - Additional authenticated data length is unlimited.
 567  *
 568  *   - Message length is unlimited.
 569  *
 570  *   - The authentication tag has length 16 bytes.
 571  *
 572  * The EAX initialisation function receives as parameter an
 573  * _initialised_ block cipher implementation context, with the secret
 574  * key already set. A pointer to that context will be kept within the
 575  * EAX context structure. It is up to the caller to allocate and
 576  * initialise that block cipher context.
 577  */
 578 typedef struct {
 579         /** \brief Pointer to vtable for this context. */
 580         const br_aead_class *vtable;
 581
 582 #ifndef BR_DOXYGEN_IGNORE
 583         const br_block_ctrcbc_class **bctx;
 584         unsigned char L2[16];
 585         unsigned char L4[16];
 586         unsigned char nonce[16];
 587         unsigned char head[16];
 588         unsigned char ctr[16];
 589         unsigned char cbcmac[16];
 590         unsigned char buf[16];
 591         size_t ptr;
 592 #endif
 593 } br_eax_context;
 594
 595 /**
 596  * \brief EAX captured state.
 597  *
 598  * Some internal values computed by EAX may be captured at various
 599  * points, and reused for another EAX run with the same secret key,
 600  * for lower per-message overhead. Captured values do not depend on
 601  * the nonce.
 602  */
 603 typedef struct {
 604 #ifndef BR_DOXYGEN_IGNORE
 605         unsigned char st[3][16];
 606 #endif
 607 } br_eax_state;
 608
 609 /**
 610  * \brief Initialize an EAX context.
 611  *
 612  * A block cipher implementation, with its initialised context
 613  * structure, is provided. The block cipher MUST use 16-byte blocks in
 614  * CTR + CBC-MAC mode, and its secret key MUST have been already set in
 615  * the provided context. The parameters are linked in the EAX context.
 616  *
 617  * After this function has been called, the `br_eax_reset()` function must
 618  * be called, to provide the nonce for EAX computation.
 619  *
 620  * \param ctx    EAX context structure.
 621  * \param bctx   block cipher context (already initialised with secret key).
 622  */
 623 void br_eax_init(br_eax_context *ctx, const br_block_ctrcbc_class **bctx);
 624
 625 /**
 626  * \brief Capture pre-AAD state.
 627  *
 628  * This function precomputes key-dependent data, and stores it in the
 629  * provided `st` structure. This structure should then be used with
 630  * `br_eax_reset_pre_aad()`, or updated with `br_eax_get_aad_mac()`
 631  * and then used with `br_eax_reset_post_aad()`.
 632  *
 633  * The EAX context structure is unmodified by this call.
 634  *
 635  * \param ctx   EAX context structure.
 636  * \param st    recipient for captured state.
 637  */
 638 void br_eax_capture(const br_eax_context *ctx, br_eax_state *st);
 639
 640 /**
 641  * \brief Reset an EAX context.
 642  *
 643  * This function resets an already initialised EAX context for a new
 644  * computation run. Implementations and keys are conserved. This function
 645  * can be called at any time; it cancels any ongoing EAX computation that
 646  * uses the provided context structure.
 647  *
 648  * It is critical to EAX security that nonce values are not repeated for
 649  * the same encryption key. Nonces can have arbitrary length. If nonces
 650  * are randomly generated, then a nonce length of at least 128 bits (16
 651  * bytes) is recommended, to make nonce reuse probability sufficiently
 652  * low.
 653  *
 654  * \param ctx     EAX context structure.
 655  * \param nonce   EAX nonce to use.
 656  * \param len     EAX nonce length (in bytes).
 657  */
 658 void br_eax_reset(br_eax_context *ctx, const void *nonce, size_t len);
 659
 660 /**
 661  * \brief Reset an EAX context with a pre-AAD captured state.
 662  *
 663  * This function is an alternative to `br_eax_reset()`, that reuses a
 664  * previously captured state structure for lower per-message overhead.
 665  * The state should have been populated with `br_eax_capture_state()`
 666  * but not updated with `br_eax_get_aad_mac()`.
 667  *
 668  * After this function is called, additional authenticated data MUST
 669  * be injected. At least one byte of additional authenticated data
 670  * MUST be provided with `br_eax_aad_inject()`; computation result will
 671  * be incorrect if `br_eax_flip()` is called right away.
 672  *
 673  * After injection of the AAD and call to `br_eax_flip()`, at least
 674  * one message byte must be provided. Empty messages are not supported
 675  * with this reset mode.
 676  *
 677  * \param ctx     EAX context structure.
 678  * \param st      pre-AAD captured state.
 679  * \param nonce   EAX nonce to use.
 680  * \param len     EAX nonce length (in bytes).
 681  */
 682 void br_eax_reset_pre_aad(br_eax_context *ctx, const br_eax_state *st,
 683         const void *nonce, size_t len);
 684
 685 /**
 686  * \brief Reset an EAX context with a post-AAD captured state.
 687  *
 688  * This function is an alternative to `br_eax_reset()`, that reuses a
 689  * previously captured state structure for lower per-message overhead.
 690  * The state should have been populated with `br_eax_capture_state()`
 691  * and then updated with `br_eax_get_aad_mac()`.
 692  *
 693  * After this function is called, message data MUST be injected. The
 694  * `br_eax_flip()` function MUST NOT be called. At least one byte of
 695  * message data MUST be provided with `br_eax_run()`; empty messages
 696  * are not supported with this reset mode.
 697  *
 698  * \param ctx     EAX context structure.
 699  * \param st      post-AAD captured state.
 700  * \param nonce   EAX nonce to use.
 701  * \param len     EAX nonce length (in bytes).
 702  */
 703 void br_eax_reset_post_aad(br_eax_context *ctx, const br_eax_state *st,
 704         const void *nonce, size_t len);
 705
 706 /**
 707  * \brief Inject additional authenticated data into EAX.
 708  *
 709  * The provided data is injected into a running EAX computation. Additional
 710  * data must be injected _before_ the call to `br_eax_flip()`.
 711  * Additional data can be injected in several chunks of arbitrary length;
 712  * the total amount of additional authenticated data is unlimited.
 713  *
 714  * \param ctx    EAX context structure.
 715  * \param data   pointer to additional authenticated data.
 716  * \param len    length of additional authenticated data (in bytes).
 717  */
 718 void br_eax_aad_inject(br_eax_context *ctx, const void *data, size_t len);
 719
 720 /**
 721  * \brief Finish injection of additional authenticated data into EAX.
 722  *
 723  * This function MUST be called before beginning the actual encryption
 724  * or decryption (with `br_eax_run()`), even if no additional authenticated
 725  * data was injected. No additional authenticated data may be injected
 726  * after this function call.
 727  *
 728  * \param ctx   EAX context structure.
 729  */
 730 void br_eax_flip(br_eax_context *ctx);
 731
 732 /**
 733  * \brief Obtain a copy of the MAC on additional authenticated data.
 734  *
 735  * This function may be called only after `br_eax_flip()`; it copies the
 736  * AAD-specific MAC value into the provided state. The MAC value depends
 737  * on the secret key and the additional data itself, but not on the
 738  * nonce. The updated state `st` is meant to be used as parameter for a
 739  * further `br_eax_reset_post_aad()` call.
 740  *
 741  * \param ctx   EAX context structure.
 742  * \param st    captured state to update.
 743  */
 744 static inline void
 745 br_eax_get_aad_mac(const br_eax_context *ctx, br_eax_state *st)
 746 {
 747         memcpy(st->st[1], ctx->head, sizeof ctx->head);
 748 }
 749
 750 /**
 751  * \brief Encrypt or decrypt some data with EAX.
 752  *
 753  * Data encryption or decryption can be done after `br_eax_flip()`
 754  * has been called on the context. If `encrypt` is non-zero, then the
 755  * provided data shall be plaintext, and it is encrypted in place.
 756  * Otherwise, the data shall be ciphertext, and it is decrypted in place.
 757  *
 758  * Data may be provided in several chunks of arbitrary length.
 759  *
 760  * \param ctx       EAX context structure.
 761  * \param encrypt   non-zero for encryption, zero for decryption.
 762  * \param data      data to encrypt or decrypt.
 763  * \param len       data length (in bytes).
 764  */
 765 void br_eax_run(br_eax_context *ctx, int encrypt, void *data, size_t len);
 766
 767 /**
 768  * \brief Compute EAX authentication tag.
 769  *
 770  * Compute the EAX authentication tag. The tag is a 16-byte value which
 771  * is written in the provided `tag` buffer. This call terminates the
 772  * EAX run: no data may be processed with that EAX context afterwards,
 773  * until `br_eax_reset()` is called to initiate a new EAX run.
 774  *
 775  * The tag value must normally be sent along with the encrypted data.
 776  * When decrypting, the tag value must be recomputed and compared with
 777  * the received tag: if the two tag values differ, then either the tag
 778  * or the encrypted data was altered in transit. As an alternative to
 779  * this function, the `br_eax_check_tag()` function can be used to
 780  * compute and check the tag value.
 781  *
 782  * \param ctx   EAX context structure.
 783  * \param tag   destination buffer for the tag (16 bytes).
 784  */
 785 void br_eax_get_tag(br_eax_context *ctx, void *tag);
 786
 787 /**
 788  * \brief Compute and check EAX authentication tag.
 789  *
 790  * This function is an alternative to `br_eax_get_tag()`, normally used
 791  * on the receiving end (i.e. when decrypting value). The tag value is
 792  * recomputed and compared with the provided tag value. If they match, 1
 793  * is returned; on mismatch, 0 is returned. A returned value of 0 means
 794  * that the data or the tag was altered in transit, normally leading to
 795  * wholesale rejection of the complete message.
 796  *
 797  * \param ctx   EAX context structure.
 798  * \param tag   tag value to compare with (16 bytes).
 799  * \return  1 on success (exact match of tag value), 0 otherwise.
 800  */
 801 uint32_t br_eax_check_tag(br_eax_context *ctx, const void *tag);
 802
 803 /**
 804  * \brief Compute EAX authentication tag (with truncation).
 805  *
 806  * This function is similar to `br_eax_get_tag()`, except that it allows
 807  * the tag to be truncated to a smaller length. The intended tag length
 808  * is provided as `len` (in bytes); it MUST be no more than 16, but
 809  * it may be smaller. Note that decreasing tag length mechanically makes
 810  * forgeries easier; NIST SP 800-38D specifies that the tag length shall
 811  * lie between 12 and 16 bytes (inclusive), but may be truncated down to
 812  * 4 or 8 bytes, for specific applications that can tolerate it. It must
 813  * also be noted that successful forgeries leak information on the
 814  * authentication key, making subsequent forgeries easier. Therefore,
 815  * tag truncation, and in particular truncation to sizes lower than 12
 816  * bytes, shall be envisioned only with great care.
 817  *
 818  * The tag is written in the provided `tag` buffer. This call terminates
 819  * the EAX run: no data may be processed with that EAX context
 820  * afterwards, until `br_eax_reset()` is called to initiate a new EAX
 821  * run.
 822  *
 823  * The tag value must normally be sent along with the encrypted data.
 824  * When decrypting, the tag value must be recomputed and compared with
 825  * the received tag: if the two tag values differ, then either the tag
 826  * or the encrypted data was altered in transit. As an alternative to
 827  * this function, the `br_eax_check_tag_trunc()` function can be used to
 828  * compute and check the tag value.
 829  *
 830  * \param ctx   EAX context structure.
 831  * \param tag   destination buffer for the tag.
 832  * \param len   tag length (16 bytes or less).
 833  */
 834 void br_eax_get_tag_trunc(br_eax_context *ctx, void *tag, size_t len);
 835
 836 /**
 837  * \brief Compute and check EAX authentication tag (with truncation).
 838  *
 839  * This function is an alternative to `br_eax_get_tag_trunc()`, normally used
 840  * on the receiving end (i.e. when decrypting value). The tag value is
 841  * recomputed and compared with the provided tag value. If they match, 1
 842  * is returned; on mismatch, 0 is returned. A returned value of 0 means
 843  * that the data or the tag was altered in transit, normally leading to
 844  * wholesale rejection of the complete message.
 845  *
 846  * Tag length MUST be 16 bytes or less. The normal EAX tag length is 16
 847  * bytes. See `br_check_tag_trunc()` for some discussion on the potential
 848  * perils of truncating authentication tags.
 849  *
 850  * \param ctx   EAX context structure.
 851  * \param tag   tag value to compare with.
 852  * \param len   tag length (in bytes).
 853  * \return  1 on success (exact match of tag value), 0 otherwise.
 854  */
 855 uint32_t br_eax_check_tag_trunc(br_eax_context *ctx,
 856         const void *tag, size_t len);
 857
 858 /**
 859  * \brief Class instance for EAX.
 860  */
 861 extern const br_aead_class br_eax_vtable;
 862
 863 /**
 864  * \brief Context structure for CCM.
 865  *
 866  * CCM is an AEAD mode that combines a block cipher in CTR mode with
 867  * CBC-MAC using the same block cipher and the same key, to provide
 868  * authenticated encryption:
 869  *
 870  *   - Any block cipher with 16-byte blocks can be used with CCM
 871  *     (technically, other block sizes are defined as well, but this
 872  *     is not implemented by these functions; shorter blocks also
 873  *     imply numerous security issues).
 874  *
 875  *   - The authentication tag length, and plaintext length, MUST be
 876  *     known when starting processing data. Plaintext and ciphertext
 877  *     can still be provided by chunks, but the total size must match
 878  *     the value provided upon initialisation.
 879  *
 880  *   - The nonce length is constrained between 7 and 13 bytes (inclusive).
 881  *     Furthermore, the plaintext length, when encoded, must fit over
 882  *     15-nonceLen bytes; thus, if the nonce has length 13 bytes, then
 883  *     the plaintext length cannot exceed 65535 bytes.
 884  *
 885  *   - Additional authenticated data length is practically unlimited
 886  *     (formal limit is at 2^64 bytes).
 887  *
 888  *   - The authentication tag has length 4 to 16 bytes (even values only).
 889  *
 890  * The CCM initialisation function receives as parameter an
 891  * _initialised_ block cipher implementation context, with the secret
 892  * key already set. A pointer to that context will be kept within the
 893  * CCM context structure. It is up to the caller to allocate and
 894  * initialise that block cipher context.
 895  */
 896 typedef struct {
 897 #ifndef BR_DOXYGEN_IGNORE
 898         const br_block_ctrcbc_class **bctx;
 899         unsigned char ctr[16];
 900         unsigned char cbcmac[16];
 901         unsigned char tagmask[16];
 902         unsigned char buf[16];
 903         size_t ptr;
 904         size_t tag_len;
 905 #endif
 906 } br_ccm_context;
 907
 908 /**
 909  * \brief Initialize a CCM context.
 910  *
 911  * A block cipher implementation, with its initialised context
 912  * structure, is provided. The block cipher MUST use 16-byte blocks in
 913  * CTR + CBC-MAC mode, and its secret key MUST have been already set in
 914  * the provided context. The parameters are linked in the CCM context.
 915  *
 916  * After this function has been called, the `br_ccm_reset()` function must
 917  * be called, to provide the nonce for CCM computation.
 918  *
 919  * \param ctx    CCM context structure.
 920  * \param bctx   block cipher context (already initialised with secret key).
 921  */
 922 void br_ccm_init(br_ccm_context *ctx, const br_block_ctrcbc_class **bctx);
 923
 924 /**
 925  * \brief Reset a CCM context.
 926  *
 927  * This function resets an already initialised CCM context for a new
 928  * computation run. Implementations and keys are conserved. This function
 929  * can be called at any time; it cancels any ongoing CCM computation that
 930  * uses the provided context structure.
 931  *
 932  * The `aad_len` parameter contains the total length, in bytes, of the
 933  * additional authenticated data. It may be zero. That length MUST be
 934  * exact.
 935  *
 936  * The `data_len` parameter contains the total length, in bytes, of the
 937  * data that will be injected (plaintext or ciphertext). That length MUST
 938  * be exact. Moreover, that length MUST be less than 2^(8*(15-nonce_len)).
 939  *
 940  * The nonce length (`nonce_len`), in bytes, must be in the 7..13 range
 941  * (inclusive).
 942  *
 943  * The tag length (`tag_len`), in bytes, must be in the 4..16 range, and
 944  * be an even integer. Short tags mechanically allow for higher forgery
 945  * probabilities; hence, tag sizes smaller than 12 bytes shall be used only
 946  * with care.
 947  *
 948  * It is critical to CCM security that nonce values are not repeated for
 949  * the same encryption key. Random generation of nonces is not generally
 950  * recommended, due to the relatively small maximum nonce value.
 951  *
 952  * Returned value is 1 on success, 0 on error. An error is reported if
 953  * the tag or nonce length is out of range, or if the
 954  * plaintext/ciphertext length cannot be encoded with the specified
 955  * nonce length.
 956  *
 957  * \param ctx         CCM context structure.
 958  * \param nonce       CCM nonce to use.
 959  * \param nonce_len   CCM nonce length (in bytes, 7 to 13).
 960  * \param aad_len     additional authenticated data length (in bytes).
 961  * \param data_len    plaintext/ciphertext length (in bytes).
 962  * \param tag_len     tag length (in bytes).
 963  * \return  1 on success, 0 on error.
 964  */
 965 int br_ccm_reset(br_ccm_context *ctx, const void *nonce, size_t nonce_len,
 966         uint64_t aad_len, uint64_t data_len, size_t tag_len);
 967
 968 /**
 969  * \brief Inject additional authenticated data into CCM.
 970  *
 971  * The provided data is injected into a running CCM computation. Additional
 972  * data must be injected _before_ the call to `br_ccm_flip()`.
 973  * Additional data can be injected in several chunks of arbitrary length,
 974  * but the total amount MUST exactly match the value which was provided
 975  * to `br_ccm_reset()`.
 976  *
 977  * \param ctx    CCM context structure.
 978  * \param data   pointer to additional authenticated data.
 979  * \param len    length of additional authenticated data (in bytes).
 980  */
 981 void br_ccm_aad_inject(br_ccm_context *ctx, const void *data, size_t len);
 982
 983 /**
 984  * \brief Finish injection of additional authenticated data into CCM.
 985  *
 986  * This function MUST be called before beginning the actual encryption
 987  * or decryption (with `br_ccm_run()`), even if no additional authenticated
 988  * data was injected. No additional authenticated data may be injected
 989  * after this function call.
 990  *
 991  * \param ctx   CCM context structure.
 992  */
 993 void br_ccm_flip(br_ccm_context *ctx);
 994
 995 /**
 996  * \brief Encrypt or decrypt some data with CCM.
 997  *
 998  * Data encryption or decryption can be done after `br_ccm_flip()`
 999  * has been called on the context. If `encrypt` is non-zero, then the
1000  * provided data shall be plaintext, and it is encrypted in place.
1001  * Otherwise, the data shall be ciphertext, and it is decrypted in place.
1002  *
1003  * Data may be provided in several chunks of arbitrary length, provided
1004  * that the total length exactly matches the length provided to the
1005  * `br_ccm_reset()` call.
1006  *
1007  * \param ctx       CCM context structure.
1008  * \param encrypt   non-zero for encryption, zero for decryption.
1009  * \param data      data to encrypt or decrypt.
1010  * \param len       data length (in bytes).
1011  */
1012 void br_ccm_run(br_ccm_context *ctx, int encrypt, void *data, size_t len);
1013
1014 /**
1015  * \brief Compute CCM authentication tag.
1016  *
1017  * Compute the CCM authentication tag. This call terminates the CCM
1018  * run: all data must have been injected with `br_ccm_run()` (in zero,
1019  * one or more successive calls). After this function has been called,
1020  * no more data can br processed; a `br_ccm_reset()` call is required
1021  * to start a new message.
1022  *
1023  * The tag length was provided upon context initialisation (last call
1024  * to `br_ccm_reset()`); it is returned by this function.
1025  *
1026  * The tag value must normally be sent along with the encrypted data.
1027  * When decrypting, the tag value must be recomputed and compared with
1028  * the received tag: if the two tag values differ, then either the tag
1029  * or the encrypted data was altered in transit. As an alternative to
1030  * this function, the `br_ccm_check_tag()` function can be used to
1031  * compute and check the tag value.
1032  *
1033  * \param ctx   CCM context structure.
1034  * \param tag   destination buffer for the tag (up to 16 bytes).
1035  * \return  the tag length (in bytes).
1036  */
1037 size_t br_ccm_get_tag(br_ccm_context *ctx, void *tag);
1038
1039 /**
1040  * \brief Compute and check CCM authentication tag.
1041  *
1042  * This function is an alternative to `br_ccm_get_tag()`, normally used
1043  * on the receiving end (i.e. when decrypting value). The tag value is
1044  * recomputed and compared with the provided tag value. If they match, 1
1045  * is returned; on mismatch, 0 is returned. A returned value of 0 means
1046  * that the data or the tag was altered in transit, normally leading to
1047  * wholesale rejection of the complete message.
1048  *
1049  * \param ctx   CCM context structure.
1050  * \param tag   tag value to compare with (up to 16 bytes).
1051  * \return  1 on success (exact match of tag value), 0 otherwise.
1052  */
1053 uint32_t br_ccm_check_tag(br_ccm_context *ctx, const void *tag);
1054
1055 #ifdef __cplusplus
1056 }
1057 #endif
1058
1059 #endif