Defined SHA-3 hashers
[strongswan.git] / src / libstrongswan / crypto / hashers / hasher.h
1 /*
2 * Copyright (C) 2012-2015 Tobias Brunner
3 * Copyright (C) 2005-2006 Martin Willi
4 * Copyright (C) 2005 Jan Hutter
5 * Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 */
17
18 /**
19 * @defgroup hasher hasher
20 * @{ @ingroup crypto
21 */
22
23 #ifndef HASHER_H_
24 #define HASHER_H_
25
26 typedef enum hash_algorithm_t hash_algorithm_t;
27 typedef struct hasher_t hasher_t;
28
29 #include <library.h>
30 #include <crypto/prfs/prf.h>
31 #include <crypto/signers/signer.h>
32 #include <credentials/keys/public_key.h>
33
34 /**
35 * Hash algorithms as defined for IKEv2 by RFC 7427
36 */
37 enum hash_algorithm_t {
38 HASH_SHA1 = 1,
39 HASH_SHA256 = 2,
40 HASH_SHA384 = 3,
41 HASH_SHA512 = 4,
42 /* use private use range for algorithms not defined/permitted by RFC 7427 */
43 HASH_UNKNOWN = 1024,
44 HASH_MD2 = 1025,
45 HASH_MD4 = 1026,
46 HASH_MD5 = 1027,
47 HASH_SHA224 = 1028,
48 HASH_SHA3_224 = 1029,
49 HASH_SHA3_256 = 1030,
50 HASH_SHA3_384 = 1031,
51 HASH_SHA3_512 = 1032
52 };
53
54 #define HASH_SIZE_MD2 16
55 #define HASH_SIZE_MD4 16
56 #define HASH_SIZE_MD5 16
57 #define HASH_SIZE_SHA1 20
58 #define HASH_SIZE_SHA224 28
59 #define HASH_SIZE_SHA256 32
60 #define HASH_SIZE_SHA384 48
61 #define HASH_SIZE_SHA512 64
62
63 /**
64 * enum names for hash_algorithm_t.
65 */
66 extern enum_name_t *hash_algorithm_names;
67
68 /**
69 * Short names for hash_algorithm_names
70 */
71 extern enum_name_t *hash_algorithm_short_names;
72
73 /**
74 * Generic interface for all hash functions.
75 */
76 struct hasher_t {
77
78 /**
79 * Hash data and write it in the buffer.
80 *
81 * If the parameter hash is NULL, no result is written back
82 * and more data can be appended to already hashed data.
83 * If not, the result is written back and the hasher is reset.
84 *
85 * The hash output parameter must hold at least
86 * hash_t.get_block_size() bytes.
87 *
88 * @param data data to hash
89 * @param hash pointer where the hash will be written
90 * @return TRUE if hash created successfully
91 */
92 bool (*get_hash)(hasher_t *this, chunk_t data,
93 u_int8_t *hash) __attribute__((warn_unused_result));
94
95 /**
96 * Hash data and allocate space for the hash.
97 *
98 * If the parameter hash is NULL, no result is written back
99 * and more data can be appended to already hashed data.
100 * If not, the result is written back and the hasher is reset.
101 *
102 * @param data chunk with data to hash
103 * @param hash chunk which will hold allocated hash
104 * @return TRUE if hash allocated successfully
105 */
106 bool (*allocate_hash)(hasher_t *this, chunk_t data,
107 chunk_t *hash) __attribute__((warn_unused_result));
108
109 /**
110 * Get the size of the resulting hash.
111 *
112 * @return hash size in bytes
113 */
114 size_t (*get_hash_size)(hasher_t *this);
115
116 /**
117 * Resets the hasher's state.
118 *
119 * @return TRUE if hasher reset successfully
120 */
121 bool (*reset)(hasher_t *this) __attribute__((warn_unused_result));
122
123 /**
124 * Destroys a hasher object.
125 */
126 void (*destroy)(hasher_t *this);
127 };
128
129 /**
130 * Conversion of ASN.1 OID to hash algorithm.
131 *
132 * @param oid ASN.1 OID
133 * @return hash algorithm, HASH_UNKNOWN if OID unsupported
134 */
135 hash_algorithm_t hasher_algorithm_from_oid(int oid);
136
137 /**
138 * Conversion of PRF algorithm to hash algorithm (if based on one).
139 *
140 * @param alg prf algorithm
141 * @return hash algorithm, HASH_UNKNOWN if not based on a hash
142 */
143 hash_algorithm_t hasher_algorithm_from_prf(pseudo_random_function_t alg);
144
145 /**
146 * Conversion of integrity algorithm to hash algorithm (if based on one).
147 *
148 * If length is not NULL the length of the resulting signature is returned,
149 * which might be smaller than the output size of the underlying hash.
150 *
151 * @param alg integrity algorithm
152 * @param length returns signature length, if not NULL
153 * @return hash algorithm, HASH_UNKNOWN if not based on a hash
154 */
155 hash_algorithm_t hasher_algorithm_from_integrity(integrity_algorithm_t alg,
156 size_t *length);
157
158 /**
159 * Conversion of hash algorithm to integrity algorithm (if based on a hash).
160 *
161 * @param alg hash algorithm
162 * @param length length of the signature
163 * @return integrity algorithm, AUTH_UNDEFINED if none is known
164 * based on the given hash function
165 */
166 integrity_algorithm_t hasher_algorithm_to_integrity(hash_algorithm_t alg,
167 size_t length);
168
169 /**
170 * Check if the given algorithm may be used for IKEv2 signature authentication.
171 *
172 * @param alg hash algorithm
173 * @return TRUE if algorithm may be used, FALSE otherwise
174 */
175 bool hasher_algorithm_for_ikev2(hash_algorithm_t alg);
176
177 /**
178 * Conversion of hash algorithm into ASN.1 OID.
179 *
180 * @param alg hash algorithm
181 * @return ASN.1 OID, or OID_UNKNOW
182 */
183 int hasher_algorithm_to_oid(hash_algorithm_t alg);
184
185 /**
186 * Conversion of hash signature algorithm into ASN.1 OID.
187 *
188 * @param alg hash algorithm
189 * @param key public key type
190 * @return ASN.1 OID if, or OID_UNKNOW
191 */
192 int hasher_signature_algorithm_to_oid(hash_algorithm_t alg, key_type_t key);
193
194 /**
195 * Determine the hash algorithm associated with a given signature scheme.
196 *
197 * @param scheme signature scheme
198 * @return hash algorithm (could be HASH_UNKNOWN)
199 */
200 hash_algorithm_t hasher_from_signature_scheme(signature_scheme_t scheme);
201
202 #endif /** HASHER_H_ @}*/