chiark - git - mdw - catacomb/blob - symm/ocb1.h

   1 /* -*-c-*-
   2  *
   3  * The OCB1 authenticated encryption mode
   4  *
   5  * (c) 2018 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of Catacomb.
  11  *
  12  * Catacomb is free software: you can redistribute it and/or modify it
  13  * under the terms of the GNU Library General Public License as published
  14  * by the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * Catacomb is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with Catacomb.  If not, write to the Free Software
  24  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25  * USA.
  26  */
  27
  28 /*----- Notes on OCB1 -----------------------------------------------------*
  29  *
  30  * OCB was designed in 2001 by Phillip Rogaway, with Mihir Bellare and John
  31  * Black, as a blockcipher-based authenticated encryption scheme which can
  32  * operate on multiple message blocks in parallel and requires only a single
  33  * blockcipher application per message block.  It refines Charanjit Jutla's
  34  * earlier IAPM, which was the first such mode to be proven secure.  This
  35  * version implements the `OCB.PMAC' mode described by Rogaway in 2002, which
  36  * combines the original OCB with PMAC (Rogaway and Black, 2002) into a
  37  * single authenticated-encryption with associated-data (AEAD) scheme.
  38  *
  39  * The patent situation on these efficient authenticated encryption schemes
  40  * is fraught.  IBM hold two patents on Jutla's pioneering work on `IACBC'
  41  * and `IAPM' which can apply (a third was filed at least six years too
  42  * late), and Virgil Gligor and Pompiliu Donescu hold patents on their `XECB'
  43  * and `XCBC' modes; these may or may not apply to OCB.  Rogaway himself
  44  * holds US patents on various versions of OCB, but has issued free licences
  45  * for free (`open source') software, and for all non-military use.  I think
  46  * Catacomb's implementation of OCB falls within the scope of the former
  47  * licence.
  48  *
  49  * Confusingly, Rogaway's 2004 paper `Efficient Instantiations of Tweakable
  50  * Blockciphers and Refinements to Modes OCB and PMAC' named the new versions
  51  * of those modes `OCB1' and `PMAC1'.  The 2011 paper by Krovetz and Rogaway,
  52  * `The Software Performance of Authenticated-Encryption Modes' renamed the
  53  * original 2001 version of OCB as `OCB1', and the 2004 version `OCB2', and
  54  * introduced a new `OCB3'.  I've decided to follow and extend the 2011
  55  * naming, so `OCB1' refers to the 2001 OCB; the 2004 version would be
  56  * `OCB2'.
  57  *
  58  * The OCB specification is clear about how OCB applies to arbitrary block
  59  * sizes.
  60  *
  61  * OCB1 is a fairly well-behaved AEAD mode.  It doesn't require
  62  * precommentment to any lengths, and allows header data to be processed
  63  * independently of any message.  On the other hand, it only accepts nonces
  64  * the same size as the underlying blockcipher's block size, and it buffers
  65  * up to a whole block's worth of data internally, which somewhat complicates
  66  * streaming.
  67  */
  68
  69 #ifndef CATACOMB_OCB1_H
  70 #define CATACOMB_OCB1_H
  71
  72 #ifdef __cplusplus
  73   extern "C" {
  74 #endif
  75
  76 /*----- Header files ------------------------------------------------------*/
  77
  78 #include <stddef.h>
  79
  80 #include <mLib/bits.h>
  81 #include <mLib/buf.h>
  82
  83 #ifndef CATACOMB_GAEAD_H
  84 #  include "gaead.h"
  85 #endif
  86
  87 #ifndef CATACOMB_OCB_H
  88 #  include "ocb.h"
  89 #endif
  90
  91 #ifndef CATACOMB_RSVR_H
  92 #  include "rsvr.h"
  93 #endif
  94
  95 /*----- Macros ------------------------------------------------------------*/
  96
  97 /* --- @OCB1_DECL@ --- *
  98  *
  99  * Arguments:   @PRE@, @pre@ = prefixes for the underlying block cipher
 100  *
 101  * Use:         Creates declarations for OCB1 message-authentication mode.
 102  */
 103
 104 #define OCB1_STRUCTS(PRE, pre, keyty, aadty)                            \
 105                                                                         \
 106 typedef struct keyty {                                                  \
 107   pre##_ctx ctx;                        /* Underlying cipher context */ \
 108   uint32 lxinv[PRE##_BLKSZ/4];          /* Final-block mask */          \
 109   uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */     \
 110 } keyty;                                                                \
 111                                                                         \
 112 typedef struct aadty {                                                  \
 113   keyty k;                              /* Processed key material */    \
 114   uint32 o[PRE##_BLKSZ/4];              /* Current offset */            \
 115   uint32 a[PRE##_BLKSZ/4];              /* Accumulator state */         \
 116   octet b[PRE##_BLKSZ];                 /* Input buffer */              \
 117   unsigned long i;                      /* Block counter */             \
 118   unsigned off;                         /* Offset into buffered data */ \
 119 } aadty;
 120
 121 #define OCB1_DECL(PRE, pre)                                             \
 122                                                                         \
 123 OCB1_STRUCTS(PRE, pre, pre##_ocb1key, pre##_ocb1aadctx)                 \
 124                                                                         \
 125 typedef struct pre##_ocb1ctx {                                          \
 126   /* This is the same as @pre_ocb1aadctx@ above, but the two are        \
 127    * logically distinct and shouldn't be muddled up.                    \
 128    */                                                                   \
 129                                                                         \
 130   pre##_ocb1key k;                      /* Processed key material */    \
 131   uint32 o[PRE##_BLKSZ/4];              /* Current offset */            \
 132   uint32 a[PRE##_BLKSZ/4];              /* Accumulator state */         \
 133   octet b[PRE##_BLKSZ];                 /* Input buffer */              \
 134   unsigned long i;                      /* Block counter */             \
 135   unsigned off;                         /* Offset into buffered data */ \
 136 } pre##_ocb1ctx;                                                        \
 137                                                                         \
 138 extern const rsvr_policy pre##_ocb1policy;                              \
 139                                                                         \
 140 extern const octet pre##_ocb1noncesz[], pre##_ocb1tagsz[];              \
 141                                                                         \
 142 /* --- @pre_ocb1setkey@ --- *                                           \
 143  *                                                                      \
 144  * Arguments:   @pre_ocb1key *key@ = pointer to key block to fill in    \
 145  *              @const void *k@ = pointer to key material               \
 146  *              @size_t ksz@ = size of key material                     \
 147  *                                                                      \
 148  * Returns:     ---                                                     \
 149  *                                                                      \
 150  * Use:         Initializes an OCB1 key block.                          \
 151  */                                                                     \
 152                                                                         \
 153 extern void pre##_ocb1setkey(pre##_ocb1key */*key*/,                    \
 154                              const void */*k*/, size_t /*ksz*/);        \
 155                                                                         \
 156 /* --- @pre_ocb1aadinit@ --- *                                          \
 157  *                                                                      \
 158  * Arguments:   @pre_ocb1aadctx *aad@ = pointer to AAD context          \
 159  *              @const pre_ocb1key *key@ = pointer to key block         \
 160  *                                                                      \
 161  * Returns:     ---                                                     \
 162  *                                                                      \
 163  * Use:         Initializes an OCB1 AAD (`additional authenticated      \
 164  *              data') context associated with a given key.  AAD        \
 165  *              contexts can be copied and/or reused, saving time if    \
 166  *              the AAD for number of messages has a common prefix.     \
 167  *                                                                      \
 168  *              The @key@ doesn't need to be kept around, though        \
 169  *              usually there'll at least be another copy in some OCB1  \
 170  *              operation context because the AAD on its own isn't much \
 171  *              good.                                                   \
 172  */                                                                     \
 173                                                                         \
 174 extern void pre##_ocb1aadinit(pre##_ocb1aadctx */*aad*/,                \
 175                               const pre##_ocb1key */*key*/);            \
 176                                                                         \
 177 /* --- @pre_ocb1aadhash@ --- *                                          \
 178  *                                                                      \
 179  * Arguments:   @pre_ocb1aadctx *aad@ = pointer to AAD context          \
 180  *              @const void *p@ = pointer to AAD material               \
 181  *              @size_t sz@ = length of AAD material                    \
 182  *                                                                      \
 183  * Returns:     ---                                                     \
 184  *                                                                      \
 185  * Use:         Feeds AAD into the context.                             \
 186  */                                                                     \
 187                                                                         \
 188 extern void pre##_ocb1aadhash(pre##_ocb1aadctx */*aad*/,                \
 189                               const void */*p*/, size_t /*sz*/);        \
 190                                                                         \
 191 /* --- @pre_ocb1aadtag@ --- *                                           \
 192  *                                                                      \
 193  * Arguments:   @const pre_ocb1aadctx *aad@ = pointer to context block  \
 194  *              @uint32 *u@ = where to write the tag                    \
 195  *                                                                      \
 196  * Returns:     ---                                                     \
 197  *                                                                      \
 198  * Use:         Finishes processing AAD and produces a tag which can be \
 199  *              mixed with an OCB1 checksum.  This function is exposed  \
 200  *              for internal reasons and is not expected to be          \
 201  *              generally useful.                                       \
 202  */                                                                     \
 203                                                                         \
 204 extern void pre##_ocb1aadtag(const pre##_ocb1aadctx */*aad*/,           \
 205                              uint32 */*t*/);                            \
 206                                                                         \
 207 /* --- @pre_ocb1init@ --- *                                             \
 208  *                                                                      \
 209  * Arguments:   @pre_ocb1ctx *ctx@ = pointer to OCB1 context            \
 210  *              @const pre_ocb1key *key@ = pointer to key block         \
 211  *              @const void *n@ = pointer to nonce                      \
 212  *              @size_t nsz@ = size of nonce                            \
 213  *                                                                      \
 214  * Returns:     Zero on success, @-1@ if the nonce length is bad.       \
 215  *                                                                      \
 216  * Use:         Initialize an OCB1 operation context with a given key.  \
 217  *                                                                      \
 218  *              The original key needn't be kept around any more.       \
 219  */                                                                     \
 220                                                                         \
 221 extern int pre##_ocb1init(pre##_ocb1ctx */*ctx*/,                       \
 222                           const pre##_ocb1key */*k*/,                   \
 223                           const void */*n*/, size_t /*nsz*/);           \
 224                                                                         \
 225 /* --- @pre_ocb1reinit@ --- *                                           \
 226  *                                                                      \
 227  * Arguments:   @pre_ocb1ctx *ctx@ = pointer to OCB1 context            \
 228  *              @const void *n@ = pointer to nonce                      \
 229  *              @size_t nsz@ = size of nonce                            \
 230  *                                                                      \
 231  * Returns:     Zero on success, @-1@ if the nonce length is bad.       \
 232  *                                                                      \
 233  * Use:         Reinitialize an OCB1 operation context, changing the    \
 234  *              nonce.                                                  \
 235  */                                                                     \
 236                                                                         \
 237 extern int pre##_ocb1reinit(pre##_ocb1ctx */*ctx*/,                     \
 238                             const void */*n*/, size_t /*nsz*/);         \
 239                                                                         \
 240 /* --- @pre_ocb1encrypt@ --- *                                          \
 241  *                                                                      \
 242  * Arguments:   @pre_ocb1ctx *ctx@ = pointer to OCB1 operation context  \
 243  *              @const void *src@ = pointer to plaintext message chunk  \
 244  *              @size_t sz@ = size of the plaintext                     \
 245  *              @buf *dst@ = a buffer to write the ciphertext to        \
 246  *                                                                      \
 247  * Returns:     Zero on success; @-1@ on failure.                       \
 248  *                                                                      \
 249  * Use:         Encrypts a chunk of a plaintext message, writing a      \
 250  *              chunk of ciphertext to the output buffer and updating   \
 251  *              the operation state.                                    \
 252  *                                                                      \
 253  *              Note that OCB1 delays output if its input is not a      \
 254  *              whole number of blocks.  This means that the output     \
 255  *              might be smaller or larger the input by up to the block \
 256  *              size.                                                   \
 257  */                                                                     \
 258                                                                         \
 259 extern int pre##_ocb1encrypt(pre##_ocb1ctx */*ctx*/,                    \
 260                              const void */*src*/, size_t /*sz*/,        \
 261                              buf */*dst*/);                             \
 262                                                                         \
 263 /* --- @pre_ocb1decrypt@ --- *                                          \
 264  *                                                                      \
 265  * Arguments:   @pre_ocb1ctx *ctx@ = pointer to OCB1 operation context  \
 266  *              @const void *src@ = pointer to ciphertext message chunk \
 267  *              @size_t sz@ = size of the ciphertext                    \
 268  *              @buf *dst@ = a buffer to write the plaintext to         \
 269  *                                                                      \
 270  * Returns:     Zero on success; @-1@ on failure.                       \
 271  *                                                                      \
 272  * Use:         Decrypts a chunk of a ciphertext message, writing a     \
 273  *              chunk of plaintext to the output buffer and updating    \
 274  *              the operation state.                                    \
 275  *                                                                      \
 276  *              Note that OCB1 delays output if its input is not a      \
 277  *              whole number of blocks.  This means that the output     \
 278  *              might be smaller or larger the input by up to the block \
 279  *              size.                                                   \
 280  */                                                                     \
 281                                                                         \
 282 extern int pre##_ocb1decrypt(pre##_ocb1ctx */*ctx*/,                    \
 283                              const void */*src*/, size_t /*sz*/,        \
 284                              buf */*dst*/);                             \
 285                                                                         \
 286 /* --- @pre_ocb1encryptdone@ --- *                                      \
 287  *                                                                      \
 288  * Arguments:   @pre_ocb1ctx *ctx@ = pointer to an OCB1 context         \
 289  *              @const pre_ocb1aadctx *aad@ = pointer to AAD context,   \
 290  *                      or null                                         \
 291  *              @buf *dst@ = buffer for remaining ciphertext            \
 292  *              @void *tag@ = where to write the tag                    \
 293  *              @size_t tsz@ = length of tag to store                   \
 294  *                                                                      \
 295  * Returns:     Zero on success; @-1@ on failure.                       \
 296  *                                                                      \
 297  * Use:         Completes an OCB1 encryption operation.  The @aad@      \
 298  *              pointer may be null if there is no additional           \
 299  *              authenticated data.  OCB1 delays output, so this will   \
 300  *              cause any remaining buffered plaintext to be encrypted  \
 301  *              and written to @dst@.  Anyway, the function will fail   \
 302  *              if the output buffer is broken.                         \
 303  */                                                                     \
 304                                                                         \
 305 extern int pre##_ocb1encryptdone(pre##_ocb1ctx */*ctx*/,                \
 306                                  const pre##_ocb1aadctx */*aad*/,       \
 307                                  buf */*dst*/,                          \
 308                                  void */*tag*/, size_t /*tsz*/);        \
 309                                                                         \
 310 /* --- @pre_ocb1decryptdone@ --- *                                      \
 311  *                                                                      \
 312  * Arguments:   @pre_ocb1ctx *ctx@ = pointer to an OCB1 context         \
 313  *              @const pre_ocb1aadctx *aad@ = pointer to AAD context,   \
 314  *                      or null                                         \
 315  *              @buf *dst@ = buffer for remaining plaintext             \
 316  *              @const void *tag@ = tag to verify                       \
 317  *              @size_t tsz@ = length of tag                            \
 318  *                                                                      \
 319  * Returns:     @+1@ for complete success; @0@ if tag verification      \
 320  *              failed; @-1@ for other kinds of errors.                 \
 321  *                                                                      \
 322  * Use:         Completes an OCB1 decryption operation.  The @aad@      \
 323  *              pointer may be null if there is no additional           \
 324  *              authenticated data.  OCB1 delays output, so this will   \
 325  *              cause any remaining buffered ciphertext to be decrypted \
 326  *              and written to @dst@.  Anyway, the function will fail   \
 327  *              if the output buffer is broken.                         \
 328  */                                                                     \
 329                                                                         \
 330 extern int pre##_ocb1decryptdone(pre##_ocb1ctx */*ctx*/,                \
 331                                  const pre##_ocb1aadctx */*aad*/,       \
 332                                  buf */*dst*/,                          \
 333                                  const void */*tag*/, size_t /*tsz*/);  \
 334                                                                         \
 335 /* --- Generic AEAD interface --- */                                    \
 336                                                                         \
 337 extern const gcaead pre##_ocb1;
 338
 339 /*----- That's all, folks -------------------------------------------------*/
 340
 341 #ifdef __cplusplus
 342   }
 343 #endif
 344
 345 #endif