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