From a1933bd1847951b959016f59ee744d1b18a00142 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Fri, 14 Oct 2016 17:07:56 +0000 Subject: Clean up and modernize librandom. Correct random number generation has historically been suprisingly painful to achieve. There was no standard, every system behaved in a subtly different way, and there were a few userland initiatives to get decent randomness, all incompatible of course. The situation is a bit better now, we're heading towards some standardization. The arc4random() series of functions is a good API, and available on a lot of systems - unfortunately not Linux, but on Linux the new getrandom() makes using /dev/random obsolete. So I removed the old crap in librandom, dropped EGD support, dropped dynamic backend selection, made a single API series (random_* instead of goodrandom_* and badrandom_*), added an arc4random backend and a getrandom backend, and defaulted to /dev/urandom backed up by SURF in the worst case. This should be much smaller and logical. However, it's a major API break, so the skarnet.org stack will be changed to adapt. --- doc/librandom/index.html | 89 ++++++++++++++++++++++++++++++------------------ 1 file changed, 55 insertions(+), 34 deletions(-) (limited to 'doc') diff --git a/doc/librandom/index.html b/doc/librandom/index.html index 8001811..183086a 100644 --- a/doc/librandom/index.html +++ b/doc/librandom/index.html @@ -51,64 +51,85 @@ If the EGD connection fails, a SURF PRNG is used. function prototypes.

-

High quality, cryptographically strong random data

+

Basic functions 

   unsigned char c ;
-  unsigned int max ;
-  unsigned int n ;
+  uint32_t max ;
+  uint32_t 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() ;
+  r = random_init() ;
+  c = random_char() ;
+  n = random_uint32(max) ;
+  random_string(data, b) ;
+  random_finish() ;

- goodrandom_init() becomes optional with skalibs-0.43. + 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 -have used it, by calling goodrandom_finish(). +are done using it, by calling random_finish() - unless your +process exits right away.

+

Advanced functions

+

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

-

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

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

+ + + -- cgit v1.2.3