-r--r--r-- 6097 librandombytes-20230919/doc/html/api.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:"Noto Sans","Droid Sans","DejaVu Sans","Arial",sans-serif;line-height:1.5}
tt,code{background-color:#f0f0f0;font-family:"Noto Sans Mono","Droid Sans Mono","DejaVu Sans Mono","Courier New",monospace,sans-serif;font-size:1em;}
pre{margin-left:3em}
p,ul,ol,blockquote,pre{font-size:1.0em;line-height:1.6}
li p{font-size:1.0em}
blockquote p{font-size:1.0em}
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.6}
.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>
librandombytes: API</title>
</head>
<body>
<div class=headline>
librandombytes</div>
<div class=nav>
<div class="navt away"><a href=index.html>Intro</a>
</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 here">API
</div><div class="navt away"><a href=security.html>Security</a>
</div><div class="navt away"><a href=license.html>License</a>
</div></div>
<div class=main>
<h3>NAME</h3>
<p>randombytes - fill a buffer with random data</p>
<h3>SYNOPSIS</h3>
<pre><code>#include <randombytes.h>
unsigned char x[xbytes];
randombytes(x,xbytes);
</code></pre>
<p>Link with <code>-lrandombytes</code>.</p>
<h3>DESCRIPTION</h3>
<p><code>randombytes</code> sets <code>x[0]</code>, <code>x[1]</code>, ..., <code>x[xbytes-1]</code> to random bytes of
data.</p>
<p>Randomness APIs vary in three major ways. <code>randombytes</code> is designed in
each way to simplify callers:</p>
<ul>
<li>
<p>Like <code>RAND_bytes</code>, <code>randombytes</code> automatically generates separate
randomness for any number of bytes in any number of calls in any
number of threads in any number of programs. For comparison, some
randomness APIs (e.g., <code>random</code>) recycle randomness from one program
to another unless the program does extra work to set a separate
"seed", and can recycle randomness across multiple threads unless the
program does further work.</p>
</li>
<li>
<p>Like <code>getrandom</code> and <code>getentropy</code> and <code>RAND_bytes</code>, <code>randombytes</code> aims
for the stringent goal of ensuring that no feasible computation will
ever be able to tell the difference between the output bytes and true
randomness. The caller can treat each returned byte as the result of 8
fresh coin flips. For comparison, some randomness APIs (e.g.,
<code>random</code>) do not aim for this goal and do not view detectable patterns
as a bug, as long as <em>most</em> applications do not notice the patterns.</p>
</li>
<li>
<p>Like <code>random</code>, <code>randombytes</code> always succeeds. Any necessary resources
(e.g., opening a file descriptor for <code>/dev/urandom</code>, on systems that
need this) are allocated at program startup, rather than being
deferred until the first <code>randombytes</code> call; also, dynamic failure
cases such as EINTR are handled inside <code>randombytes</code>. For comparison,
some randomness APIs (e.g., <code>getrandom</code> and <code>getentropy</code> and
<code>RAND_bytes</code>) can return error codes to be handled by the caller. </p>
</li>
</ul>
<p>There are some programs that try to close all file descriptors. These
programs must limit their library use to libraries that promise not to
keep file descriptors open. In particular, these programs must not use
<code>randombytes</code> (which keeps a file descriptor open on some systems) or
other libraries calling <code>randombytes</code>.</p>
<h3>LINK DETAILS</h3>
<p>Currently <code>-lrandombytes</code> is a frontend symbolic link to either
<code>-lrandombytes-kernel</code> or <code>-lrandombytes-openssl</code> as a backend library.
To simplify system-wide replacement of the backend library, typical
applications should dynamically link to <code>-lrandombytes</code> rather than to
<code>-lrandombytes-kernel</code> or <code>-lrandombytes-openssl</code>.</p>
<p>Applications that link statically to <code>-lrandombytes</code> also need
<code>-lcrypto</code> if <code>-lrandombytes</code> is <code>-lrandombytes-openssl</code>.</p>
<p>Currently <code>randombytes</code> is a macro, where the function actually linked
is <code>randombytes_internal_void_voidstar_longlong</code>.</p>
<h3>HISTORY</h3>
<p>The <code>randombytes</code> API was introduced in 2008 as part of the
<a href="https://bench.cr.yp.to">SUPERCOP</a>
benchmarking framework for cryptographic software.</p>
<p>Similar previous APIs include <code>RAND_bytes</code> and <code>arc4random_buf</code>, but
<code>RAND_bytes</code> was allowed to return failures and <code>arc4random_buf</code> was
using the broken RC4 stream cipher.</p>
<h3>SEE ALSO</h3>
<p><strong>getrandom</strong>(2), <strong>getentropy</strong>(2), <strong>rand</strong>(3), <strong>random</strong>(3),
<strong>arc4random</strong>(3), <strong>urandom</strong>(4)</p><hr><font size=1><b>Version:</b>
This is version 2023.09.04 of the "API" web page.
</font>
</div>
</body>
</html>