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_ @}*/