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