man2/getrandom.2

   1 .\" Copyright (C) 2014, Theodore Ts'o <tytso@mit.edu>
   2 .\" Copyright (C) 2014,2015 Heinrich Schuchardt <xypron.glpk@gmx.de>
   3 .\" Copyright (C) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH getrandom 2 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 getrandom \- obtain a series of random bytes
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <sys/random.h>
  16 .PP
  17 .BI "ssize_t getrandom(void " buf [. buflen "], size_t " buflen ", \
  18 unsigned int " flags );
  19 .fi
  20 .SH DESCRIPTION
  21 The
  22 .BR getrandom ()
  23 system call fills the buffer pointed to by
  24 .I buf
  25 with up to
  26 .I buflen
  27 random bytes.
  28 These bytes can be used to seed user-space random number generators
  29 or for cryptographic purposes.
  30 .PP
  31 By default,
  32 .BR getrandom ()
  33 draws entropy from the
  34 .I urandom
  35 source (i.e., the same source as the
  36 .I /dev/urandom
  37 device).
  38 This behavior can be changed via the
  39 .I flags
  40 argument.
  41 .PP
  42 If the
  43 .I urandom
  44 source has been initialized,
  45 reads of up to 256 bytes will always return as many bytes as
  46 requested and will not be interrupted by signals.
  47 No such guarantees apply for larger buffer sizes.
  48 For example, if the call is interrupted by a signal handler,
  49 it may return a partially filled buffer, or fail with the error
  50 .BR EINTR .
  51 .PP
  52 If the
  53 .I urandom
  54 source has not yet been initialized, then
  55 .BR getrandom ()
  56 will block, unless
  57 .B GRND_NONBLOCK
  58 is specified in
  59 .IR flags .
  60 .PP
  61 The
  62 .I flags
  63 argument is a bit mask that can contain zero or more of the following values
  64 ORed together:
  65 .TP
  66 .B GRND_RANDOM
  67 If this bit is set, then random bytes are drawn from the
  68 .I random
  69 source
  70 (i.e., the same source as the
  71 .I /dev/random
  72 device)
  73 instead of the
  74 .I urandom
  75 source.
  76 The
  77 .I random
  78 source is limited based on the entropy that can be obtained from environmental
  79 noise.
  80 If the number of available bytes in the
  81 .I random
  82 source is less than requested in
  83 .IR buflen ,
  84 the call returns just the available random bytes.
  85 If no random bytes are available, the behavior depends on the presence of
  86 .B GRND_NONBLOCK
  87 in the
  88 .I flags
  89 argument.
  90 .TP
  91 .B GRND_NONBLOCK
  92 By default, when reading from the
  93 .I random
  94 source,
  95 .BR getrandom ()
  96 blocks if no random bytes are available,
  97 and when reading from the
  98 .I urandom
  99 source, it blocks if the entropy pool has not yet been initialized.
 100 If the
 101 .B GRND_NONBLOCK
 102 flag is set, then
 103 .BR getrandom ()
 104 does not block in these cases, but instead immediately returns \-1 with
 105 .I errno
 106 set to
 107 .BR EAGAIN .
 108 .SH RETURN VALUE
 109 On success,
 110 .BR getrandom ()
 111 returns the number of bytes that were copied to the buffer
 112 .IR buf .
 113 This may be less than the number of bytes requested via
 114 .I buflen
 115 if either
 116 .B GRND_RANDOM
 117 was specified in
 118 .I flags
 119 and insufficient entropy was present in the
 120 .I random
 121 source or the system call was interrupted by a signal.
 122 .PP
 123 On error, \-1 is returned, and
 124 .I errno
 125 is set to indicate the error.
 126 .SH ERRORS
 127 .TP
 128 .B EAGAIN
 129 The requested entropy was not available, and
 130 .BR getrandom ()
 131 would have blocked if the
 132 .B GRND_NONBLOCK
 133 flag was not set.
 134 .TP
 135 .B EFAULT
 136 The address referred to by
 137 .I buf
 138 is outside the accessible address space.
 139 .TP
 140 .B EINTR
 141 The call was interrupted by a signal
 142 handler; see the description of how interrupted
 143 .BR read (2)
 144 calls on "slow" devices are handled with and without the
 145 .B SA_RESTART
 146 flag in the
 147 .BR signal (7)
 148 man page.
 149 .TP
 150 .B EINVAL
 151 An invalid flag was specified in
 152 .IR flags .
 153 .TP
 154 .B ENOSYS
 155 The glibc wrapper function for
 156 .BR getrandom ()
 157 determined that the underlying kernel does not implement this system call.
 158 .SH VERSIONS
 159 .BR getrandom ()
 160 was introduced in Linux 3.17.
 161 Support was added in glibc 2.25.
 162 .SH STANDARDS
 163 This system call is Linux-specific.
 164 .SH NOTES
 165 For an overview and comparison of the various interfaces that
 166 can be used to obtain randomness, see
 167 .BR random (7).
 168 .PP
 169 Unlike
 170 .I /dev/random
 171 and
 172 .IR /dev/urandom ,
 173 .BR getrandom ()
 174 does not involve the use of pathnames or file descriptors.
 175 Thus,
 176 .BR getrandom ()
 177 can be useful in cases where
 178 .BR chroot (2)
 179 makes
 180 .I /dev
 181 pathnames invisible,
 182 and where an application (e.g., a daemon during start-up)
 183 closes a file descriptor for one of these files
 184 that was opened by a library.
 185 .\"
 186 .SS Maximum number of bytes returned
 187 As of Linux 3.19 the following limits apply:
 188 .IP \(bu 3
 189 When reading from the
 190 .I urandom
 191 source, a maximum of 33554431 bytes is returned by a single call to
 192 .BR getrandom ()
 193 on systems where
 194 .I int
 195 has a size of 32 bits.
 196 .IP \(bu
 197 When reading from the
 198 .I random
 199 source, a maximum of 512 bytes is returned.
 200 .SS Interruption by a signal handler
 201 When reading from the
 202 .I urandom
 203 source
 204 .RB ( GRND_RANDOM
 205 is not set),
 206 .BR getrandom ()
 207 will block until the entropy pool has been initialized
 208 (unless the
 209 .B GRND_NONBLOCK
 210 flag was specified).
 211 If a request is made to read a large number of bytes (more than 256),
 212 .BR getrandom ()
 213 will block until those bytes have been generated and transferred
 214 from kernel memory to
 215 .IR buf .
 216 When reading from the
 217 .I random
 218 source
 219 .RB ( GRND_RANDOM
 220 is set),
 221 .BR getrandom ()
 222 will block until some random bytes become available
 223 (unless the
 224 .B GRND_NONBLOCK
 225 flag was specified).
 226 .PP
 227 The behavior when a call to
 228 .BR getrandom ()
 229 that is blocked while reading from the
 230 .I urandom
 231 source is interrupted by a signal handler
 232 depends on the initialization state of the entropy buffer
 233 and on the request size,
 234 .IR buflen .
 235 If the entropy is not yet initialized, then the call fails with the
 236 .B EINTR
 237 error.
 238 If the entropy pool has been initialized
 239 and the request size is large
 240 .RI ( buflen "\ >\ 256),"
 241 the call either succeeds, returning a partially filled buffer,
 242 or fails with the error
 243 .BR EINTR .
 244 If the entropy pool has been initialized and the request size is small
 245 .RI ( buflen "\ <=\ 256),"
 246 then
 247 .BR getrandom ()
 248 will not fail with
 249 .BR EINTR .
 250 Instead, it will return all of the bytes that have been requested.
 251 .PP
 252 When reading from the
 253 .I random
 254 source, blocking requests of any size can be interrupted by a signal handler
 255 (the call fails with the error
 256 .BR EINTR ).
 257 .PP
 258 Using
 259 .BR getrandom ()
 260 to read small buffers (<=\ 256 bytes) from the
 261 .I urandom
 262 source is the preferred mode of usage.
 263 .PP
 264 The special treatment of small values of
 265 .I buflen
 266 was designed for compatibility with
 267 OpenBSD's
 268 .BR getentropy (3),
 269 which is nowadays supported by glibc.
 270 .PP
 271 The user of
 272 .BR getrandom ()
 273 .I must
 274 always check the return value,
 275 to determine whether either an error occurred
 276 or fewer bytes than requested were returned.
 277 In the case where
 278 .B GRND_RANDOM
 279 is not specified and
 280 .I buflen
 281 is less than or equal to 256,
 282 a return of fewer bytes than requested should never happen,
 283 but the careful programmer will check for this anyway!
 284 .SH BUGS
 285 As of Linux 3.19, the following bug exists:
 286 .\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16
 287 .IP \(bu 3
 288 Depending on CPU load,
 289 .BR getrandom ()
 290 does not react to interrupts before reading all bytes requested.
 291 .SH SEE ALSO
 292 .BR getentropy (3),
 293 .BR random (4),
 294 .BR urandom (4),
 295 .BR random (7),
 296 .BR signal (7)