[u/mdw/catacomb] / hmac.h

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