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

   1 /* -*-c-*-
   2  *
   3  * $Id: hmac.h,v 1.3 2000/06/17 11:23:57 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 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: hmac.h,v $
  33  * Revision 1.3  2000/06/17 11:23:57  mdw
  34  * New key size interface.
  35  *
  36  * Revision 1.2  1999/12/10 23:17:39  mdw
  37  * Split mode macros into interface and implementation.
  38  *
  39  * Revision 1.1  1999/09/03 08:41:12  mdw
  40  * Initial import.
  41  *
  42  */
  43
  44 /*----- Notes on the HMAC and NMAC constructions --------------------------*
  45  *
  46  * Designed by Mihir Bellare, Ran Canetti and Hugo Krawczyk, NMAC is a method
  47  * for constructing keyed message authentication algorithms from unkeyed hash
  48  * functions.  It has been proven to provide useful security given reasonable
  49  * assumptions about the underlying hash function.  HMAC is an alternative
  50  * formulation which doesn't require low-level access to the hash function's
  51  * implementation.  NMAC was designed to allow MD5 has a suitable underlying
  52  * hash function, even though doubts were already being raised about its
  53  * collision resistance.
  54  */
  55
  56 #ifndef CATACOMB_HMAC_H
  57 #define CATACOMB_HMAC_H
  58
  59 #ifdef __cplusplus
  60   extern "C" {
  61 #endif
  62
  63 /*----- Header files ------------------------------------------------------*/
  64
  65 #include <stddef.h>
  66
  67 #include <mLib/bits.h>
  68
  69 #ifndef CATACOMB_GMAC_H
  70 #  include "gmac.h"
  71 #endif
  72
  73 /*----- Macros ------------------------------------------------------------*/
  74
  75 /* --- @HMAC_DECL@ --- *
  76  *
  77  * Arguments:   @PRE@, @pre@ = prefixes for the underlying hash function
  78  *
  79  * Use:         Creates declarations for the HMAC and NMAC functions.
  80  */
  81
  82 #define HMAC_DECL(PRE, pre)                                             \
  83                                                                         \
  84 /* --- An HMAC or NMAC key --- */                                       \
  85                                                                         \
  86 typedef struct pre##_mackey {                                           \
  87   octet ochain[PRE##_HASHSZ];           /* Chaining for outer hash */   \
  88   unsigned ocount;                      /* Byte count for outer hash */ \
  89   octet ichain[PRE##_HASHSZ];           /* Chaining for inner hash */   \
  90   unsigned icount;                      /* Byte count for inner hash */ \
  91 } pre##_mackey;                                                         \
  92                                                                         \
  93 /* --- An HMAC or NMAC hashing context --- */                           \
  94                                                                         \
  95 typedef struct pre##_macctx {                                           \
  96   pre##_ctx ctx;                        /* Context for main hashing */  \
  97   octet chain[PRE##_HASHSZ];            /* Chaining for outer hash */   \
  98   unsigned count;                       /* Byte count for outer hash */ \
  99 } pre##_macctx;                                                         \
 100                                                                         \
 101 /* --- Other useful constants --- */                                    \
 102                                                                         \
 103 extern const octet pre##_mackeysz[];                                    \
 104                                                                         \
 105 /* --- @pre_nmacinit@ --- *                                             \
 106  *                                                                      \
 107  * Arguments:   @pre_macctx *key@ = pointer to a MAC key object         \
 108  *              @const void *ok@ = pointer to outer hash init vector    \
 109  *              @const void *ik@ = pointer to inner hash init vector    \
 110  *                                                                      \
 111  * Returns:     ---                                                     \
 112  *                                                                      \
 113  * Use:         Initializes a MAC key for doing NMAC hashing.           \
 114  */                                                                     \
 115                                                                         \
 116 extern void pre##_nmacinit(pre##_mackey */*key*/,                       \
 117                            const void */*ok*/, const void */*ik*/);     \
 118                                                                         \
 119 /* --- @pre_hmacinit@ --- *                                             \
 120  *                                                                      \
 121  * Arguments:   @pre_mackey *key@ = pointer to MAC key object           \
 122  *              @const void *k@ = pointer to key to use                 \
 123  *              @size_t sz@ = size of key data                          \
 124  *                                                                      \
 125  * Returns:     ---                                                     \
 126  *                                                                      \
 127  * Use:         Initializes a MAC key for doing HMAC hashing.  Keys     \
 128  *              longer than the hash function's output size aren't very \
 129  *              useful, but are accepted.  Keys longer than the hash's  \
 130  *              block size are also accepted; they are hashed before    \
 131  *              use, as specified in RFC2104.                           \
 132  */                                                                     \
 133                                                                         \
 134 extern void pre##_hmacinit(pre##_mackey */*key*/,                       \
 135                            const void */*k*/, size_t /*sz*/);           \
 136                                                                         \
 137 /* --- @pre_macinit@ --- *                                              \
 138  *                                                                      \
 139  * Arguments:   @pre_macctx *ctx@ = pointer to MAC context block        \
 140  *              @const pre_mackey *key@ = pointer to MAC key block      \
 141  *                                                                      \
 142  * Returns:     ---                                                     \
 143  *                                                                      \
 144  * Use:         Instantiates a MAC context from a key block.            \
 145  */                                                                     \
 146                                                                         \
 147 extern void pre##_macinit(pre##_macctx */*ctx*/,                        \
 148                           const pre##_mackey */*key*/);                 \
 149                                                                         \
 150 /* --- @pre_machash@ --- *                                              \
 151  *                                                                      \
 152  * Arguments:   @pre_macctx *ctx@ = pointer to MAC context block        \
 153  *              @const void *buf@ = pointer to buffer                   \
 154  *              @size_t sz@ = size of the buffer                        \
 155  *                                                                      \
 156  * Returns:     ---                                                     \
 157  *                                                                      \
 158  * Use:         Hashes a buffer.                                        \
 159  */                                                                     \
 160                                                                         \
 161 extern void pre##_machash(pre##_macctx */*ctx*/,                        \
 162                           const void */*buf*/, size_t /*sz*/);          \
 163                                                                         \
 164 /* --- @pre_macdone@ --- *                                              \
 165  *                                                                      \
 166  * Arguments:   @pre_macctx *ctx@ = pointer to MAC context block        \
 167  *              @void *mac@ = pointer to buffer to receive MAC          \
 168  *                                                                      \
 169  * Returns:     ---                                                     \
 170  *                                                                      \
 171  * Use:         Returns the result of a MAC computation.                \
 172  */                                                                     \
 173                                                                         \
 174 extern void pre##_macdone(pre##_macctx */*ctx*/, void */*mac*/);        \
 175                                                                         \
 176 /* --- Generic MAC interface --- */                                     \
 177                                                                         \
 178 extern const gcmac pre##_hmac;
 179
 180 /*----- That's all, folks -------------------------------------------------*/
 181
 182 #ifdef __cplusplus
 183   }
 184 #endif
 185
 186 #endif