-r--r--r-- 5860 librandombytes-20230126/doc/html/index.html raw
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style type="text/css">
html{overflow-y:scroll}
body{font-family:sans-serif}
p,ul,ol,blockquote,pre{font-size:1.0em;line-height:1.6em}
li p{font-size:1.0em}
blockquote p{font-size:1.0em}
tt{font-size:1.3em}
code{font-size:1.3em}
h1{font-size:1.5em}
h2{font-size:1.3em}
h3{font-size:1.0em}
h1 a{text-decoration:none}
table{border-collapse:collapse}
th,td{border:1px solid black}
table a{text-decoration:none}
table tr{font-size:1.0em;line-height:1.6em}
.links a:hover{text-decoration:underline}
.links a:active{text-decoration:underline}
.links img{width:200px;padding-left:1em}
.links td{border:0px;padding-top:0.5em;padding-bottom:0.5em}
.headline{padding:0;font-weight:bold;font-size:1.5em;vertical-align:top;padding-bottom:0.5em;color:#2f8a59}
.navt{display:inline-block;box-sizing:border-box;-moz-box-sizing:border-box;-webkit-box-sizing:border-box;
min-width:14%;margin:0;padding:0;padding-left:0.5em;padding-right:0.5em;vertical-align:center;
font-weight:bold;font-size:1.1em;text-align:center;border:1px solid black}
.here{border-bottom:0px;background-color:#ffffff}
.away{background-color:#2f8a59;}
.away a{text-decoration:none;display:block;color:#ffffff}
.away a:hover,.away a:active{text-decoration:underline}
.main{margin:0;padding-top:0em;padding-bottom:1%;clear:both}
</style>
<title>
Intro</title>
</head>
<body>
<div class=headline>
librandombytes
</div>
<div class=nav>
<div class="navt here">Intro
</div><div class="navt away"><a href=download.html>Download</a>
</div><div class="navt away"><a href=install.html>Install</a>
</div><div class="navt away"><a href=api.html>API</a>
</div><div class="navt away"><a href=security.html>Security</a>
</div></div>
<div class=main>
<p>librandombytes is a public-domain library providing a simple API for
applications generating fresh randomness: include <code><randombytes.h></code>,
call <code>randombytes(x,xbytes)</code> whenever desired to generate fresh random
bytes <code>x[0]</code>, <code>x[1]</code>, ..., <code>x[xbytes-1]</code>, and link with <code>-lrandombytes</code>.</p>
<p>Random bytes are often used directly in applications. Random bytes are
also the foundation of more complicated random objects, such as random
integers in a limited interval, random floating-point numbers from a
(nearly) normal distribution, and random keys used in public-key
cryptosystems. librandombytes is dedicated to obtaining fresh random
bytes in the first place, and leaves it to higher-level libraries to
convert those bytes into other types of random objects.</p>
<p>librandombytes aims for the following stringent randomness goal: no
feasible computation will ever be able to tell the difference between
the output bytes and true randomness (independent uniformly distributed
random bytes). This makes the <code>randombytes()</code> output suitable for use
in applications ranging from simulations to cryptography.</p>
<p>Most alternative sources of randomness (such as <code>rand()</code> and <code>random()</code>
in C, and <code>mt19937_64</code> in C++) consider detectable deviations from true
randomness to be acceptable as long as <em>most</em> applications do not notice
the deviations. These sources are not permitted inside librandombytes;
the <code>randombytes()</code> caller is entitled to expect that the output comes
from sources that are designed for the right goal.</p>
<p>Internally, librandombytes is an abstraction layer for a choice of two
libraries, where each library provides the same <code>randombytes</code> interface
but the libraries choose two different sources of randomness:</p>
<ul>
<li>
<p><code>librandombytes-kernel</code> reads random bytes provided by the OS kernel
via mechanisms such as <code>getrandom()</code>. These mechanisms are typically
advertised as providing RNG security features that are harder to
provide in user space, such as hypervisor integration.</p>
</li>
<li>
<p><code>librandombytes-openssl</code> uses OpenSSL's <code>RAND_bytes</code> to generate
random bytes. This mechanism is typically advertised as providing
speed that is difficult to achieve without a per-process RNG.</p>
</li>
</ul>
<p>The idea is that the OS can install <code>librandombytes-kernel</code> by default,
but the sysadmin can install <code>librandombytes-openssl</code> to transparently
switch all of the <code>randombytes()</code> applications to <code>RAND_bytes</code> (for
example, via Debian's <code>/etc/alternatives</code> mechanism) <em>if</em> profiling
shows that this switch is important for overall system performance.</p>
<p>Making this choice centrally means that applications are free to simply
call <code>randombytes()</code></p>
<ul>
<li>
<p>without worrying about evaluating performance,</p>
</li>
<li>
<p>without worrying about how to balance performance concerns with
competing concerns, and</p>
</li>
<li>
<p>without worrying that these performance evaluations will be rendered
obsolete by speed improvements: for example, by
<a href="https://lkml.org/lkml/2023/1/1/87">ongoing work</a> to accelerate
<code>getrandom()</code>, or by the increasing deployment of
<a href="https://blog.cr.yp.to/20170723-random.html">fast-key-erasure RNGs</a>.</p>
</li>
</ul>
<p>Another virtue of having a <code>randombytes()</code> abstraction layer is that
test frameworks can substitute a deterministic seeded <code>randombytes()</code>
providing <em>known</em> pseudorandom bytes for reproducible tests. Of course,
the <code>randombytes()</code> provided by these test frameworks must be kept
separate from the fresh <code>randombytes()</code> used for deployment.</p><hr><font size=1><b>Version:</b>
This is version 2023.01.15 of the "Intro" web page.
</font>
</div>
</body>
</html>