lib/silccrypt/silcrng.h

   1 /*
   2
   3   silcrng.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silccrypt/SILC RNG Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * SILC Random Number Generator is cryptographically strong pseudo random
  25  * number generator. It is used to generate all the random numbers needed
  26  * in the SILC sessions. All key material and other sources needing random
  27  * numbers use this generator.
  28  *
  29  * The interface provides functions for retrieving different size of
  30  * random number and arbitrary length of random data buffers. The interface
  31  * also defines Global RNG API which makes it possible to call any
  32  * RNG API function without specific RNG context.
  33  *
  34  ***/
  35
  36 #ifndef SILCRNG_H
  37 #define SILCRNG_H
  38
  39 /****s* silccrypt/SilcRNGAPI/SilcRng
  40  *
  41  * NAME
  42  *
  43  *    typedef struct SilcRngStruct *SilcRng;
  44  *
  45  * DESCRIPTION
  46  *
  47  *    This context is the actual Random Number Generator and is allocated
  48  *    by silc_rng_alloc and given as argument usually to all silc_rng_*
  49  *    functions.  It is freed by the silc_rng_free function.  The RNG is
  50  *    initialized by calling the silc_rng_init function.
  51  *
  52  ***/
  53 typedef struct SilcRngStruct *SilcRng;
  54
  55 /* Prototypes */
  56
  57 /****f* silccrypt/SilcRNGAPI/silc_rng_alloc
  58  *
  59  * SYNOPSIS
  60  *
  61  *    SilcRng silc_rng_alloc(void);
  62  *
  63  * DESCRIPTION
  64  *
  65  *    Allocates new SILC random number generator and returns context to
  66  *    it.  After the RNG is allocated it must be initialized by calling
  67  *    silc_rng_init before it actually can be used to produce any random
  68  *    number.  This function returns NULL if RNG could not allocated.
  69  *
  70  ***/
  71 SilcRng silc_rng_alloc(void);
  72
  73 /****f* silccrypt/SilcRNGAPI/silc_rng_free
  74  *
  75  * SYNOPSIS
  76  *
  77  *    void silc_rng_free(SilcRng rng);
  78  *
  79  * DESCRIPTION
  80  *
  81  *    Frees the random number generator and destroys the random number
  82  *    pool.
  83  *
  84  ***/
  85 void silc_rng_free(SilcRng rng);
  86
  87 /****f* silccrypt/SilcRNGAPI/silc_rng_init
  88  *
  89  * SYNOPSIS
  90  *
  91  *    void silc_rng_init(SilcRng rng);
  92  *
  93  * DESCRIPTION
  94  *
  95  *    This function is used to initialize the random number generator.
  96  *    This is the function that must be called after the RNG is allocated
  97  *    by calling silc_rng_alloc.  RNG cannot be used before this function
  98  *    is called.
  99  *
 100  * NOTES
 101  *
 102  *    This function may be slow since it will acquire secret noise from
 103  *    the environment in an attempt to set the RNG in unguessable state.
 104  *
 105  ***/
 106 void silc_rng_init(SilcRng rng);
 107
 108 /****f* silccrypt/SilcRNGAPI/silc_rng_get_byte
 109  *
 110  * SYNOPSIS
 111  *
 112  *    SilcUInt8 silc_rng_get_byte(SilcRng rng);
 113  *
 114  * DESCRIPTION
 115  *
 116  *    Returns one 8-bit random byte from the random number generator.
 117  *
 118  ***/
 119 SilcUInt8 silc_rng_get_byte(SilcRng rng);
 120
 121 /****f* silccrypt/SilcRNGAPI/silc_rng_get_byte_fast
 122  *
 123  * SYNOPSIS
 124  *
 125  *    SilcUInt8 silc_rng_get_byte_fast(SilcRng rng);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Returns one 8-bit random byte from the random number generator as
 130  *    fast as possible.
 131  *
 132  * NOTES
 133  *
 134  *    This will read the data from /dev/urandom if it is available in the
 135  *    operating system, since this may be faster than retrieving a byte
 136  *    from the SILC RNG.  If /dev/urandom is not available this will take
 137  *    the byte from SILC RNG and is effectively same as silc_rng_get_byte.
 138  *
 139  ***/
 140 SilcUInt8 silc_rng_get_byte_fast(SilcRng rng);
 141
 142 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn16
 143  *
 144  * SYNOPSIS
 145  *
 146  *    SilcUInt16 silc_rng_get_rn16(SilcRng rng);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Returns one 16-bit random number from the random number generator.
 151  *
 152  ***/
 153 SilcUInt16 silc_rng_get_rn16(SilcRng rng);
 154
 155 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn32
 156  *
 157  * SYNOPSIS
 158  *
 159  *    SilcUInt32 silc_rng_get_rn32(SilcRng rng);
 160  *
 161  * DESCRIPTION
 162  *
 163  *    Returns one 32-bit random number from the random number generator.
 164  *
 165  ***/
 166 SilcUInt32 silc_rng_get_rn32(SilcRng rng);
 167
 168 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_string
 169  *
 170  * SYNOPSIS
 171  *
 172  *    unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len);
 173  *
 174  * DESCRIPTION
 175  *
 176  *    Returns random string in HEX form of the length of `len' bytes.
 177  *    The caller must free returned data buffer.  It is guaranteed the
 178  *    data string goes not include any zero (0x00) bytes.
 179  *
 180  ***/
 181 unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len);
 182
 183 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_data
 184  *
 185  * SYNOPSIS
 186  *
 187  *    SilcBool silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len,
 188  *                                  unsigned char *buf, SilcUInt32 buf_size);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    Returns random binary data of the length of `len' bytes to the `buf'
 193  *    of maximum size of `buf_size'.  It is guaranteed the data buffer does
 194  *    not include any zero (0x00) bytes.
 195  *
 196  ***/
 197 SilcBool silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len,
 198                               unsigned char *buf, SilcUInt32 buf_size);
 199
 200 /****f* silccrypt/SilcRNGAPI/silc_rng_add_noise
 201  *
 202  * SYNOPSIS
 203  *
 204  *    void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len);
 205  *
 206  * DESCRIPTION
 207  *
 208  *    Add the data buffer indicated by `buffer' of length of `len' bytes
 209  *    as noise to the random number generator.  The random number generator
 210  *    is restirred (reseeded) when this function is called.
 211  *
 212  ***/
 213 void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len);
 214
 215 /****f* silccrypt/SilcRNGAPI/silc_rng_global_init
 216  *
 217  * SYNOPSIS
 218  *
 219  *    SilcBool silc_rng_global_init(SilcRng rng);
 220  *
 221  * DESCRIPTION
 222  *
 223  *    This function sets the `rng' if non-NULL as global RNG context.
 224  *    When any of the silc_rng_global_* functions is called the `rng' is
 225  *    used as RNG.  If `rng' is NULL this will allocate new RNG as global
 226  *    RNG.  The application in this case must free it later by calling
 227  *    silc_rng_global_uninit.  Returns TRUE after Global RNG is initialized.
 228  *
 229  * NOTES
 230  *
 231  *    If `rng' was non-NULL, the silc_rng_init must have been called for
 232  *    the `rng' already.
 233  *
 234  *    This function can be used to define the `rng' as global RNG and then
 235  *    use silc_rng_global_* functions easily without need to provide
 236  *    the RNG as argument.
 237  *
 238  ***/
 239 SilcBool silc_rng_global_init(SilcRng rng);
 240
 241 /****f* silccrypt/SilcRNGAPI/silc_rng_global_uninit
 242  *
 243  * SYNOPSIS
 244  *
 245  *    SilcBool silc_rng_global_uninit(void);
 246  *
 247  * DESCRIPTION
 248  *
 249  *    Uninitialized the Global RNG object and frees it.  This should not
 250  *    be called if silc_rng_global_init was called with non-NULL RNG.
 251  *
 252  ***/
 253 SilcBool silc_rng_global_uninit(void);
 254
 255 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte
 256  *
 257  * SYNOPSIS
 258  *
 259  *    SilcUInt8 silc_rng_global_get_byte(void);
 260  *
 261  * DESCRIPTION
 262  *
 263  *    Returns one 8-bit random byte from the random number generator.
 264  *
 265  ***/
 266 SilcUInt8 silc_rng_global_get_byte(void);
 267
 268 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte_fast
 269  *
 270  * SYNOPSIS
 271  *
 272  *    SilcUInt8 silc_rng_global_get_byte_fast(void);
 273  *
 274  * DESCRIPTION
 275  *
 276  *    Returns one 8-bit random byte from the random number generator as
 277  *    fast as possible.
 278  *
 279  * NOTES
 280  *
 281  *    This will read the data from /dev/urandom if it is available in the
 282  *    operating system, since this may be faster than retrieving a byte
 283  *    from the SILC RNG.  If /dev/urandom is not available this will take
 284  *    the byte from SILC RNG and is effectively same as silc_rng_get_byte.
 285  *
 286  ***/
 287 SilcUInt8 silc_rng_global_get_byte_fast(void);
 288
 289 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn16
 290  *
 291  * SYNOPSIS
 292  *
 293  *    SilcUInt16 silc_rng_global_get_rn16(void);
 294  *
 295  * DESCRIPTION
 296  *
 297  *    Returns one 16-bit random number from the random number generator.
 298  *
 299  ***/
 300 SilcUInt16 silc_rng_global_get_rn16(void);
 301
 302 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn32
 303  *
 304  * SYNOPSIS
 305  *
 306  *    SilcUInt32 silc_rng_global_get_rn32(void);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Returns one 32-bit random number from the random number generator.
 311  *
 312  ***/
 313 SilcUInt32 silc_rng_global_get_rn32(void);
 314
 315 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_string
 316  *
 317  * SYNOPSIS
 318  *
 319  *    unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len);
 320  *
 321  * DESCRIPTION
 322  *
 323  *    Returns random string in HEX form of the length of `len' bytes.
 324  *    The caller must free returned data buffer.  It is guaranteed the
 325  *    data string goes not include any zero (0x00) bytes.
 326  *
 327  ***/
 328 unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len);
 329
 330 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_data
 331  *
 332  * SYNOPSIS
 333  *
 334  *    SilcBool silc_rng_global_get_rn_data(SilcRng rng, SilcUInt32 len,
 335  *                                         unsigned char *buf,
 336  *                                         SilcUInt32 buf_size);
 337  *
 338  * DESCRIPTION
 339  *
 340  *    Returns random binary data of the length of `len' bytes to the `buf'
 341  *    of maximum size of `buf_size'.  It is guaranteed the data buffer does
 342  *    not include any zero (0x00) bytes.
 343  *
 344  ***/
 345 SilcBool silc_rng_global_get_rn_data(SilcRng rng, SilcUInt32 len,
 346                                      unsigned char *buf, SilcUInt32 buf_size);
 347
 348 /****f* silccrypt/SilcRNGAPI/silc_rng_global_add_noise
 349  *
 350  * SYNOPSIS
 351  *
 352  *    void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len);
 353  *
 354  * DESCRIPTION
 355  *
 356  *    Add the data buffer indicated by `buffer' of length of `len' bytes
 357  *    as noise to the random number generator.  The random number generator
 358  *    is restirred (reseeded) when this function is called.
 359  *
 360  ***/
 361
 362 void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len);
 363
 364 #endif