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