src/libstrongswan/crypto/rngs/rng.h

   1 /*
   2  * Copyright (C) 2012 Tobias Brunner
   3  * Copyright (C) 2008 Martin Willi
   4  * 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 rng rng
  19  * @{ @ingroup crypto
  20  */
  21
  22 #ifndef RNG_H_
  23 #define RNG_H_
  24
  25 typedef enum rng_quality_t rng_quality_t;
  26 typedef struct rng_t rng_t;
  27
  28 #include <library.h>
  29
  30 /**
  31  * Quality of generated random bytes.
  32  */
  33 enum rng_quality_t {
  34         /** weak randomness, usable for nonces, IVs */
  35         RNG_WEAK,
  36         /** stronger randomness, usable for session keys */
  37         RNG_STRONG,
  38         /** true random key material */
  39         RNG_TRUE,
  40 };
  41
  42 /**
  43  * enum name for rng_quality_t.
  44  */
  45 extern enum_name_t *rng_quality_names;
  46
  47 /**
  48  * Generic interface for random number generators.
  49  */
  50 struct rng_t {
  51
  52         /**
  53          * Generates random bytes and writes them in the buffer.
  54          *
  55          * @param len           number of bytes to get
  56          * @param buffer        pointer where the generated bytes will be written
  57          * @return                      TRUE if bytes successfully written
  58          */
  59         bool (*get_bytes)(rng_t *this, size_t len,
  60                                           u_int8_t *buffer) __attribute__((warn_unused_result));
  61
  62         /**
  63          * Generates random bytes and allocate space for them.
  64          *
  65          * @param len           number of bytes to get
  66          * @param chunk         chunk which will hold generated bytes
  67          * @return                      TRUE if allocation succeeded
  68          */
  69         bool (*allocate_bytes)(rng_t *this, size_t len,
  70                                                    chunk_t *chunk) __attribute__((warn_unused_result));
  71
  72         /**
  73          * Destroys a rng object.
  74          */
  75         void (*destroy)(rng_t *this);
  76 };
  77
  78 /**
  79  * Wrapper around rng_t.get_bytes() ensuring that either all bytes or at least
  80  * the first byte is not zero.
  81  *
  82  * @param rng                   rng_t object
  83  * @param len                   number of bytes to get
  84  * @param buffer                pointer where the generated bytes will be written
  85  * @param all                   TRUE if all bytes have to be non-zero, FALSE for first
  86  * @return                              TRUE if bytes successfully written
  87  */
  88 bool rng_get_bytes_not_zero(rng_t *rng, size_t len, u_int8_t *buffer,
  89                                                         bool all) __attribute__((warn_unused_result));
  90
  91 /**
  92  * Wrapper around rng_t.allocate_bytes() ensuring that either all bytes or at
  93  * least the first byte is not zero.
  94  *
  95  * @param rng                   rng_t object
  96  * @param len                   number of bytes to get
  97  * @param chunk                 chunk that stores the generated bytes (allocated)
  98  * @param all                   TRUE if all bytes have to be non-zero, FALSE for first
  99  * @return                              TRUE if bytes successfully written
 100  */
 101 bool rng_allocate_bytes_not_zero(rng_t *rng, size_t len, chunk_t *chunk,
 102                                                                  bool all) __attribute__((warn_unused_result));
 103
 104
 105
 106 #endif /** RNG_H_ @}*/