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

   1 /* -*-c-*-
   2  *
   3  * The OCB3 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 OCB3 -----------------------------------------------------*
  29  *
  30  * OCB3 was designed in 2011 by Phillip Rogaway and Ted Krovetz, building ten
  31  * years of earlier work by Rogaway, Bellare, and Black, and refining Jutla's
  32  * pioneering work on IACBC and IAPM.  OCB3 is an efficient `authenticated
  33  * encryption with associated data' (AEAD) scheme which requires only one
  34  * blockcipher application per message block.
  35  *
  36  * The patent situation on these efficient authenticated encryption schemes
  37  * is fraught.  IBM hold two patents on Jutla's pioneering work on `IACBC'
  38  * and `IAPM' which can apply (a third was filed at least six years too
  39  * late), and Virgil Gligor and Pompiliu Donescu hold patents on their `XECB'
  40  * and `XCBC' modes; these may or may not apply to OCB.  Rogaway himself
  41  * holds US patents on various versions of OCB, but has issued free licences
  42  * for free (`open source') software, and for all non-military use.  I think
  43  * Catacomb's implementation of OCB falls within the scope of the former
  44  * licence.
  45  *
  46  * OCB3 has optimized for short messages with `similar' nonces, where
  47  * `similar' means `all but the low bits in the last byte are equal'; exactly
  48  * how many bits depends on the block length in a rather complicated manner.
  49  * This implementation supports this optimization through @pre_ocb3reinit@
  50  * (which compares the new nonce against the old one to see whether it can
  51  * make use of the similarity), and, more directly, through @pre_ocb3step@,
  52  * which (effectively) advances the nonce as a big-endian counter.
  53  *
  54  * OCB3 was originally defined only for 128-bit blockciphers, and extending
  55  * it to other sizes is nontrivial, but this has been done by Ted Krovetz in
  56  * I-D draft-krovetz-ocb-wideblock-00 (following initial prompting from, err,
  57  * me).
  58  *
  59  * OCB3 is a fairly well-behaved AEAD mode.  It doesn't require
  60  * precommentment to the header or message lengths, but does require
  61  * precommitment to the tag length.  It permits header data to be processed
  62  * independently of any message.  It only accepts nonces the same size as the
  63  * underlying blockcipher's block size, and it buffers up to a whole block's
  64  * worth of data internally, which somewhat complicates streaming.
  65  */
  66
  67 #ifndef CATACOMB_OCB3_H
  68 #define CATACOMB_OCB3_H
  69
  70 #ifdef __cplusplus
  71   extern "C" {
  72 #endif
  73
  74 /*----- Header files ------------------------------------------------------*/
  75
  76 #include <stddef.h>
  77
  78 #include <mLib/bits.h>
  79 #include <mLib/buf.h>
  80
  81 #ifndef CATACOMB_GAEAD_H
  82 #  include "gaead.h"
  83 #endif
  84
  85 #ifndef CATACOMB_OCB_H
  86 #  include "ocb.h"
  87 #endif
  88
  89 /*----- Macros ------------------------------------------------------------*/
  90
  91 /* --- @OCB3_DECL@ --- *
  92  *
  93  * Arguments:   @PRE@, @pre@ = prefixes for the underlying block cipher
  94  *
  95  * Use:         Creates declarations for OCB3 message-authentication mode.
  96  */
  97
  98 #define OCB3_NSZMAX(PRE) (PRE##_BLKSZ - (PRE##_BLKSZ <= 16 ? 1 : 2))
  99
 100 #define OCB3_DECL(PRE, pre)                                             \
 101                                                                         \
 102 typedef struct pre##_ocb3key {                                          \
 103   pre##_ctx ctx;                        /* Underlying cipher context */ \
 104   uint32 lstar[PRE##_BLKSZ/4];          /* Partial-block mask */        \
 105   uint32 ldollar[PRE##_BLKSZ/4];        /* Checksum mask */             \
 106   uint32 lmask[OCB_NCALC][PRE##_BLKSZ/4]; /* Precalculated masks */     \
 107 } pre##_ocb3key;                                                        \
 108                                                                         \
 109 typedef struct pre##_ocb3aadctx {                                       \
 110   pre##_ocb3key k;                      /* Processed key material */    \
 111   uint32 o[PRE##_BLKSZ/4];              /* Current offset */            \
 112   uint32 a[PRE##_BLKSZ/4];              /* Accumulator state */         \
 113   octet b[PRE##_BLKSZ];                 /* Input buffer */              \
 114   unsigned long i;                      /* Block counter */             \
 115   unsigned off;                         /* Offset into buffered data */ \
 116 } pre##_ocb3aadctx;                                                     \
 117                                                                         \
 118 typedef struct pre##_ocb3ctx {                                          \
 119   pre##_ocb3key k;                      /* Processed key material */    \
 120   unsigned nix, tsz;                    /* Nonce index and tag size */  \
 121   uint32 nbase[PRE##_BLKSZ/2];          /* Current base nonce */        \
 122   uint32 nstretch[PRE##_BLKSZ/2];       /* Stretched nonce material */  \
 123   uint32 o[PRE##_BLKSZ/4];              /* Current offset */            \
 124   uint32 a[PRE##_BLKSZ/4];              /* Accumulator state */         \
 125   octet b[PRE##_BLKSZ];                 /* Input buffer */              \
 126   unsigned long i;                      /* Block counter */             \
 127   unsigned off;                         /* Offset into buffered data */ \
 128 } pre##_ocb3ctx;                                                        \
 129                                                                         \
 130 extern const octet pre##_ocb3noncesz[], pre##_ocb3tagsz[];              \
 131                                                                         \
 132 /* --- @pre_ocb3setkey@ --- *                                           \
 133  *                                                                      \
 134  * Arguments:   @pre_ocb3key *key@ = pointer to key block to fill in    \
 135  *              @const void *k@ = pointer to key material               \
 136  *              @size_t ksz@ = size of key material                     \
 137  *                                                                      \
 138  * Returns:     ---                                                     \
 139  *                                                                      \
 140  * Use:         Initializes an OCB3 key block.                          \
 141  */                                                                     \
 142                                                                         \
 143 extern void pre##_ocb3setkey(pre##_ocb3key */*key*/,                    \
 144                              const void */*k*/, size_t /*ksz*/);        \
 145                                                                         \
 146 /* --- @pre_ocb3aadinit@ --- *                                          \
 147  *                                                                      \
 148  * Arguments:   @pre_ocb3aadctx *aad@ = pointer to AAD context          \
 149  *              @const pre_ocb3key *key@ = pointer to key block         \
 150  *                                                                      \
 151  * Returns:     ---                                                     \
 152  *                                                                      \
 153  * Use:         Initializes an OCB3 AAD (`additional authenticated      \
 154  *              data') context associated with a given key.  AAD        \
 155  *              contexts can be copied and/or reused, saving time if    \
 156  *              the AAD for number of messages has a common prefix.     \
 157  *                                                                      \
 158  *              The @key@ doesn't need to be kept around, though        \
 159  *              usually there'll at least be another copy in some OCB3  \
 160  *              operation context because the AAD on its own isn't much \
 161  *              good.                                                   \
 162  */                                                                     \
 163                                                                         \
 164 extern void pre##_ocb3aadinit(pre##_ocb3aadctx */*aad*/,                \
 165                               const pre##_ocb3key */*key*/);            \
 166                                                                         \
 167 /* --- @pre_ocb3aadhash@ --- *                                          \
 168  *                                                                      \
 169  * Arguments:   @pre_ocb3aadctx *aad@ = pointer to AAD context          \
 170  *              @const void *p@ = pointer to AAD material               \
 171  *              @size_t sz@ = length of AAD material                    \
 172  *                                                                      \
 173  * Returns:     ---                                                     \
 174  *                                                                      \
 175  * Use:         Feeds AAD into the context.                             \
 176  */                                                                     \
 177                                                                         \
 178 extern void pre##_ocb3aadhash(pre##_ocb3aadctx */*aad*/,                \
 179                               const void */*p*/, size_t /*sz*/);        \
 180                                                                         \
 181 /* --- @pre_ocb3init@ --- *                                             \
 182  *                                                                      \
 183  * Arguments:   @pre_ocb3ctx *ctx@ = pointer to OCB3 context            \
 184  *              @const pre_ocb3key *key@ = pointer to key block         \
 185  *              @const void *n@ = pointer to nonce                      \
 186  *              @size_t nsz@ = size of nonce                            \
 187  *              @size_t tsz@ = tag length                               \
 188  *                                                                      \
 189  * Returns:     Zero on success, @-1@ if the nonce or tag length is     \
 190  *              bad.                                                    \
 191  *                                                                      \
 192  * Use:         Initialize an OCB3 operation context with a given key.  \
 193  *                                                                      \
 194  *              The original key needn't be kept around any more.       \
 195  */                                                                     \
 196                                                                         \
 197 extern int pre##_ocb3init(pre##_ocb3ctx */*ctx*/,                       \
 198                           const pre##_ocb3key */*k*/,                   \
 199                           const void */*n*/, size_t /*nsz*/,            \
 200                           size_t /*tsz*/);                              \
 201                                                                         \
 202 /* --- @pre_ocb3reinit@ --- *                                           \
 203  *                                                                      \
 204  * Arguments:   @pre_ocb3ctx *ctx@ = pointer to OCB3 context            \
 205  *              @const void *n@ = pointer to nonce                      \
 206  *              @size_t nsz@ = size of nonce                            \
 207  *              @size_t tsz@ = tag length                               \
 208  *                                                                      \
 209  * Returns:     Zero on success, @-1@ if the nonce or tag length is     \
 210  *              bad.                                                    \
 211  *                                                                      \
 212  * Use:         Reinitialize an OCB3 operation context, changing the    \
 213  *              nonce and/or tag length.                                \
 214  */                                                                     \
 215                                                                         \
 216 extern int pre##_ocb3reinit(pre##_ocb3ctx */*ctx*/,                     \
 217                             const void */*n*/, size_t /*nsz*/,          \
 218                             size_t /*tsz*/);                            \
 219                                                                         \
 220 /* --- @pre_ocb3step@ --- *                                             \
 221  *                                                                      \
 222  * Arguments:   @pre_ocb3ctx *ctx@ = pointer to OCB3 context            \
 223  *                                                                      \
 224  * Returns:     ---                                                     \
 225  *                                                                      \
 226  * Use:         Reinitialize an OCB3 operation context, stepping to     \
 227  *              the `next' nonce along.                                 \
 228  */                                                                     \
 229                                                                         \
 230 extern void pre##_ocb3step(pre##_ocb3ctx */*ctx*/);                     \
 231                                                                         \
 232 /* --- @pre_ocb3encrypt@ --- *                                          \
 233  *                                                                      \
 234  * Arguments:   @pre_ocb3ctx *ctx@ = pointer to OCB3 operation context  \
 235  *              @const void *src@ = pointer to plaintext message chunk  \
 236  *              @size_t sz@ = size of the plaintext                     \
 237  *              @buf *dst@ = a buffer to write the ciphertext to        \
 238  *                                                                      \
 239  * Returns:     Zero on success; @-1@ on failure.                       \
 240  *                                                                      \
 241  * Use:         Encrypts a chunk of a plaintext message, writing a      \
 242  *              chunk of ciphertext to the output buffer and updating   \
 243  *              the operation state.                                    \
 244  *                                                                      \
 245  *              Note that OCB3 delays output if its input is not a      \
 246  *              whole number of blocks.  This means that the output     \
 247  *              might be smaller or larger the input by up to the block \
 248  *              size.                                                   \
 249  */                                                                     \
 250                                                                         \
 251 extern int pre##_ocb3encrypt(pre##_ocb3ctx */*ctx*/,                    \
 252                              const void */*src*/, size_t /*sz*/,        \
 253                              buf */*dst*/);                             \
 254                                                                         \
 255 /* --- @pre_ocb3decrypt@ --- *                                          \
 256  *                                                                      \
 257  * Arguments:   @pre_ocb3ctx *ctx@ = pointer to OCB3 operation context  \
 258  *              @const void *src@ = pointer to ciphertext message chunk \
 259  *              @size_t sz@ = size of the ciphertext                    \
 260  *              @buf *dst@ = a buffer to write the plaintext to         \
 261  *                                                                      \
 262  * Returns:     Zero on success; @-1@ on failure.                       \
 263  *                                                                      \
 264  * Use:         Decrypts a chunk of a ciphertext message, writing a     \
 265  *              chunk of plaintext to the output buffer and updating    \
 266  *              the operation state.                                    \
 267  *                                                                      \
 268  *              Note that OCB3 delays output if its input is not a      \
 269  *              whole number of blocks.  This means that the output     \
 270  *              might be smaller or larger the input by up to the block \
 271  *              size.                                                   \
 272  */                                                                     \
 273                                                                         \
 274 extern int pre##_ocb3decrypt(pre##_ocb3ctx */*ctx*/,                    \
 275                              const void */*src*/, size_t /*sz*/,        \
 276                              buf */*dst*/);                             \
 277                                                                         \
 278 /* --- @pre_ocb3encryptdone@ --- *                                      \
 279  *                                                                      \
 280  * Arguments:   @pre_ocb3ctx *ctx@ = pointer to an OCB3 context         \
 281  *              @const pre_ocb3aadctx *aad@ = pointer to AAD context,   \
 282  *                      or null                                         \
 283  *              @buf *dst@ = buffer for remaining ciphertext            \
 284  *              @void *tag@ = where to write the tag                    \
 285  *              @size_t tsz@ = length of tag to store                   \
 286  *                                                                      \
 287  * Returns:     Zero on success; @-1@ on failure.                       \
 288  *                                                                      \
 289  * Use:         Completes an OCB3 encryption operation.  The @aad@      \
 290  *              pointer may be null if there is no additional           \
 291  *              authenticated data.  OCB3 delays output, so this will   \
 292  *              cause any remaining buffered plaintext to be encrypted  \
 293  *              and written to @dst@.  Anyway, the function will fail   \
 294  *              if the output buffer is broken.                         \
 295  */                                                                     \
 296                                                                         \
 297 extern int pre##_ocb3encryptdone(pre##_ocb3ctx */*ctx*/,                \
 298                                  const pre##_ocb3aadctx */*aad*/,       \
 299                                  buf */*dst*/,                          \
 300                                  void */*tag*/, size_t /*tsz*/);        \
 301                                                                         \
 302 /* --- @pre_ocb3decryptdone@ --- *                                      \
 303  *                                                                      \
 304  * Arguments:   @pre_ocb3ctx *ctx@ = pointer to an OCB3 context         \
 305  *              @const pre_ocb3aadctx *aad@ = pointer to AAD context,   \
 306  *                      or null                                         \
 307  *              @buf *dst@ = buffer for remaining plaintext             \
 308  *              @const void *tag@ = tag to verify                       \
 309  *              @size_t tsz@ = length of tag                            \
 310  *                                                                      \
 311  * Returns:     @+1@ for complete success; @0@ if tag verification      \
 312  *              failed; @-1@ for other kinds of errors.                 \
 313  *                                                                      \
 314  * Use:         Completes an OCB3 decryption operation.  The @aad@      \
 315  *              pointer may be null if there is no additional           \
 316  *              authenticated data.  OCB3 delays output, so this will   \
 317  *              cause any remaining buffered ciphertext to be decrypted \
 318  *              and written to @dst@.  Anyway, the function will fail   \
 319  *              if the output buffer is broken.                         \
 320  */                                                                     \
 321                                                                         \
 322 extern int pre##_ocb3decryptdone(pre##_ocb3ctx */*ctx*/,                \
 323                                  const pre##_ocb3aadctx */*aad*/,       \
 324                                  buf */*dst*/,                          \
 325                                  const void */*tag*/, size_t /*tsz*/);  \
 326                                                                         \
 327 /* --- Generic AEAD interface --- */                                    \
 328                                                                         \
 329 extern const gcaead pre##_ocb3;
 330
 331 /*----- That's all, folks -------------------------------------------------*/
 332
 333 #ifdef __cplusplus
 334   }
 335 #endif
 336
 337 #endif