lib/silcutil/silcrand.h

   1 /*
   2
   3   silcrand.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2008 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* silcutil/Random Number Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Interface for generating pseudo-random numbers.  This random number
  25  * generator must not be used in applications needing cryptographically
  26  * strong random numbers.  For that purpose the SILC Crypto Toolkit should
  27  * be used.
  28  *
  29  * The implementation uses Mersenne Twister random number generator.
  30  *
  31  * The SILC Rand API is thread-safe.  Each thread can use the API at the
  32  * same time without affecting the random state of other threads.
  33  *
  34  * EXAMPLE
  35  *
  36  * silc_rand_seed(seed);
  37  * printf("Random number: %lu", silc_rand());
  38  *
  39  ***/
  40
  41 #ifndef SILCRAND_H
  42 #define SILCRAND_H
  43
  44 /****f* silcutil/silc_rand_seed
  45  *
  46  * SYNOPSIS
  47  *
  48  *    void silc_rand_seed(SilcUInt32 seed);
  49  *
  50  * DESCRIPTION
  51  *
  52  *    Seed the random number generator with the value `seed'.  This should
  53  *    be called before starting to retrieve random numbers and the `seed'
  54  *    itself should be random or non-determinable.  It is also wise to reseed
  55  *    the random number generator periodically if random numbers are used
  56  *    a lot.
  57  *
  58  ***/
  59 void silc_rand_seed(SilcUInt32 seed);
  60
  61 /****f* silcutil/silc_rand
  62  *
  63  * SYNOPSIS
  64  *
  65  *    SilcUInt32 silc_rand(void);
  66  *
  67  * DESCRIPTION
  68  *
  69  *    Returns 32-bit random number.
  70  *
  71  ***/
  72 SilcUInt32 silc_rand(void);
  73
  74 /****f* silcutil/silc_rand64
  75  *
  76  * SYNOPSIS
  77  *
  78  *    SilcUInt64 silc_rand64(void)
  79  *
  80  * DESCRIPTION
  81  *
  82  *    Returns 64-bit random number.
  83  *
  84  ***/
  85 SilcUInt64 silc_rand64(void);
  86
  87 #endif /* SILCRAND_H */