-rw-r--r-- 3904 librandombytes-20240318/doc/man/randombytes.3 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "randombytes" "3" "" "" ""
.hy
.SS NAME
.PP
randombytes - fill a buffer with random data
.SS SYNOPSIS
.IP
.nf
\f[C]
#include <randombytes.h>

unsigned char x[xbytes];

randombytes(x,xbytes);
\f[R]
.fi
.PP
Link with \f[V]-lrandombytes\f[R].
.SS DESCRIPTION
.PP
\f[V]randombytes\f[R] sets \f[V]x[0]\f[R], \f[V]x[1]\f[R], \&...,
\f[V]x[xbytes-1]\f[R] to random bytes of data.
.PP
Randomness APIs vary in three major ways.
\f[V]randombytes\f[R] is designed in each way to simplify callers:
.IP \[bu] 2
Like \f[V]RAND_bytes\f[R], \f[V]randombytes\f[R] 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., \f[V]random\f[R]) recycle
randomness from one program to another unless the program does extra
work to set a separate \[lq]seed\[rq], and can recycle randomness across
multiple threads unless the program does further work.
.IP \[bu] 2
Like \f[V]getrandom\f[R] and \f[V]getentropy\f[R] and
\f[V]RAND_bytes\f[R], \f[V]randombytes\f[R] 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., \f[V]random\f[R]) do not aim
for this goal and do not view detectable patterns as a bug, as long as
\f[I]most\f[R] applications do not notice the patterns.
.IP \[bu] 2
Like \f[V]random\f[R], \f[V]randombytes\f[R] always succeeds.
Any necessary resources (e.g., opening a file descriptor for
\f[V]/dev/urandom\f[R], on systems that need this) are allocated at
program startup, rather than being deferred until the first
\f[V]randombytes\f[R] call; also, dynamic failure cases such as EINTR
are handled inside \f[V]randombytes\f[R].
For comparison, some randomness APIs (e.g., \f[V]getrandom\f[R] and
\f[V]getentropy\f[R] and \f[V]RAND_bytes\f[R]) can return error codes to
be handled by the caller.
.PP
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 \f[V]randombytes\f[R] (which
keeps a file descriptor open on some systems) or other libraries calling
\f[V]randombytes\f[R].
.SS LINK DETAILS
.PP
Currently \f[V]-lrandombytes\f[R] is a frontend symbolic link to either
\f[V]-lrandombytes-kernel\f[R] or \f[V]-lrandombytes-openssl\f[R] as a
backend library.
To simplify system-wide replacement of the backend library, typical
applications should dynamically link to \f[V]-lrandombytes\f[R] rather
than to \f[V]-lrandombytes-kernel\f[R] or
\f[V]-lrandombytes-openssl\f[R].
.PP
Applications that link statically to \f[V]-lrandombytes\f[R] also need
\f[V]-lcrypto\f[R] if \f[V]-lrandombytes\f[R] is
\f[V]-lrandombytes-openssl\f[R].
.PP
Currently \f[V]randombytes\f[R] is a macro, where the function actually
linked is \f[V]randombytes_internal_void_voidstar_longlong\f[R].
.SS HISTORY
.PP
The \f[V]randombytes\f[R] API was introduced in 2008 as part of the
SUPERCOP (https://bench.cr.yp.to) benchmarking framework for
cryptographic software.
.PP
Similar previous APIs include \f[V]RAND_bytes\f[R] and
\f[V]arc4random_buf\f[R], but \f[V]RAND_bytes\f[R] was allowed to return
failures and \f[V]arc4random_buf\f[R] was using the broken RC4 stream
cipher.
.SS SEE ALSO
.PP
\f[B]getrandom\f[R](2), \f[B]getentropy\f[R](2), \f[B]rand\f[R](3),
\f[B]random\f[R](3), \f[B]arc4random\f[R](3), \f[B]urandom\f[R](4)