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