src/libstrongswan/crypto/crypto_factory.h

   1 /*
   2  * Copyright (C) 2008 Martin Willi
   3  * Copyright (C) 2016-2019 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/drbgs/drbg.h>
  37 #include <crypto/nonce_gen.h>
  38 #include <crypto/diffie_hellman.h>
  39 #include <crypto/transform.h>
  40
  41 #define CRYPTO_MAX_ALG_LINE          120   /* characters */
  42
  43 /**
  44  * Constructor function for crypters
  45  */
  46 typedef crypter_t* (*crypter_constructor_t)(encryption_algorithm_t algo,
  47                                                                                         size_t key_size);
  48 /**
  49  * Constructor function for aead transforms
  50  */
  51 typedef aead_t* (*aead_constructor_t)(encryption_algorithm_t algo,
  52                                                                           size_t key_size, size_t salt_size);
  53 /**
  54  * Constructor function for signers
  55  */
  56 typedef signer_t* (*signer_constructor_t)(integrity_algorithm_t algo);
  57
  58 /**
  59  * Constructor function for hashers
  60  */
  61 typedef hasher_t* (*hasher_constructor_t)(hash_algorithm_t algo);
  62
  63 /**
  64  * Constructor function for pseudo random functions
  65  */
  66 typedef prf_t* (*prf_constructor_t)(pseudo_random_function_t algo);
  67
  68 /**
  69  * Constructor function for extended output functions
  70  */
  71 typedef xof_t* (*xof_constructor_t)(ext_out_function_t algo);
  72
  73 /**
  74  * Constructor function for deterministic random bit generators
  75  */
  76 typedef drbg_t* (*drbg_constructor_t)(drbg_type_t type, uint32_t strength,
  77                                                                 rng_t *entropy, chunk_t personalization_str);
  78
  79 /**
  80  * Constructor function for source of randomness
  81  */
  82 typedef rng_t* (*rng_constructor_t)(rng_quality_t quality);
  83
  84 /**
  85  * Constructor function for nonce generators
  86  */
  87 typedef nonce_gen_t* (*nonce_gen_constructor_t)();
  88
  89 /**
  90  * Constructor function for diffie hellman
  91  *
  92  * The DH constructor accepts additional arguments for:
  93  * - MODP_CUSTOM: chunk_t generator, chunk_t prime
  94  */
  95 typedef diffie_hellman_t* (*dh_constructor_t)(diffie_hellman_group_t group, ...);
  96
  97 /**
  98  * Handles crypto modules and creates instances.
  99  */
 100 struct crypto_factory_t {
 101
 102         /**
 103          * Create a crypter instance.
 104          *
 105          * @param algo                  encryption algorithm
 106          * @param key_size              length of the key in bytes
 107          * @return                              crypter_t instance, NULL if not supported
 108          */
 109         crypter_t* (*create_crypter)(crypto_factory_t *this,
 110                                                                  encryption_algorithm_t algo, size_t key_size);
 111
 112         /**
 113          * Create a aead instance.
 114          *
 115          * @param algo                  encryption algorithm
 116          * @param key_size              length of the key in bytes
 117          * @param salt_size             size of salt, implicit part of the nonce
 118          * @return                              aead_t instance, NULL if not supported
 119          */
 120         aead_t* (*create_aead)(crypto_factory_t *this,
 121                                                    encryption_algorithm_t algo,
 122                                                    size_t key_size, size_t salt_size);
 123
 124         /**
 125          * Create a symmetric signer instance.
 126          *
 127          * @param algo                  MAC algorithm to use
 128          * @return                              signer_t instance, NULL if not supported
 129          */
 130         signer_t* (*create_signer)(crypto_factory_t *this,
 131                                                            integrity_algorithm_t algo);
 132
 133         /**
 134          * Create a hasher instance.
 135          *
 136          * @param algo                  hash algorithm
 137          * @return                              hasher_t instance, NULL if not supported
 138          */
 139         hasher_t* (*create_hasher)(crypto_factory_t *this, hash_algorithm_t algo);
 140
 141         /**
 142          * Create a pseudo random function instance.
 143          *
 144          * @param algo                  PRF algorithm to use
 145          * @return                              prf_t instance, NULL if not supported
 146          */
 147         prf_t* (*create_prf)(crypto_factory_t *this, pseudo_random_function_t algo);
 148
 149         /**
 150          * Create an extended output function instance.
 151          *
 152          * @param algo                  XOF algorithm to use
 153          * @return                              xof_t instance, NULL if not supported
 154          */
 155         xof_t* (*create_xof)(crypto_factory_t *this, ext_out_function_t algo);
 156
 157         /**
 158          * Create a deterministic random bit generator instance.
 159          *
 160          * @param type                                  DRBG type to use
 161          * @param strength                              security strength in bits
 162          * @param entropy                               entropy source to be used (adopted)
 163          * @param personalization_str   optional personalization string
 164          * @return                                              drbg_t instance, NULL if not supported
 165          */
 166         drbg_t* (*create_drbg)(crypto_factory_t *this, drbg_type_t type,
 167                                                    uint32_t strength, rng_t *entropy,
 168                                                    chunk_t personalization_str);
 169
 170         /**
 171          * Create a source of randomness.
 172          *
 173          * @param quality               required randomness quality
 174          * @return                              rng_t instance, NULL if no RNG with such a quality
 175          */
 176         rng_t* (*create_rng)(crypto_factory_t *this, rng_quality_t quality);
 177
 178         /**
 179          * Create a nonce generator instance.
 180          *
 181          * @return                              nonce_gen_t instance, NULL if not supported
 182          */
 183         nonce_gen_t* (*create_nonce_gen)(crypto_factory_t *this);
 184
 185         /**
 186          * Create a diffie hellman instance.
 187          *
 188          * Additional arguments are passed to the DH constructor.
 189          *
 190          * @param group                 diffie hellman group
 191          * @return                              diffie_hellman_t instance, NULL if not supported
 192          */
 193         diffie_hellman_t* (*create_dh)(crypto_factory_t *this,
 194                                                                    diffie_hellman_group_t group, ...);
 195
 196         /**
 197          * Register a crypter constructor.
 198          *
 199          * @param algo                  algorithm to constructor
 200          * @param key size              key size to perform benchmarking for
 201          * @param plugin_name   plugin that registered this algorithm
 202          * @param create                constructor function for that algorithm
 203          * @return                              TRUE if registered, FALSE if test vector failed
 204          */
 205         bool (*add_crypter)(crypto_factory_t *this, encryption_algorithm_t algo,
 206                                                 size_t key_size, const char *plugin_name,
 207                                                 crypter_constructor_t create);
 208
 209         /**
 210          * Unregister a crypter constructor.
 211          *
 212          * @param create                constructor function to unregister
 213          */
 214         void (*remove_crypter)(crypto_factory_t *this, crypter_constructor_t create);
 215
 216         /**
 217          * Unregister a aead constructor.
 218          *
 219          * @param create                constructor function to unregister
 220          */
 221         void (*remove_aead)(crypto_factory_t *this, aead_constructor_t create);
 222
 223         /**
 224          * Register a aead constructor.
 225          *
 226          * @param algo                  algorithm to constructor
 227          * @param key size              key size to perform benchmarking for
 228          * @param plugin_name   plugin that registered this algorithm
 229          * @param create                constructor function for that algorithm
 230          * @return                              TRUE if registered, FALSE if test vector failed
 231          */
 232         bool (*add_aead)(crypto_factory_t *this, encryption_algorithm_t algo,
 233                                          size_t key_size, const char *plugin_name,
 234                                          aead_constructor_t create);
 235
 236         /**
 237          * Register a signer constructor.
 238          *
 239          * @param algo                  algorithm to constructor
 240          * @param plugin_name   plugin that registered this algorithm
 241          * @param create                constructor function for that algorithm
 242          * @return                              TRUE if registered, FALSE if test vector failed
 243          */
 244         bool (*add_signer)(crypto_factory_t *this, integrity_algorithm_t algo,
 245                                             const char *plugin_name, signer_constructor_t create);
 246
 247         /**
 248          * Unregister a signer constructor.
 249          *
 250          * @param create                constructor function to unregister
 251          */
 252         void (*remove_signer)(crypto_factory_t *this, signer_constructor_t create);
 253
 254         /**
 255          * Register a hasher constructor.
 256          *
 257          * @param algo                  algorithm to constructor
 258          * @param plugin_name   plugin that registered this algorithm
 259          * @param create                constructor function for that algorithm
 260          * @return                              TRUE if registered, FALSE if test vector failed
 261          */
 262         bool (*add_hasher)(crypto_factory_t *this, hash_algorithm_t algo,
 263                                            const char *plugin_name, hasher_constructor_t create);
 264
 265         /**
 266          * Unregister a hasher constructor.
 267          *
 268          * @param create                constructor function to unregister
 269          */
 270         void (*remove_hasher)(crypto_factory_t *this, hasher_constructor_t create);
 271
 272         /**
 273          * Register a prf constructor.
 274          *
 275          * @param algo                  algorithm to constructor
 276          * @param plugin_name   plugin that registered this algorithm
 277          * @param create                constructor function for that algorithm
 278          * @return                              TRUE if registered, FALSE if test vector failed
 279          */
 280         bool (*add_prf)(crypto_factory_t *this, pseudo_random_function_t algo,
 281                                         const char *plugin_name, prf_constructor_t create);
 282
 283         /**
 284          * Unregister a prf constructor.
 285          *
 286          * @param create                constructor function to unregister
 287          */
 288         void (*remove_prf)(crypto_factory_t *this, prf_constructor_t create);
 289
 290         /**
 291          * Register an xof constructor.
 292          *
 293          * @param algo                  algorithm to constructor
 294          * @param plugin_name   plugin that registered this algorithm
 295          * @param create                constructor function for that algorithm
 296          * @return                              TRUE if registered, FALSE if test vector failed
 297          */
 298         bool (*add_xof)(crypto_factory_t *this, ext_out_function_t algo,
 299                                         const char *plugin_name, xof_constructor_t create);
 300
 301         /**
 302          * Unregister an xof constructor.
 303          *
 304          * @param create                constructor function to unregister
 305          */
 306         void (*remove_xof)(crypto_factory_t *this, xof_constructor_t create);
 307
 308         /**
 309          * Register a drbg constructor.
 310          *
 311          * @param type                  type to constructor
 312          * @param plugin_name   plugin that registered this algorithm
 313          * @param create                constructor function for that algorithm
 314          * @return                              TRUE if registered, FALSE if test vector failed
 315          */
 316         bool (*add_drbg)(crypto_factory_t *this, drbg_type_t type,
 317                                          const char *plugin_name, drbg_constructor_t create);
 318
 319         /**
 320          * Unregister a drbg constructor.
 321          *
 322          * @param create                constructor function to unregister
 323          */
 324         void (*remove_drbg)(crypto_factory_t *this, drbg_constructor_t create);
 325
 326         /**
 327          * Register a source of randomness.
 328          *
 329          * @param quality               quality of randomness this RNG serves
 330          * @param plugin_name   plugin that registered this algorithm
 331          * @param create                constructor function for such a quality
 332          * @return                              TRUE if registered, FALSE if test vector failed
 333          */
 334         bool (*add_rng)(crypto_factory_t *this, rng_quality_t quality,
 335                                         const char *plugin_name, rng_constructor_t create);
 336
 337         /**
 338          * Unregister a source of randomness.
 339          *
 340          * @param create                constructor function to unregister
 341          */
 342         void (*remove_rng)(crypto_factory_t *this, rng_constructor_t create);
 343
 344         /**
 345          * Register a nonce generator.
 346          *
 347          * @param plugin_name   plugin that registered this algorithm
 348          * @param create                constructor function for that nonce generator
 349          * @return                              TRUE if registered, FALSE if test vector failed
 350          */
 351         bool (*add_nonce_gen)(crypto_factory_t *this, const char *plugin_name,
 352                                                   nonce_gen_constructor_t create);
 353
 354         /**
 355          * Unregister a nonce generator.
 356          *
 357          * @param create                constructor function to unregister
 358          */
 359         void (*remove_nonce_gen)(crypto_factory_t *this,
 360                                                          nonce_gen_constructor_t create);
 361
 362         /**
 363          * Register a diffie hellman constructor.
 364          *
 365          * @param group                 dh group to constructor
 366          * @param plugin_name   plugin that registered this algorithm
 367          * @param create                constructor function for that algorithm
 368          * @return                              TRUE if registered, FALSE if test vector failed
 369          */
 370         bool (*add_dh)(crypto_factory_t *this, diffie_hellman_group_t group,
 371                                    const char *plugin_name, dh_constructor_t create);
 372
 373         /**
 374          * Unregister a diffie hellman constructor.
 375          *
 376          * @param create                constructor function to unregister
 377          */
 378         void (*remove_dh)(crypto_factory_t *this, dh_constructor_t create);
 379
 380         /**
 381          * Create an enumerator over all registered crypter algorithms.
 382          *
 383          * @return                              enumerator over encryption_algorithm_t, plugin
 384          */
 385         enumerator_t* (*create_crypter_enumerator)(crypto_factory_t *this);
 386
 387         /**
 388          * Create an enumerator over all registered aead algorithms.
 389          *
 390          * @return                              enumerator over encryption_algorithm_t, plugin
 391          */
 392         enumerator_t* (*create_aead_enumerator)(crypto_factory_t *this);
 393
 394         /**
 395          * Create an enumerator over all registered signer algorithms.
 396          *
 397          * @return                              enumerator over integrity_algorithm_t, plugin
 398          */
 399         enumerator_t* (*create_signer_enumerator)(crypto_factory_t *this);
 400
 401         /**
 402          * Create an enumerator over all registered hasher algorithms.
 403          *
 404          * @return                              enumerator over hash_algorithm_t, plugin
 405          */
 406         enumerator_t* (*create_hasher_enumerator)(crypto_factory_t *this);
 407
 408         /**
 409          * Create an enumerator over all registered PRFs.
 410          *
 411          * @return                              enumerator over pseudo_random_function_t, plugin
 412          */
 413         enumerator_t* (*create_prf_enumerator)(crypto_factory_t *this);
 414
 415         /**
 416          * Create an enumerator over all registered XOFs.
 417          *
 418          * @return                              enumerator over ext_out_function_t, plugin
 419          */
 420         enumerator_t* (*create_xof_enumerator)(crypto_factory_t *this);
 421
 422         /**
 423          * Create an enumerator over all registered DRBGs.
 424          *
 425          * @return                              enumerator over drbg_type_t, plugin
 426          */
 427         enumerator_t* (*create_drbg_enumerator)(crypto_factory_t *this);
 428
 429         /**
 430          * Create an enumerator over all registered diffie hellman groups.
 431          *
 432          * @return                              enumerator over diffie_hellman_group_t, plugin
 433          */
 434         enumerator_t* (*create_dh_enumerator)(crypto_factory_t *this);
 435
 436         /**
 437          * Create an enumerator over all registered random generators.
 438          *
 439          * @return                              enumerator over rng_quality_t, plugin
 440          */
 441         enumerator_t* (*create_rng_enumerator)(crypto_factory_t *this);
 442
 443         /**
 444          * Create an enumerator over all registered nonce generators.
 445          *
 446          * @return                              enumerator over plugin
 447          */
 448         enumerator_t* (*create_nonce_gen_enumerator)(crypto_factory_t *this);
 449
 450         /**
 451          * Add a test vector to the crypto factory.
 452          *
 453          * @param type                  type of the test vector
 454          * @param vector                pointer to a test vector, defined in crypto_tester.h
 455          */
 456         void (*add_test_vector)(crypto_factory_t *this, transform_type_t type,
 457                                                         void *vector);
 458
 459         /**
 460          * Create an enumerator verifying transforms using known test vectors.
 461          *
 462          * The resulting enumerator enumerates over an u_int with the type
 463          * specific transform identifier, the plugin name providing the transform,
 464          * and a boolean value indicating success/failure for the given transform.
 465          *
 466          * @param type                  transform type to test
 467          * @return                              enumerator over (u_int, char*, bool)
 468          */
 469         enumerator_t* (*create_verify_enumerator)(crypto_factory_t *this,
 470                                                                                           transform_type_t type);
 471
 472         /**
 473          * Destroy a crypto_factory instance.
 474          */
 475         void (*destroy)(crypto_factory_t *this);
 476 };
 477
 478 /**
 479  * Create a crypto_factory instance.
 480  */
 481 crypto_factory_t *crypto_factory_create();
 482
 483 #endif /** CRYPTO_FACTORY_H_ @}*/