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 2016-10-08 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 getrandom \- obtain a series of random bytes
  30 .SH SYNOPSIS
  31 .B #include <linux/random.h>
  32 .sp
  33 .BI "int getrandom(void *"buf ", size_t " buflen ", unsigned int " flags );
  34 .SH DESCRIPTION
  35 The
  36 .BR getrandom ()
  37 system call fills the buffer pointed to by
  38 .I buf
  39 with up to
  40 .I buflen
  41 random bytes.
  42 These bytes can be used to seed user-space random number generators
  43 or for cryptographic purposes.
  44
  45 By default,
  46 .BR getrandom ()
  47 draws entropy from the
  48 .IR /dev/urandom
  49 pool.
  50 This behavior can be changed via the
  51 .I flags
  52 argument.
  53
  54 If the
  55 .IR /dev/urandom
  56 pool has been initialized,
  57 reads of up to 256 bytes will always return as many bytes as
  58 requested and will not be interrupted by signals.
  59 No such guarantees apply for larger buffer sizes.
  60 For example, if the call is interrupted by a signal handler,
  61 it may return a partially filled buffer, or fail with the error
  62 .BR EINTR .
  63 If the entropy pool has not yet been initialized, then the call blocks, unless
  64 .B GRND_NONBLOCK
  65 is specified in
  66 .IR flags .
  67
  68 The
  69 .I flags
  70 argument is a bit mask that can contain zero or more of the following values
  71 ORed together:
  72 .TP
  73 .B GRND_RANDOM
  74 If this bit is set, then random bytes are drawn from the
  75 .I /dev/random
  76 pool instead of the
  77 .I /dev/urandom
  78 pool.
  79 The
  80 .I /dev/random
  81 pool is limited based on the entropy that can be obtained from environmental
  82 noise.
  83 If the number of available bytes in
  84 .I /dev/random
  85 is less than requested in
  86 .IR buflen ,
  87 the call returns just the available random bytes.
  88 If no random bytes are available, the behavior depends on the presence of
  89 .B GRND_NONBLOCK
  90 in the
  91 .I flags
  92 argument.
  93 .TP
  94 .B GRND_NONBLOCK
  95 By default, when reading from
  96 .IR /dev/random ,
  97 .BR getrandom ()
  98 blocks if no random bytes are available,
  99 and when reading from
 100 .IR /dev/urandom ,
 101 it blocks if the entropy pool has not yet been initialized.
 102 If the
 103 .B GRND_NONBLOCK
 104 flag is set, then
 105 .BR getrandom ()
 106 does not block in these cases, but instead immediately returns \-1 with
 107 .I errno
 108 set to
 109 .BR EAGAIN .
 110 .SH RETURN VALUE
 111 On success,
 112 .BR getrandom ()
 113 returns the number of bytes that were copied to the buffer
 114 .IR buf .
 115 This may be less than the number of bytes requested via
 116 .I buflen
 117 if
 118 .BR GRND_RANDOM
 119 was specified in
 120 .IR flags
 121 and insufficient entropy was present in the
 122 .IR /dev/random
 123 pool, or if the system call was interrupted by a signal.
 124 .PP
 125 On error, \-1 is returned, and
 126 .I errno
 127 is set appropriately.
 128 .SH ERRORS
 129 .TP
 130 .B EAGAIN
 131 The requested entropy was not available, and
 132 .BR getrandom ()
 133 would have blocked if the
 134 .B GRND_NONBLOCK
 135 flag was not set.
 136 .TP
 137 .B EFAULT
 138 The address referred to by
 139 .I buf
 140 is outside the accessible address space.
 141 .TP
 142 .B EINTR
 143 The call was interrupted by a signal
 144 handler; see the description of how interrupted
 145 .BR read (2)
 146 calls on "slow" devices are handled with and without the
 147 .B SA_RESTART
 148 flag in the
 149 .BR signal (7)
 150 man page.
 151 .TP
 152 .B EINVAL
 153 An invalid flag was specified in
 154 .IR flags .
 155 .SH VERSIONS
 156 .BR getrandom ()
 157 was introduced in version 3.17 of the Linux kernel.
 158 .SH CONFORMING TO
 159 This system call is Linux-specific.
 160 .SH NOTES
 161 Unlike
 162 .IR /dev/random
 163 and
 164 .IR /dev/random ,
 165 .BR getrandom ()
 166 does not involve the use of pathnames or file descriptors.
 167 Thus,
 168 .BR getrandom ()
 169 can be useful in cases where
 170 .BR chroot (2)
 171 makes
 172 .I /dev
 173 pathnames invisible,
 174 and where an application (e.g., a daemon during start-up)
 175 closes a file descriptor for one of these files
 176 that was opened by a library.
 177 .\"
 178 .SS Maximum number of bytes returned
 179 As of Linux 3.19 the following limits apply:
 180 .IP * 3
 181 When reading from
 182 .IR /dev/urandom ,
 183 a maximum of 33554431 bytes is returned by a single call to
 184 .BR getrandom ()
 185 on systems where
 186 .I int
 187 has a size of 32 bits.
 188 .IP *
 189 When reading from
 190 .IR /dev/random ,
 191 a maximum of 512 bytes is returned.
 192 .SS Initialization of the entropy pool
 193 The kernel collects bits of entropy from the environment.
 194 When a sufficient number of random bits has been collected, the
 195 .I /dev/urandom
 196 entropy pool is considered to be initialized.
 197 This state is normally reached early in the system bootstrap phase.
 198 .SS Interruption by a signal handler
 199 When reading from
 200 .I /dev/urandom
 201 .RB ( GRND_RANDOM
 202 is not set),
 203 .BR getrandom ()
 204 will block until the entropy pool has been initialized
 205 (unless the
 206 .BR GRND_NONBLOCK
 207 flag was specified).
 208 If a request is made to read a large number (more than 256) of bytes,
 209 .BR getrandom ()
 210 will block until those bytes have been generated and transferred
 211 from kernel memory to
 212 .IR buf .
 213 When reading from
 214 .I /dev/random
 215 .RB ( GRND_RANDOM
 216 is set),
 217 .BR getrandom ()
 218 will block until some random bytes become available
 219 (unless the
 220 .BR GRND_NONBLOCK
 221 flag was specified).
 222
 223 The behavior when a call to
 224 .BR getrandom ()
 225 that is blocked while reading from
 226 .I /dev/urandom
 227 is interrupted by a signal handler
 228 depends on the initialization state of the entropy buffer
 229 and on the request size,
 230 .IR buflen .
 231 If the entropy is not yet initialized, then the call will fail with the
 232 .B EINTR
 233 error.
 234 If the entropy pool has been initialized
 235 and the request size is large
 236 .RI ( buflen "\ >\ 256),"
 237 the call either succeeds, returning a partially filled buffer,
 238 or fails with the error
 239 .BR EINTR.
 240 If the entropy pool has been initialized and the request size is small
 241 .RI ( buflen "\ <=\ 256),"
 242 then
 243 .BR getrandom ()
 244 will not fail with
 245 .BR EINTR .
 246 Instead, it will return all of the bytes that have been requested.
 247
 248 When reading from
 249 .IR /dev/random ,
 250 blocking requests of any size can be interrupted by a signal
 251 (the call fails with the error
 252 .BR EINTR ).
 253
 254 Calling
 255 .BR getrandom ()
 256 to read
 257 .I /dev/urandom
 258 for small values (<=\ 256) of
 259 .I buflen
 260 is the preferred mode of usage.
 261 .PP
 262 The special treatment of small values of
 263 .I buflen
 264 was designed for compatibility with
 265 OpenBSD's
 266 .BR getentropy ()
 267 system call.
 268 .PP
 269 The user of
 270 .BR getrandom ()
 271 .I must
 272 always check the return value,
 273 to determine whether either an error occurred
 274 or fewer bytes than requested were returned.
 275 In the case where
 276 .B GRND_RANDOM
 277 is not specified and
 278 .I buflen
 279 is less than or equal to 256,
 280 a return of fewer bytes than requested should never happen,
 281 but the careful programmer will check for this anyway!
 282 .SS Choice of random device
 283 Unless you are doing long-term key generation (and perhaps not even
 284 then), you probably shouldn't be using the
 285 .BR getrandom ()
 286 .BR GRND_RANDOM
 287 flag or the
 288 .IR /dev/random
 289 device.
 290
 291 Instead, use
 292 .IR /dev/urandom ;
 293 the cryptographic algorithms used for
 294 .IR /dev/urandom ;
 295 are quite conservative, and so should be sufficient for all purposes.
 296
 297 The disadvantage of
 298 .B GRND_RANDOM
 299 and reads from
 300 .I dev/random
 301 is that the operation can block.
 302 Furthermore, dealing with the partially fulfilled
 303 requests that can occur when using
 304 .B GRND_RANDOM
 305 or when reading from
 306 .I /dev/random
 307 increases code complexity.
 308 .\"
 309 .SS Usage recommendations
 310 The kernel random-number generator
 311 relies on entropy gathered from device drivers and other sources of
 312 environmental noise.
 313 It is designed to produce a small
 314 amount of high-quality seed material to seed a
 315 cryptographic pseudorandom number generator (CPRNG).
 316 It is designed for security, not speed, and is poorly
 317 suited to generating large amounts of cryptographic random data.
 318 Users should be very economical in the amount of seed
 319 material that they consume via
 320 .BR getrandom (),
 321 .IR /dev/urandom ,
 322 and
 323 .IR /dev/random .
 324 Consuming unnecessarily large quantities of data via these interfaces
 325 will have a negative impact on other consumers of randomness.
 326
 327 These interfaces should not be used to provide large quantities
 328 of data for Monte Carlo simulations or other
 329 programs/algorithms which are doing probabilistic sampling.
 330 And indeed, such usage is unnecessary (and will be slow):
 331 instead, use these interfaces to provide a small amount of
 332 data used to seed a user-space pseudorandom number generator
 333 for use by such applications.
 334 .\"
 335 .SS Generating cryptographic keys
 336 The amount of seed material required to generate a cryptographic key
 337 equals the effective key size of the key.
 338 For example, a 3072-bit RSA
 339 or Diffie-Hellman private key has an effective key size of 128 bits
 340 (it requires about 2^128 operations to break) so a key generator
 341 needs only 128 bits (16 bytes) of seed material from
 342 .IR /dev/random .
 343
 344 While some safety margin above that minimum is reasonable, as a guard
 345 against flaws in the CPRNG algorithm, no cryptographic primitive
 346 available today can hope to promise more than 256 bits of security,
 347 so if any program reads more than 256 bits (32 bytes) from the kernel
 348 random pool per invocation, or per reasonable reseed interval (not less
 349 than one minute), that should be taken as a sign that its cryptography is
 350 .I not
 351 skillfully implemented.
 352 .\"
 353 .SS Emulating OpenBSD's getentropy()
 354 The
 355 .BR getentropy ()
 356 system call in OpenBSD can be emulated using the following
 357 function:
 358
 359 .in +4n
 360 .nf
 361 int
 362 getentropy(void *buf, size_t buflen)
 363 {
 364     int ret;
 365
 366     if (buflen > 256)
 367         goto failure;
 368     ret = getrandom(buf, buflen, 0);
 369     if (ret < 0)
 370         return ret;
 371     if (ret == buflen)
 372         return 0;
 373 failure:
 374     errno = EIO;
 375     return \-1;
 376 }
 377 .fi
 378 .in
 379 .SH BUGS
 380 As of Linux 3.19, the following bug exists:
 381 .\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16
 382 .IP * 3
 383 Depending on CPU load,
 384 .BR getrandom ()
 385 does not react to interrupts before reading all bytes requested.
 386 .SH SEE ALSO
 387 .BR random (4),
 388 .BR urandom (4),
 389 .BR signal (7)