243c79d65945cb649f8eaa09e239c5cb75195371
[strongswan.git] / src / libstrongswan / plugins / plugin_feature.h
1 /*
2 * Copyright (C) 2011 Martin Willi
3 * Copyright (C) 2011 revosec AG
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup plugin_feature plugin_feature
18 * @{ @ingroup plugins
19 */
20
21 #ifndef PLUGIN_FEATURE_H_
22 #define PLUGIN_FEATURE_H_
23
24 typedef struct plugin_feature_t plugin_feature_t;
25
26 #include <library.h>
27 #include <eap/eap.h>
28 #include <plugins/plugin.h>
29
30 /**
31 * Callback function of a plugin to (un-)register a specified feature.
32 *
33 * @param plugin plugin instance
34 * @param feature feature to register
35 * @param reg TRUE to register, FALSE to unregister
36 * @param cb_data user data passed with callback function
37 * @return TRUE if registered successfully
38 */
39 typedef bool (*plugin_feature_callback_t)(plugin_t *plugin,
40 plugin_feature_t *feature,
41 bool reg,void *cb_data);
42
43 /**
44 * Feature a plugin provides or depends on, including registration functions.
45 *
46 * Each plugin returns a list of plugin features, allowing the plugin loader
47 * to resolve dependencies and register the feature. FEATURE_PROVIDE defines
48 * features provided by the plugin, hard (DEPENDS) or soft (SDEPEND) dependency
49 * specified is related to the previously defined PROVIDE feature.
50 * If a plugin feature requires to hook in functionality into the library
51 * or a daemon, it can use REGISTER or CALLBACK entries. Each PROVIDED feature
52 * uses the REGISTER/CALLBACK entry defined previously. The REGISTER entry
53 * defines a common feature registration function directly passed to the
54 * associated manager or factory (crypto/credential factory etc.). A callback
55 * function is more generic allows the loader to invoke a callback to do
56 * the registration.
57 *
58 * To conviently create feature lists, use the four macros PLUGIN_REGISTER,
59 * PLUGIN_CALLBACK, PLUGIN_PROVIDE, PLUGIN_DEPENDS and PLUGIN_SDEPEND. Use
60 * identation to show how the registration functions and dependencies are
61 * related to a provided feature, such as:
62 *
63 * @verbatim
64 // two features, one with two dependencies, both use a callback to register
65 PLUGIN_CALLBACK(...),
66 PLUGIN_PROVIDE(...),
67 PLUGIN_DEPENDS(...),
68 PLUGIN_SDEPEND(...),
69 PLUGIN_PROVIDE(...),
70 // common constructor to register for a feature with one dependency
71 PLUGIN_REGISTER(...),
72 PLUGIN_PROVIDE(...),
73 PLUGIN_DEPENDS(...),
74 // feature that does not use a registration function
75 PLUGIN_PROVIDE(...),
76 @endverbatim
77 */
78 struct plugin_feature_t {
79 /** kind of entry */
80 enum {
81 /* plugin provides this feature */
82 FEATURE_PROVIDE,
83 /* a feature depends on this feature, hard dependency */
84 FEATURE_DEPENDS,
85 /* a feature can optionally use this feature, soft dependency */
86 FEATURE_SDEPEND,
87 /* register the specified function for all following features */
88 FEATURE_REGISTER,
89 /* use a callback to register all following features */
90 FEATURE_CALLBACK,
91 } kind;
92 /* type of feature */
93 enum {
94 /** not a feature */
95 FEATURE_NONE,
96 /** crypter_t */
97 FEATURE_CRYPTER,
98 /** aead_t */
99 FEATURE_AEAD,
100 /** signer_t */
101 FEATURE_SIGNER,
102 /** hasher_t */
103 FEATURE_HASHER,
104 /** prf_t */
105 FEATURE_PRF,
106 /** diffie_hellman_t */
107 FEATURE_DH,
108 /** rng_t */
109 FEATURE_RNG,
110 /** generic private key support */
111 FEATURE_PRIVKEY,
112 /** generating new private keys */
113 FEATURE_PRIVKEY_GEN,
114 /** private_key_t->sign() */
115 FEATURE_PRIVKEY_SIGN,
116 /** private_key_t->decrypt() */
117 FEATURE_PRIVKEY_DECRYPT,
118 /** generic public key support */
119 FEATURE_PUBKEY,
120 /** public_key_t->verify() */
121 FEATURE_PUBKEY_VERIFY,
122 /** public_key_t->encrypt() */
123 FEATURE_PUBKEY_ENCRYPT,
124 /** parsing certificates */
125 FEATURE_CERT_DECODE,
126 /** generating certificates */
127 FEATURE_CERT_ENCODE,
128 /** EAP server implementation */
129 FEATURE_EAP_SERVER,
130 /** EAP peer implementation */
131 FEATURE_EAP_PEER,
132 /** database_t */
133 FEATURE_DATABASE,
134 /** fetcher_t */
135 FEATURE_FETCHER,
136 /** custom feature, described with a string */
137 FEATURE_CUSTOM,
138 } type;
139 /** More specific data for each type */
140 union {
141 /** FEATURE_CRYPTER */
142 struct {
143 encryption_algorithm_t alg;
144 size_t key_size;
145 } crypter;
146 /** FEATURE_AEAD */
147 struct {
148 encryption_algorithm_t alg;
149 size_t key_size;
150 } aead;
151 /** FEATURE_SIGNER */
152 integrity_algorithm_t signer;
153 /** FEATURE_PRF */
154 pseudo_random_function_t prf;
155 /** FEATURE_HASHER */
156 hash_algorithm_t hasher;
157 /** FEATURE_DH */
158 diffie_hellman_group_t dh_group;
159 /** FEATURE_RNG */
160 rng_quality_t rng_quality;
161 /** FEATURE_PRIVKEY */
162 key_type_t privkey;
163 /** FEATURE_PRIVKEY_GEN */
164 key_type_t privkey_gen;
165 /** FEATURE_PRIVKEY_SIGN */
166 signature_scheme_t privkey_sign;
167 /** FEATURE_PRIVKEY_DECRYPT */
168 encryption_scheme_t privkey_decrypt;
169 /** FEATURE_PUBKEY */
170 key_type_t pubkey;
171 /** FEATURE_PUBKEY_VERIFY */
172 signature_scheme_t pubkey_verify;
173 /** FEATURE_PUBKEY_ENCRYPT */
174 encryption_scheme_t pubkey_encrypt;
175 /** FEATURE_CERT_DECODE/ENCODE */
176 certificate_type_t cert;
177 /** FEATURE_EAP_SERVER/CLIENT */
178 eap_type_t eap;
179 /** FEATURE_DATABASE */
180 db_driver_t database;
181 /** FEATURE_FETCHER */
182 char *fetcher;
183 /** FEATURE_CUSTOM */
184 char *custom;
185
186 /** FEATURE_REGISTER */
187 struct {
188 /** feature specific function to register for this type */
189 void *f;
190 /** final flag to pass for builder_function_t */
191 bool final;
192 } reg;
193
194 /** FEATURE_CALLBACK */
195 struct {
196 /** callback function to invoke for registration */
197 plugin_feature_callback_t f;
198 /** data to pass to callback */
199 void *data;
200 } cb;
201 } arg;
202 };
203
204 #define FEATURE(kind, type, ...) _PLUGIN_FEATURE_##type(kind, __VA_ARGS__)
205
206 /**
207 * Define function to register directly for all upcoming features.
208 *
209 * @param type feature type to register
210 * @param f type specific function to register
211 * @param ... type specific additional arguments
212 */
213 #define PLUGIN_REGISTER(type, f, ...) _PLUGIN_FEATURE_REGISTER_##type(type, f, ##__VA_ARGS__)
214
215 /**
216 * Define a callback to invoke for registering all upcoming features.
217 *
218 * @param cb type specific callback function to register
219 * @param data data pointer to pass to callback
220 */
221 #define PLUGIN_CALLBACK(cb, data) _PLUGIN_FEATURE_CALLBACK(cb, data)
222
223 /**
224 * Define a feature the plugin provides.
225 *
226 * @param type feature type to provide
227 * @param ... type specific arguments
228 */
229 #define PLUGIN_PROVIDE(type, ...) _PLUGIN_FEATURE_##type(PROVIDE, __VA_ARGS__)
230
231 /**
232 * Define a hard dependency for the previously defined feature.
233 *
234 * @param type feature type to provide
235 * @param ... type specific arguments
236 */
237 #define PLUGIN_DEPENDS(type, ...) _PLUGIN_FEATURE_##type(DEPENDS, __VA_ARGS__)
238
239 /**
240 * Define a soft dependency for the previously defined feature.
241 *
242 * @param type feature type to provide
243 * @param ... type specific arguments
244 */
245 #define PLUGIN_SDEPEND(type, ...) _PLUGIN_FEATURE_##type(SDEPEND, __VA_ARGS__)
246
247 #define __PLUGIN_FEATURE(kind, type, ...) (plugin_feature_t){ FEATURE_##kind, FEATURE_##type, { __VA_ARGS__ }}
248 #define _PLUGIN_FEATURE_CRYPTER(kind, alg, size) __PLUGIN_FEATURE(kind, CRYPTER, .crypter = { alg, size })
249 #define _PLUGIN_FEATURE_AEAD(kind, alg, size) __PLUGIN_FEATURE(kind, AEAD, .aead = { alg, size })
250 #define _PLUGIN_FEATURE_SIGNER(kind, alg) __PLUGIN_FEATURE(kind, SIGNER, .signer = alg)
251 #define _PLUGIN_FEATURE_HASHER(kind, alg) __PLUGIN_FEATURE(kind, HASHER, .hasher = alg)
252 #define _PLUGIN_FEATURE_PRF(kind, alg) __PLUGIN_FEATURE(kind, PRF, .prf = alg)
253 #define _PLUGIN_FEATURE_DH(kind, group) __PLUGIN_FEATURE(kind, DH, .dh_group = group)
254 #define _PLUGIN_FEATURE_RNG(kind, quality) __PLUGIN_FEATURE(kind, RNG, .rng_quality = quality)
255 #define _PLUGIN_FEATURE_PRIVKEY(kind, type) __PLUGIN_FEATURE(kind, PRIVKEY, .privkey = type)
256 #define _PLUGIN_FEATURE_PRIVKEY_GEN(kind, type) __PLUGIN_FEATURE(kind, PRIVKEY_GEN, .privkey_gen = type)
257 #define _PLUGIN_FEATURE_PRIVKEY_SIGN(kind, scheme) __PLUGIN_FEATURE(kind, PRIVKEY_SIGN, .privkey_sign = scheme)
258 #define _PLUGIN_FEATURE_PRIVKEY_DECRYPT(kind, scheme) __PLUGIN_FEATURE(kind, PRIVKEY_DECRYPT, .privkey_decrypt = scheme)
259 #define _PLUGIN_FEATURE_PUBKEY(kind, type) __PLUGIN_FEATURE(kind, PUBKEY, .pubkey = type)
260 #define _PLUGIN_FEATURE_PUBKEY_VERIFY(kind, scheme) __PLUGIN_FEATURE(kind, PUBKEY_VERIFY, .pubkey_verify = scheme)
261 #define _PLUGIN_FEATURE_PUBKEY_ENCRYPT(kind, scheme) __PLUGIN_FEATURE(kind, PUBKEY_ENCRYPT, .pubkey_encrypt = scheme)
262 #define _PLUGIN_FEATURE_CERT_DECODE(kind, type) __PLUGIN_FEATURE(kind, CERT_DECODE, .cert = type)
263 #define _PLUGIN_FEATURE_CERT_ENCODE(kind, type) __PLUGIN_FEATURE(kind, CERT_ENCODE, .cert = type)
264 #define _PLUGIN_FEATURE_EAP_SERVER(kind, type) __PLUGIN_FEATURE(kind, EAP_SERVER, .eap = type)
265 #define _PLUGIN_FEATURE_EAP_PEER(kind, type) __PLUGIN_FEATURE(kind, EAP_PEER, .eap = type)
266 #define _PLUGIN_FEATURE_DATABASE(kind, type) __PLUGIN_FEATURE(kind, DATABASE, .database = type)
267 #define _PLUGIN_FEATURE_FETCHER(kind, type) __PLUGIN_FEATURE(kind, FETCHER, .fetcher = type)
268
269 #define __PLUGIN_FEATURE_REGISTER(type, _f) (plugin_feature_t){ FEATURE_REGISTER, FEATURE_##type, .arg.reg.f = _f }
270 #define __PLUGIN_FEATURE_REGISTER_BUILDER(type, _f, _final) (plugin_feature_t){ FEATURE_REGISTER, FEATURE_##type, .arg.reg = {.f = _f, .final = _final, }}
271 #define _PLUGIN_FEATURE_REGISTER_CRYPTER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
272 #define _PLUGIN_FEATURE_REGISTER_AEAD(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
273 #define _PLUGIN_FEATURE_REGISTER_SIGNER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
274 #define _PLUGIN_FEATURE_REGISTER_HASHER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
275 #define _PLUGIN_FEATURE_REGISTER_PRF(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
276 #define _PLUGIN_FEATURE_REGISTER_DH(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
277 #define _PLUGIN_FEATURE_REGISTER_RNG(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
278 #define _PLUGIN_FEATURE_REGISTER_PRIVKEY(type, f, final) __PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
279 #define _PLUGIN_FEATURE_REGISTER_PRIVKEY_GEN(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
280 #define _PLUGIN_FEATURE_REGISTER_PUBKEY(type, f, final) __PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
281 #define _PLUGIN_FEATURE_REGISTER_CERT_DECODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
282 #define _PLUGIN_FEATURE_REGISTER_CERT_ENCODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
283 #define _PLUGIN_FEATURE_REGISTER_DATABASE(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
284 #define _PLUGIN_FEATURE_REGISTER_FETCHER(type, f) __PLUGIN_FEATURE_REGISTER(type, f)
285
286 #define _PLUGIN_FEATURE_CALLBACK(_cb, _data) (plugin_feature_t){ FEATURE_CALLBACK, FEATURE_NONE, .arg.cb = { .f = _cb, .data = _data } }
287
288 /**
289 * Names for plugin_feature_t types.
290 */
291 extern enum_name_t *plugin_feature_names;
292
293 /**
294 * Check if feature a matches to feature b.
295 *
296 * @param a feature to check
297 * @param b feature to match against
298 * @return TRUE if a matches b
299 */
300 bool plugin_feature_matches(plugin_feature_t *a, plugin_feature_t *b);
301
302 /**
303 * Get a string describing feature.
304 *
305 * @param feature feature to describe
306 * @return allocated string describing feature
307 */
308 char* plugin_feature_get_string(plugin_feature_t *feature);
309
310 /**
311 * Load a plugin feature using a REGISTER/CALLBACK feature entry.
312 *
313 * @param plugin plugin providing feature
314 * @param feature feature to load
315 * @param reg REGISTER/CALLBACK feature entry to use for registration
316 */
317 bool plugin_feature_load(plugin_t *plugin, plugin_feature_t *feature,
318 plugin_feature_t *reg);
319
320 /**
321 * Unload a plugin feature using a REGISTER/CALLBACK feature entry.
322 *
323 * @param plugin plugin providing feature
324 * @param feature feature to unload
325 * @param reg REGISTER/CALLBACK feature entry to use for deregistration
326 */
327 bool plugin_feature_unload(plugin_t *plugin, plugin_feature_t *feature,
328 plugin_feature_t *reg);
329
330 #endif /** PLUGIN_FEATURE_H_ @}*/