Source/charon/utils/randomizer.h

   1 /**
   2  * @file randomizer.h
   3  *
   4  * @brief Interface of randomizer_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2005 Jan Hutter, Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef RANDOMIZER_H_
  24 #define RANDOMIZER_H_
  25
  26 #include <types.h>
  27
  28
  29 /**
  30  * Default random device used when no device is given.
  31  */
  32 #define DEFAULT_RANDOM_DEVICE "/dev/random"
  33
  34 /**
  35  * Pseudo random device used when no device is given.
  36  */
  37 #define DEFAULT_PSEUDO_RANDOM_DEVICE "/dev/urandom"
  38
  39 typedef struct randomizer_t randomizer_t;
  40
  41 /**
  42  * @brief Class used to get random and pseudo random values.
  43  *
  44  * This class is thread save as file system read calls are thread save.
  45  *
  46  * @b Constructors:
  47  *  - randomizer_create()
  48  *  - randomizer_create_on_devices()
  49  *
  50  * @ingroup utils
  51  */
  52 struct randomizer_t {
  53
  54         /**
  55          * @brief Reads a specific number of bytes from random device.
  56          *
  57          * @param this                                  calling randomizer_t object
  58          * @param bytes                                 number of bytes to read
  59          * @param[out] buffer                   pointer to buffer where to write the data in.
  60          *                                                              Size of buffer has to be at least bytes.
  61          */
  62         void (*get_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
  63
  64         /**
  65          * @brief Allocates space and writes in random bytes.
  66          *
  67          * @param this                                  calling randomizer_t object
  68          * @param bytes                                 number of bytes to allocate
  69          * @param[out] chunk                    chunk which will hold the allocated random bytes
  70          */
  71         void (*allocate_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
  72
  73         /**
  74          * @brief Reads a specific number of bytes from pseudo random device.
  75          *
  76          * @param this                                  calling randomizer_t object
  77          * @param bytes                                 number of bytes to read
  78          * @param[out] buffer                   pointer to buffer where to write the data in.
  79          *                                                              size of buffer has to be at least bytes.
  80          */
  81         void (*get_pseudo_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
  82
  83         /**
  84          * @brief Allocates space and writes in pseudo random bytes.
  85          *
  86          * @param this                                  calling randomizer_t object
  87          * @param bytes                                 number of bytes to allocate
  88          * @param[out] chunk                            chunk which will hold the allocated random bytes
  89          */
  90         void (*allocate_pseudo_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
  91
  92         /**
  93          * @brief Destroys a randomizer_t object.
  94          *
  95          * @param this  randomizer_t object to destroy
  96          */
  97         void (*destroy) (randomizer_t *this);
  98 };
  99
 100 /**
 101  * @brief Creates a randomizer_t object
 102  *
 103  * @return
 104  *                                      - created randomizer_t, or
 105  *                                      - NULL if failed
 106  *
 107  * @ingroup utils
 108  */
 109 randomizer_t *randomizer_create();
 110
 111 /**
 112  * @brief Creates an randomizer_t object with specific random device names.
 113  *
 114  * @param random_dev_name       device name for random values, etc /dev/random
 115  * @param prandom_dev_name      device name for pseudo random values, etc /dev/urandom
 116  * @return                                      randomizer_t object
 117  *
 118  * @ingroup utils
 119  */
 120 randomizer_t *randomizer_create_on_devices(char * random_dev_name,char * prandom_dev_name);
 121
 122 #endif /*RANDOMIZER_H_*/