Source/charon/transforms/hmac.h

   1 /**
   2  * @file hmac.h
   3  *
   4  * @brief Interface of hmac_t.
   5  */
   6
   7 /*
   8  * Copyright (C) 2005 Jan Hutter, Martin Willi
   9  * Hochschule fuer Technik Rapperswil
  10  *
  11  * This program is free software; you can redistribute it and/or modify it
  12  * under the terms of the GNU General Public License as published by the
  13  * Free Software Foundation; either version 2 of the License, or (at your
  14  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  18  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  19  * for more details.
  20  */
  21
  22 #ifndef HMAC_H_
  23 #define HMAC_H_
  24
  25 #include <transforms/hashers/hasher.h>
  26 #include <definitions.h>
  27
  28
  29 typedef struct hmac_t hmac_t;
  30
  31 /**
  32  * @brief Message authentication using hash functions.
  33  *
  34  * This class implements the message authenticaion algorithm
  35  * described in RFC2104. It uses a hash function, wich must
  36  * be implemented as a hasher_t class.
  37  *
  38  * @see http://www.faqs.org/rfcs/rfc2104.html
  39  * @see hasher_t, prf_hmac_t
  40  *
  41  * @ingroup transforms
  42  */
  43 struct hmac_t {
  44         /**
  45          * @brief Generate message authentication code.
  46          *
  47          * If buffer is NULL, no result is given back. A next call will
  48          * append the data to already supplied. If buffer is not NULL,
  49          * the mac of all apended data is calculated, returned and the
  50          * state of the hmac_t reset;
  51          *
  52          * @param this                  calling hmac
  53          * @param data                  chunk of data to authenticate
  54          * @param [out]buffer   pointer where the generated bytes will be written
  55          * @return
  56          *                                              - SUCCESS in any case
  57          */
  58         status_t (*get_mac) (hmac_t *this, chunk_t data, u_int8_t *buffer);
  59
  60         /**
  61          * @brief Generates message authentication code and
  62          * allocate space for them.
  63          *
  64          * If chunk is NULL, no result is given back. A next call will
  65          * append the data to already supplied. If chunk is not NULL,
  66          * the mac of all apended data is calculated, returned and the
  67          * state of the hmac_t reset;
  68          *
  69          * @param this                  calling hmac
  70          * @param data                  chunk of data to authenticate
  71          * @param [out]chunk    chunk which will hold generated bytes
  72          * @return
  73          *                                              - SUCCESS in any case
  74          *                                              - OUT_OF_RES if space could not be allocated
  75          */
  76         status_t (*allocate_mac) (hmac_t *this, chunk_t data, chunk_t *chunk);
  77
  78         /**
  79          * @brief Get the block size of this hmac.
  80          *
  81          * @param this                  calling hmac
  82          * @return                              block size in bytes
  83          */
  84         size_t (*get_block_size) (hmac_t *this);
  85
  86         /**
  87          * @brief Set the key for this hmac.
  88          *
  89          * Any key length is accepted.
  90          *
  91          * @param this                  calling hmac
  92          * @param key                   key to set
  93          * @return                              block size in bytes
  94          */
  95         size_t (*set_key) (hmac_t *this, chunk_t key);
  96
  97         /**
  98          * @brief Destroys a hmac object.
  99          *
 100          * @param this                  hmac_t object to destroy
 101          * @return
 102          *                                              - SUCCESS in any case
 103          */
 104         status_t (*destroy) (hmac_t *this);
 105 };
 106
 107 /**
 108  * @brief Creates a new hmac_t object.
 109  *
 110  * Creates a new hmac_t object using hash_algorithm to
 111  * create a hasher_t internally.
 112  *
 113  * @param hash_algorithm                hash algorithm to use
 114  * @return
 115  *                                                              - hmac_t if successfully
 116  *                                                              - NULL if out of ressources or hash not supported
 117  *
 118  * @ingroup transforms
 119  */
 120 hmac_t *hmac_create(hash_algorithm_t hash_algorithm);
 121
 122
 123 #endif /*HMAC_H_*/