From 3534b428629be185e096be99e3bd5fdfe32d5544 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 18 Sep 2014 18:55:44 +0000 Subject: initial commit with rc for skalibs-2.0.0.0 --- doc/librandom/index.html | 113 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 doc/librandom/index.html (limited to 'doc/librandom') diff --git a/doc/librandom/index.html b/doc/librandom/index.html new file mode 100644 index 0000000..b721594 --- /dev/null +++ b/doc/librandom/index.html @@ -0,0 +1,113 @@ + + + + + skalibs: the random library interface + + + + + +

+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

+ + + +

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(). +

+ + + +

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

+ + + -- cgit v1.2.3