xof: Defined Extended Output Functions
[strongswan.git] / src / libstrongswan / crypto / crypto_factory.h
1 /*
2 * Copyright (C) 2008 Martin Willi
3 * Copyright (C) 2016 Andreas Steffen
4 * HSR Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup crypto_factory crypto_factory
19 * @{ @ingroup crypto
20 */
21
22 #ifndef CRYPTO_FACTORY_H_
23 #define CRYPTO_FACTORY_H_
24
25 typedef struct crypto_factory_t crypto_factory_t;
26
27 #include <library.h>
28 #include <collections/enumerator.h>
29 #include <crypto/crypters/crypter.h>
30 #include <crypto/aead.h>
31 #include <crypto/signers/signer.h>
32 #include <crypto/hashers/hasher.h>
33 #include <crypto/prfs/prf.h>
34 #include <crypto/rngs/rng.h>
35 #include <crypto/xofs/xof.h>
36 #include <crypto/nonce_gen.h>
37 #include <crypto/diffie_hellman.h>
38 #include <crypto/transform.h>
39
40 #define CRYPTO_MAX_ALG_LINE 120 /* characters */
41
42 /**
43 * Constructor function for crypters
44 */
45 typedef crypter_t* (*crypter_constructor_t)(encryption_algorithm_t algo,
46 size_t key_size);
47 /**
48 * Constructor function for aead transforms
49 */
50 typedef aead_t* (*aead_constructor_t)(encryption_algorithm_t algo,
51 size_t key_size, size_t salt_size);
52 /**
53 * Constructor function for signers
54 */
55 typedef signer_t* (*signer_constructor_t)(integrity_algorithm_t algo);
56
57 /**
58 * Constructor function for hashers
59 */
60 typedef hasher_t* (*hasher_constructor_t)(hash_algorithm_t algo);
61
62 /**
63 * Constructor function for pseudo random functions
64 */
65 typedef prf_t* (*prf_constructor_t)(pseudo_random_function_t algo);
66
67 /**
68 * Constructor function for pseudo random functions
69 */
70 typedef xof_t* (*xof_constructor_t)(ext_out_function_t algo);
71
72 /**
73 * Constructor function for source of randomness
74 */
75 typedef rng_t* (*rng_constructor_t)(rng_quality_t quality);
76
77 /**
78 * Constructor function for nonce generators
79 */
80 typedef nonce_gen_t* (*nonce_gen_constructor_t)();
81
82 /**
83 * Constructor function for diffie hellman
84 *
85 * The DH constructor accepts additional arguments for:
86 * - MODP_CUSTOM: chunk_t generator, chunk_t prime
87 */
88 typedef diffie_hellman_t* (*dh_constructor_t)(diffie_hellman_group_t group, ...);
89
90 /**
91 * Handles crypto modules and creates instances.
92 */
93 struct crypto_factory_t {
94
95 /**
96 * Create a crypter instance.
97 *
98 * @param algo encryption algorithm
99 * @param key_size length of the key in bytes
100 * @return crypter_t instance, NULL if not supported
101 */
102 crypter_t* (*create_crypter)(crypto_factory_t *this,
103 encryption_algorithm_t algo, size_t key_size);
104
105 /**
106 * Create a aead instance.
107 *
108 * @param algo encryption algorithm
109 * @param key_size length of the key in bytes
110 * @param salt_size size of salt, implicit part of the nonce
111 * @return aead_t instance, NULL if not supported
112 */
113 aead_t* (*create_aead)(crypto_factory_t *this,
114 encryption_algorithm_t algo,
115 size_t key_size, size_t salt_size);
116
117 /**
118 * Create a symmetric signer instance.
119 *
120 * @param algo MAC algorithm to use
121 * @return signer_t instance, NULL if not supported
122 */
123 signer_t* (*create_signer)(crypto_factory_t *this,
124 integrity_algorithm_t algo);
125
126 /**
127 * Create a hasher instance.
128 *
129 * @param algo hash algorithm
130 * @return hasher_t instance, NULL if not supported
131 */
132 hasher_t* (*create_hasher)(crypto_factory_t *this, hash_algorithm_t algo);
133
134 /**
135 * Create a pseudo random function instance.
136 *
137 * @param algo PRF algorithm to use
138 * @return prf_t instance, NULL if not supported
139 */
140 prf_t* (*create_prf)(crypto_factory_t *this, pseudo_random_function_t algo);
141
142 /**
143 * Create an extended output function instance.
144 *
145 * @param algo XOF algorithm to use
146 * @return xof_t instance, NULL if not supported
147 */
148 xof_t* (*create_xof)(crypto_factory_t *this, ext_out_function_t algo);
149
150 /**
151 * Create a source of randomness.
152 *
153 * @param quality required randomness quality
154 * @return rng_t instance, NULL if no RNG with such a quality
155 */
156 rng_t* (*create_rng)(crypto_factory_t *this, rng_quality_t quality);
157
158 /**
159 * Create a nonce generator instance.
160 *
161 * @return nonce_gen_t instance, NULL if not supported
162 */
163 nonce_gen_t* (*create_nonce_gen)(crypto_factory_t *this);
164
165 /**
166 * Create a diffie hellman instance.
167 *
168 * Additional arguments are passed to the DH constructor.
169 *
170 * @param group diffie hellman group
171 * @return diffie_hellman_t instance, NULL if not supported
172 */
173 diffie_hellman_t* (*create_dh)(crypto_factory_t *this,
174 diffie_hellman_group_t group, ...);
175
176 /**
177 * Register a crypter constructor.
178 *
179 * @param algo algorithm to constructor
180 * @param key size key size to peform benchmarking for
181 * @param plugin_name plugin that registered this algorithm
182 * @param create constructor function for that algorithm
183 * @return TRUE if registered, FALSE if test vector failed
184 */
185 bool (*add_crypter)(crypto_factory_t *this, encryption_algorithm_t algo,
186 size_t key_size, const char *plugin_name,
187 crypter_constructor_t create);
188
189 /**
190 * Unregister a crypter constructor.
191 *
192 * @param create constructor function to unregister
193 */
194 void (*remove_crypter)(crypto_factory_t *this, crypter_constructor_t create);
195
196 /**
197 * Unregister a aead constructor.
198 *
199 * @param create constructor function to unregister
200 */
201 void (*remove_aead)(crypto_factory_t *this, aead_constructor_t create);
202
203 /**
204 * Register a aead constructor.
205 *
206 * @param algo algorithm to constructor
207 * @param key size key size to peform benchmarking for
208 * @param plugin_name plugin that registered this algorithm
209 * @param create constructor function for that algorithm
210 * @return TRUE if registered, FALSE if test vector failed
211 */
212 bool (*add_aead)(crypto_factory_t *this, encryption_algorithm_t algo,
213 size_t key_size, const char *plugin_name,
214 aead_constructor_t create);
215
216 /**
217 * Register a signer constructor.
218 *
219 * @param algo algorithm to constructor
220 * @param plugin_name plugin that registered this algorithm
221 * @param create constructor function for that algorithm
222 * @return TRUE if registered, FALSE if test vector failed
223 */
224 bool (*add_signer)(crypto_factory_t *this, integrity_algorithm_t algo,
225 const char *plugin_name, signer_constructor_t create);
226
227 /**
228 * Unregister a signer constructor.
229 *
230 * @param create constructor function to unregister
231 */
232 void (*remove_signer)(crypto_factory_t *this, signer_constructor_t create);
233
234 /**
235 * Register a hasher constructor.
236 *
237 * @param algo algorithm to constructor
238 * @param plugin_name plugin that registered this algorithm
239 * @param create constructor function for that algorithm
240 * @return TRUE if registered, FALSE if test vector failed
241 */
242 bool (*add_hasher)(crypto_factory_t *this, hash_algorithm_t algo,
243 const char *plugin_name, hasher_constructor_t create);
244
245 /**
246 * Unregister a hasher constructor.
247 *
248 * @param create constructor function to unregister
249 */
250 void (*remove_hasher)(crypto_factory_t *this, hasher_constructor_t create);
251
252 /**
253 * Register a prf constructor.
254 *
255 * @param algo algorithm to constructor
256 * @param plugin_name plugin that registered this algorithm
257 * @param create constructor function for that algorithm
258 * @return TRUE if registered, FALSE if test vector failed
259 */
260 bool (*add_prf)(crypto_factory_t *this, pseudo_random_function_t algo,
261 const char *plugin_name, prf_constructor_t create);
262
263 /**
264 * Unregister a prf constructor.
265 *
266 * @param create constructor function to unregister
267 */
268 void (*remove_prf)(crypto_factory_t *this, prf_constructor_t create);
269
270 /**
271 * Register an xof constructor.
272 *
273 * @param algo algorithm to constructor
274 * @param plugin_name plugin that registered this algorithm
275 * @param create constructor function for that algorithm
276 * @return TRUE if registered, FALSE if test vector failed
277 */
278 bool (*add_xof)(crypto_factory_t *this, ext_out_function_t algo,
279 const char *plugin_name, xof_constructor_t create);
280
281 /**
282 * Unregister an xof constructor.
283 *
284 * @param create constructor function to unregister
285 */
286 void (*remove_xof)(crypto_factory_t *this, xof_constructor_t create);
287
288 /**
289 * Register a source of randomness.
290 *
291 * @param quality quality of randomness this RNG serves
292 * @param plugin_name plugin that registered this algorithm
293 * @param create constructor function for such a quality
294 * @return TRUE if registered, FALSE if test vector failed
295 */
296 bool (*add_rng)(crypto_factory_t *this, rng_quality_t quality,
297 const char *plugin_name, rng_constructor_t create);
298
299 /**
300 * Unregister a source of randomness.
301 *
302 * @param create constructor function to unregister
303 */
304 void (*remove_rng)(crypto_factory_t *this, rng_constructor_t create);
305
306 /**
307 * Register a nonce generator.
308 *
309 * @param plugin_name plugin that registered this algorithm
310 * @param create constructor function for that nonce generator
311 * @return TRUE if registered, FALSE if test vector failed
312 */
313 bool (*add_nonce_gen)(crypto_factory_t *this, const char *plugin_name,
314 nonce_gen_constructor_t create);
315
316 /**
317 * Unregister a nonce generator.
318 *
319 * @param create constructor function to unregister
320 */
321 void (*remove_nonce_gen)(crypto_factory_t *this,
322 nonce_gen_constructor_t create);
323
324 /**
325 * Register a diffie hellman constructor.
326 *
327 * @param group dh group to constructor
328 * @param plugin_name plugin that registered this algorithm
329 * @param create constructor function for that algorithm
330 * @return TRUE if registered, FALSE if test vector failed
331 */
332 bool (*add_dh)(crypto_factory_t *this, diffie_hellman_group_t group,
333 const char *plugin_name, dh_constructor_t create);
334
335 /**
336 * Unregister a diffie hellman constructor.
337 *
338 * @param create constructor function to unregister
339 */
340 void (*remove_dh)(crypto_factory_t *this, dh_constructor_t create);
341
342 /**
343 * Create an enumerator over all registered crypter algorithms.
344 *
345 * @return enumerator over encryption_algorithm_t, plugin
346 */
347 enumerator_t* (*create_crypter_enumerator)(crypto_factory_t *this);
348
349 /**
350 * Create an enumerator over all registered aead algorithms.
351 *
352 * @return enumerator over encryption_algorithm_t, plugin
353 */
354 enumerator_t* (*create_aead_enumerator)(crypto_factory_t *this);
355
356 /**
357 * Create an enumerator over all registered signer algorithms.
358 *
359 * @return enumerator over integrity_algorithm_t, plugin
360 */
361 enumerator_t* (*create_signer_enumerator)(crypto_factory_t *this);
362
363 /**
364 * Create an enumerator over all registered hasher algorithms.
365 *
366 * @return enumerator over hash_algorithm_t, plugin
367 */
368 enumerator_t* (*create_hasher_enumerator)(crypto_factory_t *this);
369
370 /**
371 * Create an enumerator over all registered PRFs.
372 *
373 * @return enumerator over pseudo_random_function_t, plugin
374 */
375 enumerator_t* (*create_prf_enumerator)(crypto_factory_t *this);
376
377 /**
378 * Create an enumerator over all registered XOFs.
379 *
380 * @return enumerator over ext_out_function_t, plugin
381 */
382 enumerator_t* (*create_xof_enumerator)(crypto_factory_t *this);
383
384 /**
385 * Create an enumerator over all registered diffie hellman groups.
386 *
387 * @return enumerator over diffie_hellman_group_t, plugin
388 */
389 enumerator_t* (*create_dh_enumerator)(crypto_factory_t *this);
390
391 /**
392 * Create an enumerator over all registered random generators.
393 *
394 * @return enumerator over rng_quality_t, plugin
395 */
396 enumerator_t* (*create_rng_enumerator)(crypto_factory_t *this);
397
398 /**
399 * Create an enumerator over all registered nonce generators.
400 *
401 * @return enumerator over plugin
402 */
403 enumerator_t* (*create_nonce_gen_enumerator)(crypto_factory_t *this);
404
405 /**
406 * Add a test vector to the crypto factory.
407 *
408 * @param type type of the test vector
409 * @param vector pointer to a test vector, defined in crypto_tester.h
410 */
411 void (*add_test_vector)(crypto_factory_t *this, transform_type_t type,
412 void *vector);
413
414 /**
415 * Create an enumerator verifying transforms using known test vectors.
416 *
417 * The resulting enumerator enumerates over an u_int with the type
418 * specific transform identifier, the plugin name providing the transform,
419 * and a boolean value indicating success/failure for the given transform.
420 *
421 * @param type transform type to test
422 * @return enumerator over (u_int, char*, bool)
423 */
424 enumerator_t* (*create_verify_enumerator)(crypto_factory_t *this,
425 transform_type_t type);
426
427 /**
428 * Destroy a crypto_factory instance.
429 */
430 void (*destroy)(crypto_factory_t *this);
431 };
432
433 /**
434 * Create a crypto_factory instance.
435 */
436 crypto_factory_t *crypto_factory_create();
437
438 #endif /** CRYPTO_FACTORY_H_ @}*/