Re: [PATCH 1/3] getrandom.2: new manpage

[Michael Kerrisk (man-pages)]

Hi Heinrich,

Things seem to have stalled on the getrandom(2) man page (no response
to my mail below), and also in your conversation with Ted regarding
the 29 Nov patch proposal "urandom: handle signals immediately".
What's the current status?

Cheers,

Michael


On 11 November 2014 at 12:44, Michael Kerrisk (man-pages)
<mtk.manpages@xxxxxxxxx> wrote:
> Hi Heinrich,
>
> On Fri, Oct 3, 2014 at 2:15 AM, Heinrich Schuchardt <xypron.glpk@xxxxxx> wrote:
>> 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 <tytso@xxxxxxx> and suggestion by
>> Michael Kerrisk <mtk.manpages@xxxxxxxxx>.
>
> No word from Ted so far...
>
> I've added LKML to CC, because I think it's worth getting wider review
> of the page at this point.
>
> I've done some further editing on the page, and pushed the current
> version in public branch:
> http://git.kernel.org/cgit/docs/man-pages/man-pages.git/log/?h=draft_getrandom
>
> Could you please review the current version, appended below. Note that
> there are a couple of FIXMEs there. Also, could you pay special
> attention to the changes in these commits, to make sure I have not
> injected any errors:
>
> pick 0ef180e getrandom.2: Add a sentence to clarify the default behavior...
> pick 62342ef getrandom.2: Reword GRND_NONBLOCK description
> pick 0c90d3d getrandom.2: Reword GRND_RANDOM description
>
> Cheers,
>
> Michael
>
> .\" Copyright (C) 2014, Theodore Ts'o <tytso@xxxxxxx>
> .\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@xxxxxx>
> .\"
> .\" %%%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
> .I /dev/urandom
> devices.
> Therefore
> .BR getrandom ()
> should not be used for Monte Carlo simulations or other
> programs/algorithms which are doing probabilistic sampling.
>
> .\" FIXME is the following paragraph correct?
> By default,
> .BR getrandom ()
> draws entropy from the
> .IR /dev/urandom
> pool, and, if that pool has been initialized and
> .IR buflen
> is less than or equal to 256 (see NOTES, below),
> then the call never blocks when drawing from that pool
> and always returns the number of bytes requested in
> .IR buflen .
> This behavior can be changed via the
> .I flags
> argument.
>
> 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 the number of available bytes in
> .I /dev/random
> is less than requested in
> .IR buflen ,
> the call returns just the available random bytes.
> 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
> By default, if there is no random byte available at all,
> .BR getrandom ()
> blocks until data is available.
> If the
> .B GRND_NONBLOCK
> flag is set, then
> .BR getrandom ()
> instead immediately returns -1 with
> .I errno
> set to
> .BR EAGAIN .
> .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 number of bytes requested 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 specified in
> .IR flags .
> .TP
> .B EFAULT
> The address referred to by
> .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
> .\" FIXME Here, I think there needs to be an opening paragraph that describes
> .\" the cases where getrandom() can block. This should cover the cases with
> .\" GRND_RANDOM and without GRND_RANDOM. Reading the existing page, I am
> .\" still not completely confident that I know what the cases are.
> 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 initialized 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,
> to determine whether either an error occurred
> or 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)



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/