1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>skalibs: the random library interface</title
<meta name="Description" content="skalibs: the random library interface" />
<meta name="Keywords" content="skalibs library random librandom random.h" />
<!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="../libskarnet.html">libskarnet</a><br />
<a href="../index.html">skalibs</a><br />
<a href="http://skarnet.org/software/">Software</a><br />
<a href="http://skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>random</tt> library interface </h1>
<p>
<tt>librandom</tt> is a small library designed to provide an
interface to some reasonable-quality pseudorandom number
generation. Some libcs have a bad
<tt>random()</tt> implementation; <tt>librandom</tt> is designed
to use system pseudorandom number generation when it's provided
via <tt>/dev/random</tt> and <tt>/dev/urandom</tt>, and to use
a good default PRNG otherwise.
</p>
<p>
<tt>librandom</tt> also supports
<a href="http://egd.sourceforge.net/">EGD</a>. If you have built
skalibs with <tt>--enable-egd</tt>, 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 <tt>/dev/random</tt>.
If the EGD connection fails, a SURF PRNG is used.
</p>
<h2> Compiling </h2>
<ul>
<li> Use <tt>#include <skalibs/random.h></tt> </li>
</ul>
<h2> Programming </h2>
<p>
You should refer to the <tt>skalibs/random.h</tt> header for the exact
function prototypes.
</p>
<h3> Basic functions </h3>
<pre>
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() ;
</pre>
<p>
<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
are done using it, by calling <tt>random_finish()</tt> - unless your
process exits right away.
</p>
<ul>
<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>
<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>
<p>
<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>
<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>
|
