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 typedef struct randomizer_t randomizer_t;
  29
  30 /**
  31  * @brief Class used to get random and pseudo random values.
  32  *
  33  * This class is thread save as file system read calls are thread save.
  34  *
  35  * @ingroup utils
  36  */
  37 struct randomizer_t {
  38
  39         /**
  40          * @brief Reads a specific number of bytes from random device.
  41          *
  42          * @param this                                  calling randomizer_t object
  43          * @param bytes                                 number of bytes to read
  44          * @param[out] buffer                   pointer to buffer where to write the data in.
  45          *                                                              Size of buffer has to be at least bytes.
  46          * @return
  47          *                                                              - SUCCESS
  48          *                                                              - FAILED if random device could not be opened
  49          */
  50         status_t (*get_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
  51
  52         /**
  53          * @brief Allocates space and writes in random bytes.
  54          *
  55          * @param this                                  calling randomizer_t object
  56          * @param bytes                                 number of bytes to allocate
  57          * @param[out] chunk                            chunk which will hold the allocated random bytes
  58          * @return
  59          *                                                              - SUCCESS
  60          *                                                              - OUT_OF_RES
  61          *                                                              - FAILED if random device could not be opened
  62          */
  63         status_t (*allocate_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
  64
  65         /**
  66          * @brief Reads a specific number of bytes from pseudo random device.
  67          *
  68          * @param this                                  calling randomizer_t object
  69          * @param bytes                                 number of bytes to read
  70          * @param[out] buffer                   pointer to buffer where to write the data in.
  71          *                                                              size of buffer has to be at least bytes.
  72          * @return
  73          *                                                              - SUCCESS
  74          *                                                              - FAILED if random device could not be opened
  75          */
  76         status_t (*get_pseudo_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
  77
  78         /**
  79          * @brief Allocates space and writes in pseudo random bytes.
  80          *
  81          * @param this                                  calling randomizer_t object
  82          * @param bytes                                 number of bytes to allocate
  83          * @param[out] chunk                            chunk which will hold the allocated random bytes
  84          * @return
  85          *                                                              - SUCCESS
  86          *                                                              - OUT_OF_RES
  87          *                                                              - FAILED if random device could not be opened
  88          */
  89         status_t (*allocate_pseudo_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
  90
  91         /**
  92          * @brief Destroys a randomizer_t object.
  93          *
  94          * @param this  randomizer_t object to destroy
  95          * @return              SUCCESS in any case
  96          */
  97         status_t (*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
 117  *                                                      - created randomizer_t
 118  *                                                      - NULL if out of ressources
 119  *
 120  * @ingroup utils
 121  */
 122 randomizer_t *randomizer_create_on_devices(char * random_dev_name,char * prandom_dev_name);
 123
 124 #endif /*RANDOMIZER_H_*/