summaryrefslogtreecommitdiff
path: root/doc/librandom
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2016-10-14 17:07:56 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2016-10-14 17:07:56 +0000
commita1933bd1847951b959016f59ee744d1b18a00142 (patch)
tree42392f2df048defd712fa12d290bf84a7a77df6d /doc/librandom
parenteaf9404b22bba7be5092672144b867380c602beb (diff)
downloadskalibs-a1933bd1847951b959016f59ee744d1b18a00142.tar.xz
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.
Diffstat (limited to 'doc/librandom')
-rw-r--r--doc/librandom/index.html89
1 files changed, 55 insertions, 34 deletions
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.
</p>
- <h3> High quality, cryptographically strong random data </h3>
+<h3> Basic functions </h3>
<pre>
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() ;
</pre>
<p>
- <tt>goodrandom_init()</tt> becomes optional with skalibs-0.43.
+ <tt>random_init()</tt> must be called before any other function in
+the random library. It returns 0 (and sets errno) on failure, and
+nonzero on success.
+</p>
+
+<p>
It is recommended that you let the library perform cleanups after you
-have used it, by calling <tt>goodrandom_finish()</tt>.
+are done using it, by calling <tt>random_finish()</tt> - unless your
+process exits right away.
</p>
<ul>
- <li> <tt>goodrandom_char()</tt> returns a random character </li>
- <li> <tt>goodrandom_int(<em>max</em>)</tt> returns a random integer
-between 0 and <em>max</em>-1 </li>
- <li> <tt>goodrandom_string(<em>data</em>, <em>b</em>)</tt> puts
-<em>b</em> random bytes in <em>data</em>, which must be preallocated.
-It returns <em>b</em> if it succeeds, or a non-negative integer lesser
-than <em>b</em> if it fails for any reason. </li>
+ <li> <tt>random_char()</tt> returns a random character. </li>
+ <li> <tt>random_uint32(<em>max</em>)</tt> returns a random integer
+between 0 and <em>max</em>-1. </li>
+ <li> <tt>random_string(<em>data</em>, <em>b</em>)</tt> fills
+<em>b</em> bytes in <em>data</em> (which must be preallocated)
+with random data. </li>
</ul>
+<h3> Advanced functions </h3>
+
<p>
- If you have neither <tt>/dev/random</tt> nor EGD, a software PRNG is
-used. This PRNG is based on the
-<a href="http://cr.yp.to/antiforgery.html#surf">SURF</a> function, which
-is unpredictable enough for most uses.
+<code> void random_unsort (char *s, unsigned int n, unsigned int chunksize) </code> <br />
+Shuffles the array <em>s</em> (of size at least <em>n</em>*<em>chunksize</em>) by
+performing a random permutation of the <em>n</em> blocks of <em>chunksize</em> bytes.
+Bytes are not permuted inside chunks.
</p>
- <h3> Lower quality random data </h3>
-
<p>
- It works basically the same, by replacing <tt>goodrandom_*</tt> with
-<tt>badrandom_*</tt>. It uses <tt>/dev/urandom</tt> 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.
+<code> void random_name (char *s, unsigned int n) </code> <br />
+Writes <em>n</em> random readable ASCII characters into <em>s</em>:
+letters, numbers, hyphens or underscores. Does not terminate with a
+null character.
</p>
<p>
- The point of <tt>badrandom</tt> is to get random bytes <em>instantly</em>,
-even at the expense of quality; whereas <tt>goodrandom</tt> always returns
-high-quality random bytes, but may block if entropy is insufficient. In
-practice, in spite of its name, <tt>badrandom</tt> will return quite
-unpredictable pseudo-random data, so <tt>goodrandom</tt> should be used
-only when paranoia is the rule and blocking is an option.
+<code> int random_sauniquename (stralloc *sa, unsigned int n) </code> <br />
+Appends a (non-null-terminated) unique, unpredictable ASCII name to the
+<a href="../libstddjb/stralloc.html">stralloc</a> <em>*sa</em>. That
+name includes <em>n</em> randomly generated ASCII characters.
</p>
+<h2> Notes </h2>
+
+<ul>
+ <li> The <tt>random</tt> 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:
+ <ul>
+ <li> <a href="http://man.openbsd.org/arc4random.3">arc4random()</a> </li>
+ <li> <a href="http://man7.org/linux/man-pages/man2/getrandom.2.html">getrandom()</a> </li>
+ <li> <tt>/dev/urandom</tt> </li>
+ <li> a basic <a href="https://cr.yp.to/papers/surf.pdf">SURF</a> pseudo-random generator</li>
+ </ul> </li>
+ <li> The <tt>random_init()</tt> 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. </li>
+</ul>
+
</body>
</html>