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

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