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

   1 /* -*-c-*-
   2  *
   3  * The PMAC1 message authentication 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 PMAC1 ----------------------------------------------------*
  29  *
  30  * PMAC was designed in 2002 by John Black and Phillip Rogaway as a
  31  * blockcipher-based MAC which can operate on multiple message blocks in
  32  * parallel.  Unfortunately, Rogaway applied for patents on PMAC, and as a
  33  * result it saw limited adoption.  Rogaway has since abandoned the patent
  34  * applications, and PMAC is free for all uses.
  35  *
  36  * Confusingly, Rogaway's 2004 paper `Efficient Instantiations of Tweakable
  37  * Blockciphers and Refinements to Modes OCB and PMAC' named the new versions
  38  * of those modes `OCB1' and `PMAC1'.  The 2011 paper by Krovetz and Rogaway,
  39  * `The Software Performance of Authenticated-Encryption Modes' renamed the
  40  * original 2001 version of OCB as `OCB1', and the 2004 version `OCB2', and
  41  * introduced a new `OCB3', but does not mention PMAC.  (PMAC is used as-is
  42  * in the 2001 and 2004 versions of OCB, to process header data; the header
  43  * processing in the 2011 version of OCB is not a secure standalone MAC, so
  44  * there is no PMAC3.)  I've decided to follow and extend the 2011 naming, so
  45  * `PMAC1' refers to the 2002 PMAC; the 2004 version would be `PMAC2'.
  46  *
  47  * This implementation does not currently attempt to process blocks in
  48  * parallel, though this is a possible future improvement.
  49  */
  50
  51 #ifndef CATACOMB_PMAC1_H
  52 #define CATACOMB_PMAC1_H
  53
  54 #ifdef __cplusplus
  55   extern "C" {
  56 #endif
  57
  58 /*----- Header files ------------------------------------------------------*/
  59
  60 #include <stddef.h>
  61
  62 #include <mLib/bits.h>
  63
  64 #ifndef CATACOMB_GMAC_H
  65 #  include "gmac.h"
  66 #endif
  67
  68 #ifndef CATACOMB_OCB1_H
  69 #  include "ocb1.h"
  70 #endif
  71
  72 /*----- Macros ------------------------------------------------------------*/
  73
  74 /* --- @PMAC1_DECL@ --- *
  75  *
  76  * Arguments:   @PRE@, @pre@ = prefixes for the underlying block cipher
  77  *
  78  * Use:         Creates declarations for PMAC1 message-authentication mode.
  79  *
  80  *              Most of these are aliases for OCB1 operations: see
  81  *              <catacomb/ocb1.h> for their documentation.
  82  */
  83
  84 #define PMAC1_DECL(PRE, pre)                                            \
  85                                                                         \
  86 OCB1_STRUCTS(PRE, pre, pre##_pmac1key, pre##_pmac1ctx)                  \
  87                                                                         \
  88 extern void pre##_pmac1setkey(pre##_pmac1key */*key*/,                  \
  89                               const void */*k*/, size_t /*ksz*/);       \
  90                                                                         \
  91 extern void pre##_pmac1init(pre##_pmac1ctx */*ctx*/,                    \
  92                             const pre##_pmac1key */*k*/);               \
  93                                                                         \
  94 extern void pre##_pmac1hash(pre##_pmac1ctx */*ctx*/,                    \
  95                             const void */*p*/, size_t /*sz*/);          \
  96                                                                         \
  97 /* --- @pre_pmac1done@ --- *                                            \
  98  *                                                                      \
  99  * Arguments:   @pre_pmac1ctx *ctx@ = pointer to PMAC1 context block    \
 100  *              @void *t@ = where to write the tag                      \
 101  *                                                                      \
 102  * Returns:     ---                                                     \
 103  *                                                                      \
 104  * Use:         Finishes a MAC operation and produces the tag.          \
 105  */                                                                     \
 106                                                                         \
 107 extern void pre##_pmac1done(pre##_pmac1ctx */*ctx*/, void */*t*/);      \
 108                                                                         \
 109 /* --- Generic MAC interface --- */                                     \
 110                                                                         \
 111 extern const gcmac pre##_pmac1;
 112
 113 /*----- That's all, folks -------------------------------------------------*/
 114
 115 #ifdef __cplusplus
 116   }
 117 #endif
 118
 119 #endif