src/libstrongswan/crypto/crypto_tester.h

   1 /*
   2  * Copyright (C) 2009 Martin Willi
   3  * Copyright (C) 2016-2019 Andreas Steffen
   4  *
   5  * Copyright (C) secunet Security Networks AG
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup crypto_tester crypto_tester
  20  * @{ @ingroup crypto
  21  */
  22
  23 #ifndef CRYPTO_TESTER_H_
  24 #define CRYPTO_TESTER_H_
  25
  26 typedef struct crypto_tester_t crypto_tester_t;
  27
  28 #include <crypto/crypto_factory.h>
  29
  30 typedef struct crypter_test_vector_t crypter_test_vector_t;
  31 typedef struct aead_test_vector_t aead_test_vector_t;
  32 typedef struct signer_test_vector_t signer_test_vector_t;
  33 typedef struct hasher_test_vector_t hasher_test_vector_t;
  34 typedef struct prf_test_vector_t prf_test_vector_t;
  35 typedef struct xof_test_vector_t xof_test_vector_t;
  36 typedef struct kdf_test_vector_t kdf_test_vector_t;
  37 typedef struct kdf_test_args_t kdf_test_args_t;
  38 typedef struct drbg_test_vector_t drbg_test_vector_t;
  39 typedef struct rng_test_vector_t rng_test_vector_t;
  40 typedef struct ke_test_vector_t ke_test_vector_t;
  41
  42 struct crypter_test_vector_t {
  43         /** encryption algorithm this vector tests */
  44         encryption_algorithm_t alg;
  45         /** key length to use, in bytes */
  46         size_t key_size;
  47         /** encryption key of test vector */
  48         u_char *key;
  49         /** initialization vector, using crypters blocksize bytes */
  50         u_char *iv;
  51         /** length of plain and cipher text */
  52         size_t len;
  53         /** plain text */
  54         u_char *plain;
  55         /** cipher text */
  56         u_char *cipher;
  57 };
  58
  59 struct aead_test_vector_t {
  60         /** encryption algorithm this vector tests */
  61         encryption_algorithm_t alg;
  62         /** key length to use, in bytes */
  63         size_t key_size;
  64         /** salt length to use, in bytes */
  65         size_t salt_size;
  66         /** encryption key of test vector */
  67         u_char *key;
  68         /** initialization vector, using crypters blocksize bytes */
  69         u_char *iv;
  70         /** length of associated data */
  71         size_t alen;
  72         /** associated data */
  73         u_char *adata;
  74         /** length of plain text */
  75         size_t len;
  76         /** plain text */
  77         u_char *plain;
  78         /** cipher text */
  79         u_char *cipher;
  80 };
  81
  82 struct signer_test_vector_t {
  83         /** signer algorithm this test vector tests */
  84         integrity_algorithm_t alg;
  85         /** key to use, with a length the algorithm expects */
  86         u_char *key;
  87         /** size of the input data */
  88         size_t len;
  89         /** input data */
  90         u_char *data;
  91         /** expected output, with output size of the tested algorithm */
  92         u_char *mac;
  93 };
  94
  95 struct hasher_test_vector_t {
  96         /** hash algorithm this test vector tests */
  97         hash_algorithm_t alg;
  98         /** length of the input data */
  99         size_t len;
 100         /** input data */
 101         u_char *data;
 102         /** expected hash, with hash size of the tested algorithm */
 103         u_char *hash;
 104 };
 105
 106 struct prf_test_vector_t {
 107         /** prf algorithm this test vector tests */
 108         pseudo_random_function_t alg;
 109         /** is this PRF stateful? */
 110         bool stateful;
 111         /** key length to use, in bytes */
 112         size_t key_size;
 113         /** key to use */
 114         u_char *key;
 115         /** size of the seed data */
 116         size_t len;
 117         /** seed data */
 118         u_char *seed;
 119         /** expected output, with block size of the tested algorithm */
 120         u_char *out;
 121 };
 122
 123 struct xof_test_vector_t {
 124         /** xof algorithm this test vector tests */
 125         ext_out_function_t alg;
 126         /** size of the seed data */
 127         size_t len;
 128         /** seed data */
 129         u_char *seed;
 130         /** size of the output */
 131         size_t out_len;
 132         /** expected output of size*/
 133         u_char *out;
 134 };
 135
 136 struct kdf_test_vector_t {
 137         /** kdf algorithm this test vector tests */
 138         key_derivation_function_t alg;
 139         /** argument passed to constructor, type depends on alg */
 140         union {
 141                 pseudo_random_function_t prf;
 142         } arg;
 143         /** optional key */
 144         chunk_t key;
 145         /** optional salt */
 146         chunk_t salt;
 147         /** expected output */
 148         chunk_t out;
 149 };
 150
 151 struct kdf_test_args_t {
 152         /** the arguments used to construct the KDF */
 153         va_list args;
 154 };
 155
 156 struct drbg_test_vector_t {
 157         /** drbg type this test vector tests */
 158         drbg_type_t type;
 159         /** security strength in bits */
 160         uint32_t strength;
 161         /** optional personalization string */
 162         chunk_t personalization_str;
 163         /** entropy_input | nonce | entropy_input_reseed */
 164         chunk_t entropy;
 165         /** returned output bits */
 166         chunk_t out;
 167 };
 168
 169 /**
 170  * Test vector for a RNG.
 171  *
 172  * Contains a callback function to analyze the output of a RNG,
 173  */
 174 struct rng_test_vector_t {
 175         /** quality of random data this test vector tests */
 176         rng_quality_t quality;
 177         /** callback function to test RNG output, returns TRUE if data ok */
 178         bool (*test)(void *user, chunk_t data);
 179         /** number of bytes the function requests */
 180         size_t len;
 181         /** user data passed back to the test() function on invocation */
 182         void *user;
 183 };
 184
 185 struct ke_test_vector_t {
 186         /** key exchange method to test */
 187         key_exchange_method_t method;
 188         /** private key of alice */
 189         u_char *priv_a;
 190         /** private key of bob */
 191         u_char *priv_b;
 192         /** length of private keys */
 193         size_t priv_len;
 194         /** expected public key of alice */
 195         u_char *pub_a;
 196         /** expected public key of bob */
 197         u_char *pub_b;
 198         /** size of public keys */
 199         size_t pub_len;
 200         /** expected shared secret */
 201         u_char *shared;
 202         /** size of shared secret */
 203         size_t shared_len;
 204 };
 205
 206 /**
 207  * Cryptographic primitive testing framework.
 208  */
 209 struct crypto_tester_t {
 210
 211         /**
 212          * Test a crypter algorithm, optionally using a specified key size.
 213          *
 214          * @param alg                   algorithm to test
 215          * @param key_size              key size to test, 0 for default
 216          * @param create                constructor function for the crypter
 217          * @param speed                 speed test result, NULL to omit
 218          * @return                              TRUE if test passed
 219          */
 220         bool (*test_crypter)(crypto_tester_t *this, encryption_algorithm_t alg,
 221                                                  size_t key_size, crypter_constructor_t create,
 222                                                  u_int *speed, const char *plugin_name);
 223
 224         /**
 225          * Test an aead algorithm, optionally using a specified key size.
 226          *
 227          * @param alg                   algorithm to test
 228          * @param key_size              key size to test, 0 for default
 229          * @param salt_size             salt length to test, 0 for default
 230          * @param create                constructor function for the aead transform
 231          * @param speed                 speed test result, NULL to omit
 232          * @return                              TRUE if test passed
 233          */
 234         bool (*test_aead)(crypto_tester_t *this, encryption_algorithm_t alg,
 235                                           size_t key_size, size_t salt_size,
 236                                           aead_constructor_t create,
 237                                           u_int *speed, const char *plugin_name);
 238         /**
 239          * Test a signer algorithm.
 240          *
 241          * @param alg                   algorithm to test
 242          * @param create                constructor function for the signer
 243          * @param speed                 speed test result, NULL to omit
 244          * @return                              TRUE if test passed
 245          */
 246         bool (*test_signer)(crypto_tester_t *this, integrity_algorithm_t alg,
 247                                                 signer_constructor_t create,
 248                                                 u_int *speed, const char *plugin_name);
 249         /**
 250          * Test a hasher algorithm.
 251          *
 252          * @param alg                   algorithm to test
 253          * @param create                constructor function for the hasher
 254          * @param speed                 speed test result, NULL to omit
 255          * @return                              TRUE if test passed
 256          */
 257         bool (*test_hasher)(crypto_tester_t *this, hash_algorithm_t alg,
 258                                                 hasher_constructor_t create,
 259                                                 u_int *speed, const char *plugin_name);
 260         /**
 261          * Test a PRF algorithm.
 262          *
 263          * @param alg                   algorithm to test
 264          * @param create                constructor function for the PRF
 265          * @param speed                 speed test result, NULL to omit
 266          * @return                              TRUE if test passed
 267          */
 268         bool (*test_prf)(crypto_tester_t *this, pseudo_random_function_t alg,
 269                                          prf_constructor_t create,
 270                                          u_int *speed, const char *plugin_name);
 271         /**
 272          * Test an XOF algorithm.
 273          *
 274          * @param alg                   algorithm to test
 275          * @param create                constructor function for the XOF
 276          * @param speed                 speed test result, NULL to omit
 277          * @return                              TRUE if test passed
 278          */
 279         bool (*test_xof)(crypto_tester_t *this, ext_out_function_t alg,
 280                                          xof_constructor_t create,
 281                                          u_int *speed, const char *plugin_name);
 282         /**
 283          * Test a KDF algorithm.
 284          *
 285          * If constructor arguments are passed, only matching test vectors are
 286          * tried. Otherwise, all are tried and implementations are allowed to fail
 287          * construction with unsupported arguments.
 288          *
 289          * @param alg                   algorithm to test
 290          * @param create                constructor function for the XOF
 291          * @param args                  optional arguments to pass to constructor
 292          * @param speed                 speed test result, NULL to omit
 293          * @return                              TRUE if test passed
 294          */
 295         bool (*test_kdf)(crypto_tester_t *this, key_derivation_function_t alg,
 296                                          kdf_constructor_t create, kdf_test_args_t *args,
 297                                          u_int *speed, const char *plugin_name);
 298         /**
 299          * Test a DRBG type.
 300          *
 301          * @param type                  DRBG type to test
 302          * @param create                constructor function for the DRBG
 303          * @param speed                 speed test result, NULL to omit
 304          * @return                              TRUE if test passed
 305          */
 306         bool (*test_drbg)(crypto_tester_t *this, drbg_type_t type,
 307                                           drbg_constructor_t create,
 308                                           u_int *speed, const char *plugin_name);
 309         /**
 310          * Test a RNG implementation.
 311          *
 312          * @param alg                   algorithm to test
 313          * @param create                constructor function for the RNG
 314          * @param speed                 speed test result, NULL to omit
 315          * @return                              TRUE if test passed
 316          */
 317         bool (*test_rng)(crypto_tester_t *this, rng_quality_t quality,
 318                                          rng_constructor_t create,
 319                                          u_int *speed, const char *plugin_name);
 320         /**
 321          * Test a key exchange implementation.
 322          *
 323          * @param ke                    key exchange method to test
 324          * @param create                constructor function for the key exchange method
 325          * @param speed                 speed test result, NULL to omit
 326          * @return                              TRUE if test passed
 327          */
 328         bool (*test_ke)(crypto_tester_t *this, key_exchange_method_t ke,
 329                                         ke_constructor_t create,
 330                                         u_int *speed, const char *plugin_name);
 331
 332         /**
 333          * Add a test vector to test a crypter.
 334          *
 335          * @param vector                pointer to test vector
 336          */
 337         void (*add_crypter_vector)(crypto_tester_t *this,
 338                                                            crypter_test_vector_t *vector);
 339         /**
 340          * Add a test vector to test an aead transform.
 341          *
 342          * @param vector                pointer to test vector
 343          */
 344         void (*add_aead_vector)(crypto_tester_t *this,
 345                                                         aead_test_vector_t *vector);
 346         /**
 347          * Add a test vector to test a signer.
 348          *
 349          * @param vector                pointer to test vector
 350          */
 351         void (*add_signer_vector)(crypto_tester_t *this,
 352                                                           signer_test_vector_t *vector);
 353         /**
 354          * Add a test vector to test a hasher.
 355          *
 356          * @param vector                pointer to test vector
 357          */
 358         void (*add_hasher_vector)(crypto_tester_t *this,
 359                                                           hasher_test_vector_t *vector);
 360         /**
 361          * Add a test vector to test a PRF.
 362          *
 363          * @param vector                pointer to test vector
 364          */
 365         void (*add_prf_vector)(crypto_tester_t *this, prf_test_vector_t *vector);
 366
 367         /**
 368          * Add a test vector to test an XOF.
 369          *
 370          * @param vector                pointer to test vector
 371          */
 372         void (*add_xof_vector)(crypto_tester_t *this, xof_test_vector_t *vector);
 373
 374         /**
 375          * Add a test vector to test a KDF.
 376          *
 377          * @param vector                pointer to test vector
 378          */
 379         void (*add_kdf_vector)(crypto_tester_t *this, kdf_test_vector_t *vector);
 380
 381         /**
 382          * Add a test vector to test a DRBG.
 383          *
 384          * @param vector                pointer to test vector
 385          */
 386         void (*add_drbg_vector)(crypto_tester_t *this, drbg_test_vector_t *vector);
 387
 388         /**
 389          * Add a test vector to test a RNG.
 390          *
 391          * @param vector                pointer to test vector
 392          */
 393         void (*add_rng_vector)(crypto_tester_t *this, rng_test_vector_t *vector);
 394
 395         /**
 396          * Add a test vector to test a Diffie-Hellman backend.
 397          *
 398          * @param vector                pointer to test vector
 399          */
 400         void (*add_ke_vector)(crypto_tester_t *this, ke_test_vector_t *vector);
 401
 402         /**
 403          * Destroy a crypto_tester_t.
 404          */
 405         void (*destroy)(crypto_tester_t *this);
 406 };
 407
 408 /**
 409  * Create a crypto_tester instance.
 410  */
 411 crypto_tester_t *crypto_tester_create();
 412
 413 #endif /** CRYPTO_TESTER_H_ @}*/