xof: Defined Extended Output Functions
[strongswan.git] / src / libstrongswan / plugins / plugin_feature.h
1 /*
2 * Copyright (C) 2012-2015 Tobias Brunner
3 * Hochschule fuer Technik Rapperswil
4 *
5 * Copyright (C) 2011 Martin Willi
6 * Copyright (C) 2011 revosec AG
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 plugin_feature plugin_feature
21 * @{ @ingroup plugins
22 */
23
24 #ifndef PLUGIN_FEATURE_H_
25 #define PLUGIN_FEATURE_H_
26
27 typedef struct plugin_feature_t plugin_feature_t;
28
29 #include <library.h>
30 #include <eap/eap.h>
31 #include <plugins/plugin.h>
32 #include <credentials/containers/container.h>
33
34 /**
35 * Callback function of a plugin to (un-)register a specified feature.
36 *
37 * @param plugin plugin instance
38 * @param feature feature to register
39 * @param reg TRUE to register, FALSE to unregister
40 * @param cb_data user data passed with callback function
41 * @return TRUE if registered successfully
42 */
43 typedef bool (*plugin_feature_callback_t)(plugin_t *plugin,
44 plugin_feature_t *feature,
45 bool reg,void *cb_data);
46
47 /**
48 * Feature a plugin provides or depends on, including registration functions.
49 *
50 * Each plugin returns a list of plugin features, allowing the plugin loader
51 * to resolve dependencies and register the feature. FEATURE_PROVIDE defines
52 * features provided by the plugin, hard (DEPENDS) or soft (SDEPEND) dependency
53 * specified is related to the previously defined PROVIDE feature.
54 * If a plugin feature requires to hook in functionality into the library
55 * or a daemon, it can use REGISTER or CALLBACK entries. Each PROVIDE feature
56 * uses the REGISTER/CALLBACK entry defined previously. The REGISTER entry
57 * defines a common feature registration function directly passed to the
58 * associated manager or factory (crypto/credential factory etc.). A callback
59 * function is more generic allows the loader to invoke a callback to do
60 * the registration. PROVIDE features that do not use a registration or callback
61 * function must be listed before any REGISTER/CALLBACK entry, or use the NOOP
62 * helper macro.
63 *
64 * To conveniently create feature lists, use the macros PLUGIN_REGISTER,
65 * PLUGIN_CALLBACK, PLUGIN_NOOP, PLUGIN_PROVIDE, PLUGIN_DEPENDS and
66 * PLUGIN_SDEPEND. Use indentation to show how the registration functions
67 * and dependencies are related to a provided feature, such as:
68 *
69 * @verbatim
70 // two features, one with two dependencies, both use a callback to register
71 PLUGIN_CALLBACK(...),
72 PLUGIN_PROVIDE(...),
73 PLUGIN_DEPENDS(...),
74 PLUGIN_SDEPEND(...),
75 PLUGIN_PROVIDE(...),
76 // common constructor to register for a feature with one dependency
77 PLUGIN_REGISTER(...),
78 PLUGIN_PROVIDE(...),
79 PLUGIN_DEPENDS(...),
80 // feature that does not use a registration function
81 PLUGIN_NOOP,
82 PLUGIN_PROVIDE(...),
83 @endverbatim
84 */
85 struct plugin_feature_t {
86 /** kind of entry */
87 enum {
88 /* plugin provides this feature */
89 FEATURE_PROVIDE,
90 /* a feature depends on this feature, hard dependency */
91 FEATURE_DEPENDS,
92 /* a feature can optionally use this feature, soft dependency */
93 FEATURE_SDEPEND,
94 /* register the specified function for all following features */
95 FEATURE_REGISTER,
96 /* use a callback to register all following features */
97 FEATURE_CALLBACK,
98 } kind;
99 /* type of feature */
100 enum {
101 /** not a feature */
102 FEATURE_NONE,
103 /** crypter_t */
104 FEATURE_CRYPTER,
105 /** aead_t */
106 FEATURE_AEAD,
107 /** signer_t */
108 FEATURE_SIGNER,
109 /** hasher_t */
110 FEATURE_HASHER,
111 /** prf_t */
112 FEATURE_PRF,
113 /** xof_t */
114 FEATURE_XOF,
115 /** diffie_hellman_t */
116 FEATURE_DH,
117 /** rng_t */
118 FEATURE_RNG,
119 /** nonce_gen_t */
120 FEATURE_NONCE_GEN,
121 /** generic private key support */
122 FEATURE_PRIVKEY,
123 /** generating new private keys */
124 FEATURE_PRIVKEY_GEN,
125 /** private_key_t->sign() */
126 FEATURE_PRIVKEY_SIGN,
127 /** private_key_t->decrypt() */
128 FEATURE_PRIVKEY_DECRYPT,
129 /** generic public key support */
130 FEATURE_PUBKEY,
131 /** public_key_t->verify() */
132 FEATURE_PUBKEY_VERIFY,
133 /** public_key_t->encrypt() */
134 FEATURE_PUBKEY_ENCRYPT,
135 /** parsing certificates */
136 FEATURE_CERT_DECODE,
137 /** generating certificates */
138 FEATURE_CERT_ENCODE,
139 /** parsing containers */
140 FEATURE_CONTAINER_DECODE,
141 /** generating containers */
142 FEATURE_CONTAINER_ENCODE,
143 /** EAP server implementation */
144 FEATURE_EAP_SERVER,
145 /** EAP peer implementation */
146 FEATURE_EAP_PEER,
147 /** XAuth server implementation */
148 FEATURE_XAUTH_SERVER,
149 /** XAuth peer implementation */
150 FEATURE_XAUTH_PEER,
151 /** database_t */
152 FEATURE_DATABASE,
153 /** fetcher_t */
154 FEATURE_FETCHER,
155 /** resolver_t */
156 FEATURE_RESOLVER,
157 /** custom feature, described with a string */
158 FEATURE_CUSTOM,
159 } type;
160 /** More specific data for each type */
161 union {
162 /** FEATURE_CRYPTER */
163 struct {
164 encryption_algorithm_t alg;
165 size_t key_size;
166 } crypter;
167 /** FEATURE_AEAD */
168 struct {
169 encryption_algorithm_t alg;
170 size_t key_size;
171 } aead;
172 /** FEATURE_SIGNER */
173 integrity_algorithm_t signer;
174 /** FEATURE_PRF */
175 pseudo_random_function_t prf;
176 /** FEATURE_XOFF */
177 ext_out_function_t xof;
178 /** FEATURE_HASHER */
179 hash_algorithm_t hasher;
180 /** FEATURE_DH */
181 diffie_hellman_group_t dh_group;
182 /** FEATURE_RNG */
183 rng_quality_t rng_quality;
184 /** FEATURE_PRIVKEY */
185 key_type_t privkey;
186 /** FEATURE_PRIVKEY_GEN */
187 key_type_t privkey_gen;
188 /** FEATURE_PRIVKEY_SIGN */
189 signature_scheme_t privkey_sign;
190 /** FEATURE_PRIVKEY_DECRYPT */
191 encryption_scheme_t privkey_decrypt;
192 /** FEATURE_PUBKEY */
193 key_type_t pubkey;
194 /** FEATURE_PUBKEY_VERIFY */
195 signature_scheme_t pubkey_verify;
196 /** FEATURE_PUBKEY_ENCRYPT */
197 encryption_scheme_t pubkey_encrypt;
198 /** FEATURE_CERT_DECODE/ENCODE */
199 certificate_type_t cert;
200 /** FEATURE_CONTAINER_DECODE/ENCODE */
201 container_type_t container;
202 /** FEATURE_EAP_SERVER/CLIENT */
203 eap_vendor_type_t eap;
204 /** FEATURE_DATABASE */
205 db_driver_t database;
206 /** FEATURE_FETCHER */
207 char *fetcher;
208 /** FEATURE_CUSTOM */
209 char *custom;
210 /** FEATURE_XAUTH_SERVER/CLIENT */
211 char *xauth;
212
213 /** FEATURE_REGISTER */
214 struct {
215 /** final flag to pass for builder_function_t */
216 bool final;
217 /** feature specific function to register for this type */
218 void *f;
219 } reg;
220
221 /** FEATURE_CALLBACK */
222 struct {
223 /** callback function to invoke for registration */
224 plugin_feature_callback_t f;
225 /** data to pass to callback */
226 void *data;
227 } cb;
228 } arg;
229 };
230
231 #define FEATURE(kind, type, ...) _PLUGIN_FEATURE_##type(kind, __VA_ARGS__)
232
233 /**
234 * Define function to register directly for all upcoming features.
235 *
236 * @param type feature type to register
237 * @param f type specific function to register
238 * @param ... type specific additional arguments
239 */
240 #define PLUGIN_REGISTER(type, f, ...) _PLUGIN_FEATURE_REGISTER_##type(type, f, ##__VA_ARGS__)
241
242 /**
243 * Define a callback to invoke for registering all upcoming features.
244 *
245 * @param cb type specific callback function to register
246 * @param data data pointer to pass to callback
247 */
248 #define PLUGIN_CALLBACK(cb, data) _PLUGIN_FEATURE_CALLBACK(cb, data)
249
250 /**
251 * The upcoming features use neither a callback nor a register function.
252 */
253 #define PLUGIN_NOOP _PLUGIN_FEATURE_CALLBACK(NULL, NULL)
254
255 /**
256 * Define a feature the plugin provides.
257 *
258 * @param type feature type to provide
259 * @param ... type specific arguments
260 */
261 #define PLUGIN_PROVIDE(type, ...) _PLUGIN_FEATURE_##type(PROVIDE, __VA_ARGS__)
262
263 /**
264 * Define a hard dependency for the previously defined feature.
265 *
266 * @param type feature type to provide
267 * @param ... type specific arguments
268 */
269 #define PLUGIN_DEPENDS(type, ...) _PLUGIN_FEATURE_##type(DEPENDS, __VA_ARGS__)
270
271 /**
272 * Define a soft dependency for the previously defined feature.
273 *
274 * @param type feature type to provide
275 * @param ... type specific arguments
276 */
277 #define PLUGIN_SDEPEND(type, ...) _PLUGIN_FEATURE_##type(SDEPEND, __VA_ARGS__)
278
279 #define __PLUGIN_FEATURE(kind, type, ...) (plugin_feature_t){ FEATURE_##kind, FEATURE_##type, { __VA_ARGS__ }}
280 #define _PLUGIN_FEATURE_CRYPTER(kind, alg, size) __PLUGIN_FEATURE(kind, CRYPTER, .crypter = { alg, size })
281 #define _PLUGIN_FEATURE_AEAD(kind, alg, size) __PLUGIN_FEATURE(kind, AEAD, .aead = { alg, size })
282 #define _PLUGIN_FEATURE_SIGNER(kind, alg) __PLUGIN_FEATURE(kind, SIGNER, .signer = alg)
283 #define _PLUGIN_FEATURE_HASHER(kind, alg) __PLUGIN_FEATURE(kind, HASHER, .hasher = alg)
284 #define _PLUGIN_FEATURE_PRF(kind, alg) __PLUGIN_FEATURE(kind, PRF, .prf = alg)
285 #define _PLUGIN_FEATURE_XOF(kind, alg) __PLUGIN_FEATURE(kind, XOF, .xof = alg)
286 #define _PLUGIN_FEATURE_DH(kind, group) __PLUGIN_FEATURE(kind, DH, .dh_group = group)
287 #define _PLUGIN_FEATURE_RNG(kind, quality) __PLUGIN_FEATURE(kind, RNG, .rng_quality = quality)
288 #define _PLUGIN_FEATURE_NONCE_GEN(kind, ...) __PLUGIN_FEATURE(kind, NONCE_GEN, .custom = NULL)
289 #define _PLUGIN_FEATURE_PRIVKEY(kind, type) __PLUGIN_FEATURE(kind, PRIVKEY, .privkey = type)
290 #define _PLUGIN_FEATURE_PRIVKEY_GEN(kind, type) __PLUGIN_FEATURE(kind, PRIVKEY_GEN, .privkey_gen = type)
291 #define _PLUGIN_FEATURE_PRIVKEY_SIGN(kind, scheme) __PLUGIN_FEATURE(kind, PRIVKEY_SIGN, .privkey_sign = scheme)
292 #define _PLUGIN_FEATURE_PRIVKEY_DECRYPT(kind, scheme) __PLUGIN_FEATURE(kind, PRIVKEY_DECRYPT, .privkey_decrypt = scheme)
293 #define _PLUGIN_FEATURE_PUBKEY(kind, type) __PLUGIN_FEATURE(kind, PUBKEY, .pubkey = type)
294 #define _PLUGIN_FEATURE_PUBKEY_VERIFY(kind, scheme) __PLUGIN_FEATURE(kind, PUBKEY_VERIFY, .pubkey_verify = scheme)
295 #define _PLUGIN_FEATURE_PUBKEY_ENCRYPT(kind, scheme) __PLUGIN_FEATURE(kind, PUBKEY_ENCRYPT, .pubkey_encrypt = scheme)
296 #define _PLUGIN_FEATURE_CERT_DECODE(kind, type) __PLUGIN_FEATURE(kind, CERT_DECODE, .cert = type)
297 #define _PLUGIN_FEATURE_CERT_ENCODE(kind, type) __PLUGIN_FEATURE(kind, CERT_ENCODE, .cert = type)
298 #define _PLUGIN_FEATURE_CONTAINER_DECODE(kind, type) __PLUGIN_FEATURE(kind, CONTAINER_DECODE, .container = type)
299 #define _PLUGIN_FEATURE_CONTAINER_ENCODE(kind, type) __PLUGIN_FEATURE(kind, CONTAINER_ENCODE, .container = type)
300 #define _PLUGIN_FEATURE_EAP_SERVER(kind, type) _PLUGIN_FEATURE_EAP_SERVER_VENDOR(kind, type, 0)
301 #define _PLUGIN_FEATURE_EAP_PEER(kind, type) _PLUGIN_FEATURE_EAP_PEER_VENDOR(kind, type, 0)
302 #define _PLUGIN_FEATURE_EAP_SERVER_VENDOR(kind, type, vendor)__PLUGIN_FEATURE(kind, EAP_SERVER, .eap = { type, vendor })
303 #define _PLUGIN_FEATURE_EAP_PEER_VENDOR(kind, type, vendor) __PLUGIN_FEATURE(kind, EAP_PEER, .eap = { type, vendor })
304 #define _PLUGIN_FEATURE_DATABASE(kind, type) __PLUGIN_FEATURE(kind, DATABASE, .database = type)
305 #define _PLUGIN_FEATURE_FETCHER(kind, type) __PLUGIN_FEATURE(kind, FETCHER, .fetcher = type)
306 #define _PLUGIN_FEATURE_RESOLVER(kind, ...) __PLUGIN_FEATURE(kind, RESOLVER, .custom = NULL)
307 #define _PLUGIN_FEATURE_CUSTOM(kind, name) __PLUGIN_FEATURE(kind, CUSTOM, .custom = name)
308 #define _PLUGIN_FEATURE_XAUTH_SERVER(kind, name) __PLUGIN_FEATURE(kind, XAUTH_SERVER, .xauth = name)
309 #define _PLUGIN_FEATURE_XAUTH_PEER(kind, name) __PLUGIN_FEATURE(kind, XAUTH_PEER, .xauth = name)
310
311 #define __PLUGIN_FEATURE_REGISTER(type, _f) (plugin_feature_t){ FEATURE_REGISTER, FEATURE_##type, .arg.reg.f = _f }
312 #define __PLUGIN_FEATURE_REGISTER_BUILDER(type, _f, _final) (plugin_feature_t){ FEATURE_REGISTER, FEATURE_##type, .arg.reg = {.f = _f, .final = _final, }}
313 #define _PLUGIN_FEATURE_REGISTER_CRYPTER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
314 #define _PLUGIN_FEATURE_REGISTER_AEAD(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
315 #define _PLUGIN_FEATURE_REGISTER_SIGNER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
316 #define _PLUGIN_FEATURE_REGISTER_HASHER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
317 #define _PLUGIN_FEATURE_REGISTER_PRF(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
318 #define _PLUGIN_FEATURE_REGISTER_XOF(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
319 #define _PLUGIN_FEATURE_REGISTER_DH(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
320 #define _PLUGIN_FEATURE_REGISTER_RNG(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
321 #define _PLUGIN_FEATURE_REGISTER_NONCE_GEN(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
322 #define _PLUGIN_FEATURE_REGISTER_PRIVKEY(type, f, final) __PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
323 #define _PLUGIN_FEATURE_REGISTER_PRIVKEY_GEN(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
324 #define _PLUGIN_FEATURE_REGISTER_PUBKEY(type, f, final) __PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
325 #define _PLUGIN_FEATURE_REGISTER_CERT_DECODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
326 #define _PLUGIN_FEATURE_REGISTER_CERT_ENCODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
327 #define _PLUGIN_FEATURE_REGISTER_CONTAINER_DECODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
328 #define _PLUGIN_FEATURE_REGISTER_CONTAINER_ENCODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
329 #define _PLUGIN_FEATURE_REGISTER_DATABASE(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
330 #define _PLUGIN_FEATURE_REGISTER_FETCHER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
331 #define _PLUGIN_FEATURE_REGISTER_RESOLVER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
332
333 #define _PLUGIN_FEATURE_CALLBACK(_cb, _data) (plugin_feature_t){ FEATURE_CALLBACK, FEATURE_NONE, .arg.cb = { .f = _cb, .data = _data } }
334
335 /**
336 * Names for plugin_feature_t types.
337 */
338 extern enum_name_t *plugin_feature_names;
339
340 /**
341 * Add a set of plugin features to the given array, which must have enough space
342 * to store the added features.
343 *
344 * @param features the array of plugin features to extend
345 * @param to_add the features to add
346 * @param count number of features to add
347 * @param pos current position in the features array, gets advanced
348 */
349 static inline void plugin_features_add(plugin_feature_t *features,
350 plugin_feature_t *to_add,
351 int count, int *pos)
352 {
353 int i;
354
355 for (i = 0; i < count; i++)
356 {
357 features[(*pos)++] = to_add[i];
358 }
359 }
360
361 /**
362 * Calculates a hash value for the given feature.
363 *
364 * Since this is intended to be used with the plugin_features_matches function
365 * the hash is not really unique for all types of features (e.g. RNGs are all
366 * mapped to the same value because they are loosely matched by said function).
367 *
368 * @param feature feature to hash
369 * @return hash value of the feature
370 */
371 uint32_t plugin_feature_hash(plugin_feature_t *feature);
372
373 /**
374 * Check if feature a matches to feature b.
375 *
376 * This is no check for equality. For instance, for FEATURE_RNG a matches b if
377 * a's strength is at least the strength of b. Or for FEATURE_SQL if a is
378 * DB_ANY it will match b if it is of the same type.
379 *
380 * @param a feature to check
381 * @param b feature to match against
382 * @return TRUE if a matches b
383 */
384 bool plugin_feature_matches(plugin_feature_t *a, plugin_feature_t *b);
385
386 /**
387 * Check if feature a equals feature b.
388 *
389 * @param a feature
390 * @param b feature to compare
391 * @return TRUE if a equals b
392 */
393 bool plugin_feature_equals(plugin_feature_t *a, plugin_feature_t *b);
394
395 /**
396 * Get a string describing feature.
397 *
398 * @param feature feature to describe
399 * @return allocated string describing feature
400 */
401 char* plugin_feature_get_string(plugin_feature_t *feature);
402
403 /**
404 * Load a plugin feature using a REGISTER/CALLBACK feature entry.
405 *
406 * @param plugin plugin providing feature
407 * @param feature feature to load
408 * @param reg REGISTER/CALLBACK feature entry to use for registration
409 */
410 bool plugin_feature_load(plugin_t *plugin, plugin_feature_t *feature,
411 plugin_feature_t *reg);
412
413 /**
414 * Unload a plugin feature using a REGISTER/CALLBACK feature entry.
415 *
416 * @param plugin plugin providing feature
417 * @param feature feature to unload
418 * @param reg REGISTER/CALLBACK feature entry to use for deregistration
419 */
420 bool plugin_feature_unload(plugin_t *plugin, plugin_feature_t *feature,
421 plugin_feature_t *reg);
422
423 #endif /** PLUGIN_FEATURE_H_ @}*/