The `random` library interface

librandom is a small library designed to provide an interface to some reasonable-quality pseudorandom number generation. Some libcs have a bad random() implementation; librandom is designed to use system pseudorandom number generation when it's provided via /dev/random and /dev/urandom, and to use a good default PRNG otherwise.

librandom also supports EGD. If you have built skalibs with --enable-egd, then the librandom primitives will try and connect to an EGD service to get random bytes if there is no kernel-based entropy generator such as /dev/random. If the EGD connection fails, a SURF PRNG is used.

Compiling

Use #include <skalibs/random.h>

Programming

You should refer to the skalibs/random.h header for the exact function prototypes.

Basic functions

  unsigned char c ;
  uint32_t max ;
  uint32_t n ;
  unsigned int b ;
  char data[at least b] ;
  int r ;

  r = random_init() ;
  c = random_char() ;
  n = random_uint32(max) ;
  random_string(data, b) ;
  random_finish() ;

random_init() must be called before any other function in the random library. It returns 0 (and sets errno) on failure, and nonzero on success.

It is recommended that you let the library perform cleanups after you are done using it, by calling random_finish() - unless your process exits right away.

random_char() returns a random character.
random_uint32(max) returns a random integer between 0 and max-1.
random_string(data, b) fills b bytes in data (which must be preallocated) with random data.

Advanced functions

void random_unsort (char *s, unsigned int n, unsigned int chunksize)
Shuffles the array s (of size at least n*chunksize) by performing a random permutation of the n blocks of chunksize bytes. Bytes are not permuted inside chunks.

void random_name (char *s, unsigned int n)
Writes n random readable ASCII characters into s: letters, numbers, hyphens or underscores. Does not terminate with a null character.

int random_sauniquename (stralloc *sa, unsigned int n)
Appends a (non-null-terminated) unique, unpredictable ASCII name to the stralloc *sa. That name includes n randomly generated ASCII characters.

Notes

The random library is a thin wrapper around the best available random generator provided by the underlying system. By decreasing order of preference, it will use the following implementations if available:
- arc4random()
- getrandom()
- /dev/urandom
- a basic SURF pseudo-random generator
The random_init() function tries to automatically add some reasonably random data to the underlying random generator's entropy pool. However, that pseudorandom data is not 100% unpredictable, so it will not replace proper seeding of the random generator at boot time.