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 type          feature type to register
 219  * @param cb            type specific callback function to register
 220  * @param data          data pointer to pass to callback
 221  */
 222 #define PLUGIN_CALLBACK(cb, data) _PLUGIN_FEATURE_CALLBACK(cb, data)
 223
 224 /**
 225  * Define a feature the plugin provides.
 226  *
 227  * @param type          feature type to provide
 228  * @param ...           type specific arguments
 229  */
 230 #define PLUGIN_PROVIDE(type, ...) _PLUGIN_FEATURE_##type(PROVIDE, __VA_ARGS__)
 231
 232 /**
 233  * Define a hard dependency for the previously defined feature.
 234  *
 235  * @param type          feature type to provide
 236  * @param ...           type specific arguments
 237  */
 238 #define PLUGIN_DEPENDS(type, ...) _PLUGIN_FEATURE_##type(DEPENDS, __VA_ARGS__)
 239
 240 /**
 241  * Define a soft dependency for the previously defined feature.
 242  *
 243  * @param type          feature type to provide
 244  * @param ...           type specific arguments
 245  */
 246 #define PLUGIN_SDEPEND(type, ...) _PLUGIN_FEATURE_##type(SDEPEND, __VA_ARGS__)
 247
 248 #define __PLUGIN_FEATURE(kind, type, ...)                                       (plugin_feature_t){ FEATURE_##kind, FEATURE_##type, { __VA_ARGS__ }}
 249 #define _PLUGIN_FEATURE_CRYPTER(kind, alg, size)                        __PLUGIN_FEATURE(kind, CRYPTER, .crypter = { alg, size })
 250 #define _PLUGIN_FEATURE_AEAD(kind, alg, size)                           __PLUGIN_FEATURE(kind, AEAD, .aead = { alg, size })
 251 #define _PLUGIN_FEATURE_SIGNER(kind, alg)                                       __PLUGIN_FEATURE(kind, SIGNER, .signer = alg)
 252 #define _PLUGIN_FEATURE_HASHER(kind, alg)                                       __PLUGIN_FEATURE(kind, HASHER, .hasher = alg)
 253 #define _PLUGIN_FEATURE_PRF(kind, alg)                                          __PLUGIN_FEATURE(kind, PRF, .prf = alg)
 254 #define _PLUGIN_FEATURE_DH(kind, group)                                         __PLUGIN_FEATURE(kind, DH, .dh_group = group)
 255 #define _PLUGIN_FEATURE_RNG(kind, quality)                                      __PLUGIN_FEATURE(kind, RNG, .rng_quality = quality)
 256 #define _PLUGIN_FEATURE_PRIVKEY(kind, type)                                     __PLUGIN_FEATURE(kind, PRIVKEY, .privkey = type)
 257 #define _PLUGIN_FEATURE_PRIVKEY_GEN(kind, type)                         __PLUGIN_FEATURE(kind, PRIVKEY_GEN, .privkey_gen = type)
 258 #define _PLUGIN_FEATURE_PRIVKEY_SIGN(kind, scheme)                      __PLUGIN_FEATURE(kind, PRIVKEY_SIGN, .privkey_sign = scheme)
 259 #define _PLUGIN_FEATURE_PRIVKEY_DECRYPT(kind, scheme)           __PLUGIN_FEATURE(kind, PRIVKEY_DECRYPT, .privkey_decrypt = scheme)
 260 #define _PLUGIN_FEATURE_PUBKEY(kind, type)                                      __PLUGIN_FEATURE(kind, PUBKEY, .pubkey = type)
 261 #define _PLUGIN_FEATURE_PUBKEY_VERIFY(kind, scheme)                     __PLUGIN_FEATURE(kind, PUBKEY_VERIFY, .pubkey_verify = scheme)
 262 #define _PLUGIN_FEATURE_PUBKEY_ENCRYPT(kind, scheme)            __PLUGIN_FEATURE(kind, PUBKEY_ENCRYPT, .pubkey_encrypt = scheme)
 263 #define _PLUGIN_FEATURE_CERT_DECODE(kind, type)                         __PLUGIN_FEATURE(kind, CERT_DECODE, .cert = type)
 264 #define _PLUGIN_FEATURE_CERT_ENCODE(kind, type)                         __PLUGIN_FEATURE(kind, CERT_ENCODE, .cert = type)
 265 #define _PLUGIN_FEATURE_EAP_SERVER(kind, type)                          __PLUGIN_FEATURE(kind, EAP_SERVER, .eap = type)
 266 #define _PLUGIN_FEATURE_EAP_PEER(kind, type)                            __PLUGIN_FEATURE(kind, EAP_PEER, .eap = type)
 267 #define _PLUGIN_FEATURE_DATABASE(kind, type)                            __PLUGIN_FEATURE(kind, DATABASE, .database = type)
 268 #define _PLUGIN_FEATURE_FETCHER(kind, type)                                     __PLUGIN_FEATURE(kind, FETCHER, .fetcher = type)
 269
 270 #define __PLUGIN_FEATURE_REGISTER(type, _f)                                     (plugin_feature_t){ FEATURE_REGISTER, FEATURE_##type, .arg.reg.f = _f }
 271 #define __PLUGIN_FEATURE_REGISTER_BUILDER(type, _f, _final)     (plugin_feature_t){ FEATURE_REGISTER, FEATURE_##type, .arg.reg = {.f = _f, .final = _final, }}
 272 #define _PLUGIN_FEATURE_REGISTER_CRYPTER(type, f)                       __PLUGIN_FEATURE_REGISTER(type, f)
 273 #define _PLUGIN_FEATURE_REGISTER_AEAD(type, f)                          __PLUGIN_FEATURE_REGISTER(type, f)
 274 #define _PLUGIN_FEATURE_REGISTER_SIGNER(type, f)                        __PLUGIN_FEATURE_REGISTER(type, f)
 275 #define _PLUGIN_FEATURE_REGISTER_HASHER(type, f)                        __PLUGIN_FEATURE_REGISTER(type, f)
 276 #define _PLUGIN_FEATURE_REGISTER_PRF(type, f)                           __PLUGIN_FEATURE_REGISTER(type, f)
 277 #define _PLUGIN_FEATURE_REGISTER_DH(type, f)                            __PLUGIN_FEATURE_REGISTER(type, f)
 278 #define _PLUGIN_FEATURE_REGISTER_RNG(type, f)                           __PLUGIN_FEATURE_REGISTER(type, f)
 279 #define _PLUGIN_FEATURE_REGISTER_PRIVKEY(type, f, final)        __PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
 280 #define _PLUGIN_FEATURE_REGISTER_PRIVKEY_GEN(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
 281 #define _PLUGIN_FEATURE_REGISTER_PUBKEY(type, f, final)         __PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
 282 #define _PLUGIN_FEATURE_REGISTER_CERT_DECODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
 283 #define _PLUGIN_FEATURE_REGISTER_CERT_ENCODE(type, f, final)__PLUGIN_FEATURE_REGISTER_BUILDER(type, f, final)
 284 #define _PLUGIN_FEATURE_REGISTER_DATABASE(type, f)                      __PLUGIN_FEATURE_REGISTER(type, f)
 285 #define _PLUGIN_FEATURE_REGISTER_FETCHER(type, f)                       __PLUGIN_FEATURE_REGISTER(type, f)
 286
 287 #define _PLUGIN_FEATURE_CALLBACK(_cb, _data) (plugin_feature_t){ FEATURE_CALLBACK, FEATURE_NONE, .arg.cb = { .f = _cb, .data = _data } }
 288
 289 /**
 290  * Names for plugin_feature_t types.
 291  */
 292 extern enum_name_t *plugin_feature_names;
 293
 294 /**
 295  * Check if feature a matches to feature b.
 296  *
 297  * @param a                     feature to check
 298  * @param b                     feature to match against
 299  * @return                      TRUE if a matches b
 300  */
 301 bool plugin_feature_matches(plugin_feature_t *a, plugin_feature_t *b);
 302
 303 /**
 304  * Get a string describing feature.
 305  *
 306  * @param feature       feature to describe
 307  * @return                      allocated string describing feature
 308  */
 309 char* plugin_feature_get_string(plugin_feature_t *feature);
 310
 311 #endif /** PLUGIN_FEATURE_H_ @}*/