mirror of https://github.com/mkerrisk/man-pages
getrandom.2: New page documenting getrandom(2)
Kernel 3.17 introduces a new system call getrandom(2). The man page in this patch is based on the commit message by Theodore Ts'o and suggestions by Michael Kerrisk. Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Heinrich Schuchardt
Michael Kerrisk
parent
6f0dcebc96
commit
18647599c7
|
|
@ -0,0 +1,242 @@
|
|||
.\" Copyright (C) 2014, Theodore Ts'o <tytso@mit.edu>
|
||||
.\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de>
|
||||
.\"
|
||||
.\" %%%LICENSE_START(VERBATIM)
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
.\" preserved on all copies.
|
||||
.\"
|
||||
.\" Permission is granted to copy and distribute modified versions of
|
||||
.\" this manual under the conditions for verbatim copying, provided that
|
||||
.\" the entire resulting derived work is distributed under the terms of
|
||||
.\" a permission notice identical to this one.
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume.
|
||||
.\" no responsibility for errors or omissions, or for damages resulting.
|
||||
.\" from the use of the information contained herein. The author(s) may.
|
||||
.\" not have taken the same level of care in the production of this.
|
||||
.\" manual, which is licensed free of charge, as they might when working.
|
||||
.\" professionally.
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\" %%%LICENSE_END
|
||||
|
||||
.TH GETRANDOM 2 2014-10-03 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
getrandom \- obtain a series of random bytes
|
||||
.SH SYNOPSIS
|
||||
.B #include <linux/random.h>
|
||||
.sp
|
||||
.BI "int getrandom(void *"buf ", size_t " buflen ", unsigned int " flags );
|
||||
.SH DESCRIPTION
|
||||
The system call
|
||||
.BR getrandom ()
|
||||
fills the buffer pointed to by
|
||||
.I buf
|
||||
with up to
|
||||
.I buflen
|
||||
random bytes.
|
||||
These can be used to seed user-space random number generators
|
||||
or for other cryptographic purposes.
|
||||
.PP
|
||||
.BR getrandom ()
|
||||
relies on entropy gathered from device drivers and other sources of
|
||||
environmental noise.
|
||||
Unnecessarily reading large quantities of data will have a negative impact
|
||||
on other users of the
|
||||
.I /dev/random
|
||||
and the
|
||||
.I /dev/urandom
|
||||
devices.
|
||||
Therefore
|
||||
.BR getrandom ()
|
||||
should not be used for Monte Carlo simulations or other
|
||||
programs/algorithms which are doing probabilistic sampling.
|
||||
.PP
|
||||
The
|
||||
.I flags
|
||||
argument is a bit mask that can contain zero or more of the following values
|
||||
ORed together:
|
||||
.TP
|
||||
.B GRND_RANDOM
|
||||
If this bit is set, then random bytes are drawn from the
|
||||
.I /dev/random
|
||||
pool instead of the
|
||||
.I /dev/urandom
|
||||
pool.
|
||||
The
|
||||
.I /dev/random
|
||||
pool is limited based on the entropy that can be obtained from environmental
|
||||
noise.
|
||||
If less random bytes are available than are requested in argument
|
||||
.IR buflen ,
|
||||
the available random bytes will be copied and the call returns.
|
||||
If no random byte is available, the response will depend on the
|
||||
presence of
|
||||
.B GRND_NONBLOCK
|
||||
in the
|
||||
.I flags
|
||||
argument.
|
||||
.TP
|
||||
.B GRND_NONBLOCK
|
||||
If this bit is set and there is no random byte available at all,
|
||||
.BR getrandom ()
|
||||
will return -1 with
|
||||
.I errno
|
||||
set to
|
||||
.BR EAGAIN .
|
||||
If the
|
||||
.B GRND_NONBLOCK
|
||||
bit is not set and there is no random byte available at all,
|
||||
.BR getrandom ()
|
||||
will block.
|
||||
.SH RETURN VALUE
|
||||
On success,
|
||||
.BR getrandom ()
|
||||
returns the number of bytes that were copied to the buffer
|
||||
.IR buf .
|
||||
This may be less than the bytes requested by the caller via
|
||||
.I buflen
|
||||
if insufficient entropy was present in the
|
||||
.IR /dev/random
|
||||
pool, or if the system call was interrupted by a signal.
|
||||
.PP
|
||||
On error, -1 is returned, and
|
||||
.I errno
|
||||
is set appropriately.
|
||||
.SH ERRORS
|
||||
.TP
|
||||
.B EINVAL
|
||||
An invalid flag was passed to
|
||||
.BR getrandom ().
|
||||
.TP
|
||||
.B EFAULT
|
||||
The address referenced in parameter
|
||||
.I buf
|
||||
is outside the accessible address space.
|
||||
.TP
|
||||
.B EAGAIN
|
||||
The requested entropy was not available, and
|
||||
.BR getrandom ()
|
||||
would have blocked if the
|
||||
.B GRND_NONBLOCK
|
||||
flag was not set.
|
||||
.TP
|
||||
.B EINTR
|
||||
While blocked waiting for entropy, the call was interrupted by a signal
|
||||
handler; see the description of how interrupted
|
||||
.BR read (2)
|
||||
calls on "slow" devices are handled with and without the
|
||||
.B SA_RESTART
|
||||
flag in the
|
||||
.BR signal (7)
|
||||
man page.
|
||||
.SH VERSIONS
|
||||
.BR getrandom ()
|
||||
was introduced in version 3.17 of the Linux kernel.
|
||||
.SH CONFORMING TO
|
||||
This system call is Linux-specific.
|
||||
.SH NOTES
|
||||
.SS Interruption by a signal handler
|
||||
The reaction of
|
||||
.BR getrandom ()
|
||||
in case of an interruption of a blocking call by a signal
|
||||
when reading from
|
||||
.I /dev/urandom
|
||||
.RB ( GRND_RANDOM
|
||||
is not set)
|
||||
depends on the initialization state of the entropy buffer
|
||||
and on the request size
|
||||
.IR buflen .
|
||||
If the entropy is not yet initialized or the request size is large
|
||||
.RI ( buflen
|
||||
> 256),
|
||||
.B EINTR
|
||||
will be returned.
|
||||
If the entropy pool has been intialized and the request size is small
|
||||
.RI ( buflen
|
||||
<= 256),
|
||||
.BR getrandom ()
|
||||
will not return
|
||||
.BR EINTR .
|
||||
Instead, it will return all of the bytes that have been requested.
|
||||
.PP
|
||||
When reading from
|
||||
.I /dev/random
|
||||
.RB ( GRND_RANDOM
|
||||
is set)
|
||||
these guarantees do
|
||||
.I not
|
||||
apply.
|
||||
.PP
|
||||
Calling
|
||||
.BR getrandom ()
|
||||
to read
|
||||
.I /dev/urandom
|
||||
for small values (<= 256) of
|
||||
.I buflen
|
||||
is the preferred mode of usage.
|
||||
.PP
|
||||
The special treatment of small values of
|
||||
.I buflen
|
||||
was designed for compatibility with
|
||||
OpenBSD's
|
||||
.BR getentropy ()
|
||||
system call.
|
||||
.PP
|
||||
The user of
|
||||
.BR getrandom ()
|
||||
.I must
|
||||
always check the return value, in case it indicates some error,
|
||||
or if fewer bytes than requested were returned.
|
||||
In the case where
|
||||
.B GRND_RANDOM
|
||||
is not specified and
|
||||
.I buflen
|
||||
is less than or equal to 256,
|
||||
a return of fewer bytes than requested should never happen,
|
||||
but the careful user-space code should check for this anyway!
|
||||
.SS Choice of random device
|
||||
Unless you are doing long-term key generation (and perhaps not even
|
||||
then), you probably shouldn't be using
|
||||
.B GRND_RANDOM.
|
||||
The cryptographic algorithms used for
|
||||
.I /dev/urandom
|
||||
are quite conservative, and so should be sufficient for all purposes.
|
||||
The disadvantage of
|
||||
.B GRND_RANDOM
|
||||
is that it can block.
|
||||
Furthermore, dealing with partially fulfilled
|
||||
.BR getrandom ()
|
||||
requests increases code complexity.
|
||||
.SS Emulating OpenBSD's getentropy()
|
||||
The
|
||||
.BR getentropy ()
|
||||
system call in OpenBSD can be emulated using the following
|
||||
function:
|
||||
|
||||
.in +4n
|
||||
.nf
|
||||
int
|
||||
getentropy(void *buf, size_t buflen)
|
||||
{
|
||||
int ret;
|
||||
|
||||
if (buflen > 256)
|
||||
goto failure;
|
||||
ret = getrandom(buf, buflen, 0);
|
||||
if (ret < 0)
|
||||
return ret;
|
||||
if (ret == buflen)
|
||||
return 0;
|
||||
failure:
|
||||
errno = EIO;
|
||||
return -1;
|
||||
}
|
||||
.fi
|
||||
.in
|
||||
.SH SEE ALSO
|
||||
.BR random (4),
|
||||
.BR urandom (4)
|
||||
Loading…
Reference in New Issue