Source/charon/utils/randomizer.h

   1 /**
   2  * @file randomizer.h
   3  *
   4  * @brief Class used to get random and pseudo random values
   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  * Object representing an randomizer
  30  *
  31  * This class is thread save as file system read calls are thread save...
  32  */
  33 typedef struct randomizer_s randomizer_t;
  34
  35 struct randomizer_s {
  36
  37         /**
  38          * @brief Reads a specific number of bytes from random device.
  39          *
  40          * @param this                                  calling randomizer_t object
  41          * @param bytes                                 Number of bytes to read
  42          * @param[out] buffer                   Pointer to buffer where to write the data in.
  43          *                                                              Size of buffer has to be at least bytes.
  44          * @return
  45          *                                                              - SUCCESS
  46          *                                                              - FAILED
  47          */
  48         status_t (*get_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
  49
  50         /**
  51          * @brief Allocates space and writes in random bytes
  52          *
  53          * @param this                                  calling randomizer_t object
  54          * @param bytes                                 Number of bytes to allocate
  55          * @param[out] chunk                    chunk which will hold the allocated random bytes
  56          * @return
  57          *                                                              - SUCCESS
  58          *                                                              - OUT_OF_RES
  59          *                                                              - FAILED
  60          */
  61         status_t (*allocate_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
  62
  63         /**
  64          * @brief Reads a specific number of bytes from pseudo random device.
  65          *
  66          * @param this                                  calling randomizer_t object
  67          * @param bytes                                 Number of bytes to read
  68          * @param[out] buffer                   Pointer to buffer where to write the data in.
  69          *                                                              Size of buffer has to be at least bytes.
  70          * @return
  71          *                                                              - SUCCESS
  72          *                                                              - FAILED
  73          */
  74         status_t (*get_pseudo_random_bytes) (randomizer_t *this,size_t bytes, u_int8_t *buffer);
  75
  76         /**
  77          * @brief Allocates space and writes in pseudo random bytes
  78          *
  79          * @param this                                  calling randomizer_t object
  80          * @param bytes                                 Number of bytes to allocate
  81          * @param[out] chunk                            chunk which will hold the allocated random bytes
  82          * @return
  83          *                                                              - SUCCESS
  84          *                                                              - OUT_OF_RES
  85          *                                                              - FAILED
  86          */
  87         status_t (*allocate_pseudo_random_bytes) (randomizer_t *this, size_t bytes, chunk_t *chunk);
  88
  89         /**
  90          * @brief Destroys a randomizer_t object.
  91          *
  92          * @param this  randomizer_t object to destroy
  93          * @return
  94          *                              SUCCESS in any case
  95          */
  96         status_t (*destroy) (randomizer_t *this);
  97 };
  98
  99 /**
 100  * @brief Create an randomizer_t object
 101  *
 102  * @return
 103  *                                      - created randomizer_t, or
 104  *                                      - NULL if failed
 105  */
 106 randomizer_t *randomizer_create();
 107
 108 /**
 109  * @brief Create an randomizer_t object with specific random device names
 110  *
 111  * @param random_dev_name       Device name for random values, etc /dev/random
 112  * @param prandom_dev_name      Device name for pseudo random values, etc /dev/urandom
 113  * @return
 114  *                                                      - created randomizer_t, or
 115  *                                                      - NULL if failed
 116  */
 117 randomizer_t *randomizer_create_on_devices(char * random_dev_name,char * prandom_dev_name);
 118
 119 #endif /*RANDOMIZER_H_*/