- updated documentation, should be the reference
[strongswan.git] / 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_*/