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

   1 /* -*-c-*-
   2  *
   3  * Generic code for HMAC and NMAC
   4  *
   5  * (c) 1998 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
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * Catacomb is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU 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
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 /*----- Notes on the HMAC and NMAC constructions --------------------------*
  29  *
  30  * Designed by Mihir Bellare, Ran Canetti and Hugo Krawczyk, NMAC is a method
  31  * for constructing keyed message authentication algorithms from unkeyed hash
  32  * functions.  It has been proven to provide useful security given reasonable
  33  * assumptions about the underlying hash function.  HMAC is an alternative
  34  * formulation which doesn't require low-level access to the hash function's
  35  * implementation.  NMAC was designed to allow MD5 has a suitable underlying
  36  * hash function, even though doubts were already being raised about its
  37  * collision resistance.
  38  */
  39
  40 #ifndef CATACOMB_HMAC_H
  41 #define CATACOMB_HMAC_H
  42
  43 #ifdef __cplusplus
  44   extern "C" {
  45 #endif
  46
  47 /*----- Header files ------------------------------------------------------*/
  48
  49 #include <stddef.h>
  50
  51 #include <mLib/bits.h>
  52
  53 #ifndef CATACOMB_GMAC_H
  54 #  include "gmac.h"
  55 #endif
  56
  57 /*----- Macros ------------------------------------------------------------*/
  58
  59 /* --- @HMAC_DECL@ --- *
  60  *
  61  * Arguments:   @PRE@, @pre@ = prefixes for the underlying hash function
  62  *
  63  * Use:         Creates declarations for the HMAC and NMAC functions.
  64  */
  65
  66 #define HMAC_DECL(PRE, pre)                                             \
  67                                                                         \
  68 /* --- An HMAC or NMAC key --- */                                       \
  69                                                                         \
  70 typedef struct pre##_mackey {                                           \
  71   octet ochain[PRE##_STATESZ];          /* Chaining for outer hash */   \
  72   unsigned ocount;                      /* Byte count for outer hash */ \
  73   octet ichain[PRE##_STATESZ];          /* Chaining for inner hash */   \
  74   unsigned icount;                      /* Byte count for inner hash */ \
  75 } pre##_mackey;                                                         \
  76                                                                         \
  77 /* --- An HMAC or NMAC hashing context --- */                           \
  78                                                                         \
  79 typedef struct pre##_macctx {                                           \
  80   pre##_ctx ctx;                        /* Context for main hashing */  \
  81   octet chain[PRE##_STATESZ];           /* Chaining for outer hash */   \
  82   unsigned count;                       /* Byte count for outer hash */ \
  83 } pre##_macctx;                                                         \
  84                                                                         \
  85 /* --- Other useful constants --- */                                    \
  86                                                                         \
  87 extern const octet pre##_hmackeysz[];                                   \
  88 extern const octet pre##_nmackeysz[];                                   \
  89 extern const octet pre##_sslmackeysz[];                                 \
  90                                                                         \
  91 /* --- @pre_nmacinit@ --- *                                             \
  92  *                                                                      \
  93  * Arguments:   @pre_macctx *key@ = pointer to a MAC key object         \
  94  *              @const void *ok@ = pointer to outer hash init vector    \
  95  *              @const void *ik@ = pointer to inner hash init vector    \
  96  *                                                                      \
  97  * Returns:     ---                                                     \
  98  *                                                                      \
  99  * Use:         Initializes a MAC key for doing NMAC hashing.           \
 100  */                                                                     \
 101                                                                         \
 102 extern void pre##_nmacinit(pre##_mackey */*key*/,                       \
 103                            const void */*ok*/, const void */*ik*/);     \
 104                                                                         \
 105 /* --- @pre_hmacinit@ --- *                                             \
 106  *                                                                      \
 107  * Arguments:   @pre_mackey *key@ = pointer to MAC key object           \
 108  *              @const void *k@ = pointer to key to use                 \
 109  *              @size_t sz@ = size of key data                          \
 110  *                                                                      \
 111  * Returns:     ---                                                     \
 112  *                                                                      \
 113  * Use:         Initializes a MAC key for doing HMAC hashing.  Keys     \
 114  *              longer than the hash function's output size aren't very \
 115  *              useful, but are accepted.  Keys longer than the hash's  \
 116  *              block size are also accepted; they are hashed before    \
 117  *              use, as specified in RFC2104.                           \
 118  */                                                                     \
 119                                                                         \
 120 extern void pre##_hmacinit(pre##_mackey */*key*/,                       \
 121                            const void */*k*/, size_t /*sz*/);           \
 122                                                                         \
 123 /* --- @pre_sslmacinit@ --- *                                           \
 124  *                                                                      \
 125  * Arguments:   @pre_mackey *key@ = pointer to MAC key object           \
 126  *              @const void *k@ = pointer to key to use                 \
 127  *              @size_t sz@ = size of key data                          \
 128  *                                                                      \
 129  * Returns:     ---                                                     \
 130  *                                                                      \
 131  * Use:         Initializes a MAC key for doing hasing using the SSL3   \
 132  *              variant of HMAC.                                        \
 133  */                                                                     \
 134                                                                         \
 135 extern void pre##_sslmacinit(pre##_mackey */*key*/,                     \
 136                              const void */*k*/, size_t /*sz*/);         \
 137                                                                         \
 138 /* --- @pre_macinit@ --- *                                              \
 139  *                                                                      \
 140  * Arguments:   @pre_macctx *ctx@ = pointer to MAC context block        \
 141  *              @const pre_mackey *key@ = pointer to MAC key block      \
 142  *                                                                      \
 143  * Returns:     ---                                                     \
 144  *                                                                      \
 145  * Use:         Instantiates a MAC context from a key block.            \
 146  */                                                                     \
 147                                                                         \
 148 extern void pre##_macinit(pre##_macctx */*ctx*/,                        \
 149                           const pre##_mackey */*key*/);                 \
 150                                                                         \
 151 /* --- @pre_machash@ --- *                                              \
 152  *                                                                      \
 153  * Arguments:   @pre_macctx *ctx@ = pointer to MAC context block        \
 154  *              @const void *buf@ = pointer to buffer                   \
 155  *              @size_t sz@ = size of the buffer                        \
 156  *                                                                      \
 157  * Returns:     ---                                                     \
 158  *                                                                      \
 159  * Use:         Hashes a buffer.                                        \
 160  */                                                                     \
 161                                                                         \
 162 extern void pre##_machash(pre##_macctx */*ctx*/,                        \
 163                           const void */*buf*/, size_t /*sz*/);          \
 164                                                                         \
 165 /* --- @pre_macdone@ --- *                                              \
 166  *                                                                      \
 167  * Arguments:   @pre_macctx *ctx@ = pointer to MAC context block        \
 168  *              @void *mac@ = pointer to buffer to receive MAC          \
 169  *                                                                      \
 170  * Returns:     ---                                                     \
 171  *                                                                      \
 172  * Use:         Returns the result of a MAC computation.                \
 173  */                                                                     \
 174                                                                         \
 175 extern void pre##_macdone(pre##_macctx */*ctx*/, void */*mac*/);        \
 176                                                                         \
 177 /* --- Generic MAC interface --- */                                     \
 178                                                                         \
 179 extern const gcmac pre##_hmac;                                          \
 180 extern const gcmac pre##_nmac;                                          \
 181 extern const gcmac pre##_sslmac;
 182
 183 /*----- That's all, folks -------------------------------------------------*/
 184
 185 #ifdef __cplusplus
 186   }
 187 #endif
 188
 189 #endif