Mark dependency on mLib 2.0.0pre4 now.

[u/mdw/catacomb] / hmac.h

/* -*-c-*-
 *
 * $Id: hmac.h,v 1.4 2000/10/15 19:09:20 mdw Exp $
 *
 * Generic code for HMAC and NMAC
 *
 * (c) 1998 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: hmac.h,v $
 * Revision 1.4  2000/10/15 19:09:20  mdw
 * Support HMAC mode for hash functions which need to store more state than
 * the hash output size.
 *
 * Revision 1.3  2000/06/17 11:23:57  mdw
 * New key size interface.
 *
 * Revision 1.2  1999/12/10 23:17:39  mdw
 * Split mode macros into interface and implementation.
 *
 * Revision 1.1  1999/09/03 08:41:12  mdw
 * Initial import.
 *
 */

/*----- Notes on the HMAC and NMAC constructions --------------------------*
 *
 * Designed by Mihir Bellare, Ran Canetti and Hugo Krawczyk, NMAC is a method
 * for constructing keyed message authentication algorithms from unkeyed hash
 * functions.  It has been proven to provide useful security given reasonable
 * assumptions about the underlying hash function.  HMAC is an alternative
 * formulation which doesn't require low-level access to the hash function's
 * implementation.  NMAC was designed to allow MD5 has a suitable underlying
 * hash function, even though doubts were already being raised about its
 * collision resistance.
 */

#ifndef CATACOMB_HMAC_H
#define CATACOMB_HMAC_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <stddef.h>

#include <mLib/bits.h>

#ifndef CATACOMB_GMAC_H
#  include "gmac.h"
#endif

/*----- Macros ------------------------------------------------------------*/

/* --- @HMAC_DECL@ --- *
 *
 * Arguments:	@PRE@, @pre@ = prefixes for the underlying hash function
 *
 * Use:		Creates declarations for the HMAC and NMAC functions.
 */

#define HMAC_DECL(PRE, pre)						\
									\
/* --- An HMAC or NMAC key --- */					\
									\
typedef struct pre##_mackey {						\
  octet ochain[PRE##_STATESZ];		/* Chaining for outer hash */	\
  unsigned ocount;			/* Byte count for outer hash */	\
  octet ichain[PRE##_STATESZ];		/* Chaining for inner hash */	\
  unsigned icount;			/* Byte count for inner hash */	\
} pre##_mackey;								\
									\
/* --- An HMAC or NMAC hashing context --- */				\
									\
typedef struct pre##_macctx {						\
  pre##_ctx ctx;			/* Context for main hashing */	\
  octet chain[PRE##_STATESZ];		/* Chaining for outer hash */	\
  unsigned count;			/* Byte count for outer hash */	\
} pre##_macctx;								\
									\
/* --- Other useful constants --- */					\
									\
extern const octet pre##_mackeysz[];					\
									\
/* --- @pre_nmacinit@ --- *						\
 *									\
 * Arguments:	@pre_macctx *key@ = pointer to a MAC key object		\
 *		@const void *ok@ = pointer to outer hash init vector	\
 *		@const void *ik@ = pointer to inner hash init vector	\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Initializes a MAC key for doing NMAC hashing.		\
 */									\
									\
extern void pre##_nmacinit(pre##_mackey */*key*/,			\
			   const void */*ok*/, const void */*ik*/);	\
									\
/* --- @pre_hmacinit@ --- *						\
 *									\
 * Arguments:	@pre_mackey *key@ = pointer to MAC key object		\
 *		@const void *k@ = pointer to key to use			\
 *		@size_t sz@ = size of key data				\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Initializes a MAC key for doing HMAC hashing.  Keys	\
 *		longer than the hash function's output size aren't very	\
 *		useful, but are accepted.  Keys longer than the hash's	\
 *		block size are also accepted; they are hashed before	\
 *		use, as specified in RFC2104.				\
 */									\
									\
extern void pre##_hmacinit(pre##_mackey */*key*/, 			\
			   const void */*k*/, size_t /*sz*/);		\
									\
/* --- @pre_macinit@ --- *						\
 *									\
 * Arguments:	@pre_macctx *ctx@ = pointer to MAC context block	\
 *		@const pre_mackey *key@ = pointer to MAC key block	\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Instantiates a MAC context from a key block.		\
 */									\
									\
extern void pre##_macinit(pre##_macctx */*ctx*/,			\
			  const pre##_mackey */*key*/);			\
									\
/* --- @pre_machash@ --- *						\
 *									\
 * Arguments:	@pre_macctx *ctx@ = pointer to MAC context block	\
 *		@const void *buf@ = pointer to buffer			\
 *		@size_t sz@ = size of the buffer			\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Hashes a buffer.					\
 */									\
									\
extern void pre##_machash(pre##_macctx */*ctx*/,			\
			  const void */*buf*/, size_t /*sz*/);		\
									\
/* --- @pre_macdone@ --- *						\
 *									\
 * Arguments:	@pre_macctx *ctx@ = pointer to MAC context block	\
 *		@void *mac@ = pointer to buffer to receive MAC		\
 *									\
 * Returns:	---							\
 *									\
 * Use:		Returns the result of a MAC computation.		\
 */									\
									\
extern void pre##_macdone(pre##_macctx */*ctx*/, void */*mac*/);	\
									\
/* --- Generic MAC interface --- */					\
									\
extern const gcmac pre##_hmac;

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif