skalibs: the random library interface
Keywords: skalibs library random librandom random.h

libskarnet
skalibs
Software
skarnet.org

# 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.

### High quality, cryptographically strong random data

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

      goodrandom_init() ;
      c = goodrandom_char() ;
      n = goodrandom_int(max) ;
      r = goodrandom_string(data, b) ;
      goodrandom_finish() ;

`goodrandom_init()` becomes optional with skalibs-0.43. It is recommended that you let the library perform cleanups after you have used it, by calling `goodrandom_finish()`.

- `goodrandom_char()` returns a random character
- `goodrandom_int(max)` returns a random integer between 0 and max-1
- `goodrandom_string(data, b)` puts b random bytes in data, which must be preallocated. It returns b if it succeeds, or a non-negative integer lesser than b if it fails for any reason.

If you have neither `/dev/random` nor EGD, a software PRNG is used. This PRNG is based on the SURF function, which is unpredictable enough for most uses.

### Lower quality random data

It works basically the same, by replacing `goodrandom_*` with `badrandom_*`. It uses `/dev/urandom` on systems that support it; on systems that do not, but support EGD, non-blocking calls to EGD are made ; if that is not enough, or EGD is not supported, the SURF generator is used.

The point of `badrandom` is to get random bytes instantly, even at the expense of quality; whereas `goodrandom` always returns high-quality random bytes, but may block if entropy is insufficient. In practice, in spite of its name, `badrandom` will return quite unpredictable pseudo-random data, so `goodrandom` should be used only when paranoia is the rule and blocking is an option.