original/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 <tmk.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 2015-01-22 "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 .PP
  45 .BR getrandom ()
  46 relies on entropy gathered from device drivers and other sources of
  47 environmental noise.
  48 Unnecessarily reading large quantities of data will have a negative impact
  49 on other users of the
  50 .I /dev/random
  51 and
  52 .I /dev/urandom
  53 devices.
  54 Therefore,
  55 .BR getrandom ()
  56 should not be used for Monte Carlo simulations or other
  57 programs/algorithms which are doing probabilistic sampling.
  58
  59 By default,
  60 .BR getrandom ()
  61 draws entropy from the
  62 .IR /dev/urandom
  63 pool.
  64 This behavior can be changed via the
  65 .I flags
  66 argument.
  67 If the
  68 .IR /dev/urandom
  69 pool has been initialized,
  70 reads of up to 256 bytes will always return as many bytes as
  71 requested and will not be interrupted by signals.
  72 No such guarantees apply for larger buffer sizes.
  73 For example, if the call is interrupted by a signal handler,
  74 it may return a partially filled buffer, or fail with the error
  75 .BR EINTR .
  76 If the pool has not yet been initialized, then the call blocks, unless
  77 .B GRND_RANDOM
  78 is specified in
  79 .IR flags .
  80
  81 The
  82 .I flags
  83 argument is a bit mask that can contain zero or more of the following values
  84 ORed together:
  85 .TP
  86 .B GRND_RANDOM
  87 If this bit is set, then random bytes are drawn from the
  88 .I /dev/random
  89 pool instead of the
  90 .I /dev/urandom
  91 pool.
  92 The
  93 .I /dev/random
  94 pool is limited based on the entropy that can be obtained from environmental
  95 noise.
  96 If the number of available bytes in
  97 .I /dev/random
  98 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
 109 .IR /dev/random ,
 110 .BR getrandom ()
 111 blocks if no random bytes are available,
 112 and when reading from
 113 .IR /dev/urandom ,
 114 it blocks if the entropy pool has not yet been initialized.
 115 If the
 116 .B GRND_NONBLOCK
 117 flag is set, then
 118 .BR getrandom ()
 119 does not block in these cases, but instead immediately returns \-1 with
 120 .I errno
 121 set to
 122 .BR EAGAIN .
 123 .SH RETURN VALUE
 124 On success,
 125 .BR getrandom ()
 126 returns the number of bytes that were copied to the buffer
 127 .IR buf .
 128 This may be less than the number of bytes requested via
 129 .I buflen
 130 if
 131 .BR GRND_RANDOM
 132 was specified in
 133 .IR flags
 134 and insufficient entropy was present in the
 135 .IR /dev/random
 136 pool, or if the system call was interrupted by a signal.
 137 .PP
 138 On error, \-1 is returned, and
 139 .I errno
 140 is set appropriately.
 141 .SH ERRORS
 142 .TP
 143 .B EINVAL
 144 An invalid flag was specified in
 145 .IR flags .
 146 .TP
 147 .B EFAULT
 148 The address referred to by
 149 .I buf
 150 is outside the accessible address space.
 151 .TP
 152 .B EAGAIN
 153 The requested entropy was not available, and
 154 .BR getrandom ()
 155 would have blocked if the
 156 .B GRND_NONBLOCK
 157 flag was not set.
 158 .TP
 159 .B EINTR
 160 The call was interrupted by a signal
 161 handler; see the description of how interrupted
 162 .BR read (2)
 163 calls on "slow" devices are handled with and without the
 164 .B SA_RESTART
 165 flag in the
 166 .BR signal (7)
 167 man page.
 168 .SH VERSIONS
 169 .BR getrandom ()
 170 was introduced in version 3.17 of the Linux kernel.
 171 .SH CONFORMING TO
 172 This system call is Linux-specific.
 173 .SH NOTES
 174 .SS Maximum number of bytes returned
 175 As of Linux 3.19 the following limits apply:
 176 .IP * 3
 177 When reading from
 178 .IR /dev/urandom ,
 179 a maximum of 33554431 bytes is returned by a single call to
 180 .BR getrandom ()
 181 on a system where
 182 .I int
 183 has a size of 32 bits.
 184 .IP *
 185 When reading from
 186 .IR /dev/random ,
 187 a maximum of 512 bytes is returned.
 188 .SS Initialization of the entropy pool
 189 The kernel collects bits of entropy from environment.
 190 When a sufficient number of random bits has been collected, the
 191 .I /dev/urandom
 192 entropy pool is considered to be initialized.
 193 This state is normally reached early in the system bootstrap phase.
 194 .SS Interruption by a signal handler
 195 When reading from
 196 .I /dev/urandom
 197 .RB ( GRND_RANDOM
 198 is not set),
 199 .BR getrandom ()
 200 will block until the entropy pool has been initialized
 201 (unless the
 202 .BR GRND_NONBLOCK
 203 flag was specified).
 204 If a request is made to read a large number (more than 256) of bytes,
 205 .BR getrandom ()
 206 will block until those bytes have been generated and transferred
 207 from kernel memory to
 208 .IR buf .
 209 When reading from
 210 .I /dev/random
 211 .RB ( GRND_RANDOM
 212 is set),
 213 .BR getrandom ()
 214 will block until some random bytes become available
 215 (unless the
 216 .BR GRND_NONBLOCK
 217 flag was specified).
 218
 219 The behavior when a call to
 220 .BR getrandom ()
 221 that is blocked while reading from
 222 .I /dev/urandom
 223 is interrupted by a signal handler
 224 depends on the initialization state of the entropy buffer
 225 and on the request size,
 226 .IR buflen .
 227 If the entropy is not yet initialized, then the call will fail with the
 228 .B EINTR
 229 error.
 230 If the entropy pool has been initialized
 231 and the request size is large
 232 .RI ( buflen "\ >\ 256),"
 233 the call either succeeds, returning a partially filled buffer,
 234 or fails with the error
 235 .BR EINTR.
 236 If the entropy pool has been initialized and the request size is small
 237 .RI ( buflen "\ <=\ 256),"
 238 then
 239 .BR getrandom ()
 240 will not fail with
 241 .BR EINTR .
 242 Instead, it will return all of the bytes that have been requested.
 243
 244 When reading from
 245 .IR /dev/random ,
 246 blocking requests of any size can be interrupted by a signal
 247 (the call fails with the error
 248 .BR EINTR ).
 249
 250 Calling
 251 .BR getrandom ()
 252 to read
 253 .I /dev/urandom
 254 for small values (<=\ 256) of
 255 .I buflen
 256 is the preferred mode of usage.
 257 .PP
 258 The special treatment of small values of
 259 .I buflen
 260 was designed for compatibility with
 261 OpenBSD's
 262 .BR getentropy ()
 263 system call.
 264 .PP
 265 The user of
 266 .BR getrandom ()
 267 .I must
 268 always check the return value,
 269 to determine whether either an error occurred
 270 or fewer bytes than requested were returned.
 271 In the case where
 272 .B GRND_RANDOM
 273 is not specified and
 274 .I buflen
 275 is less than or equal to 256,
 276 a return of fewer bytes than requested should never happen,
 277 but the careful programmer will check for this anyway!
 278 .SS Choice of random device
 279 Unless you are doing long-term key generation (and perhaps not even
 280 then), you probably shouldn't be using
 281 .B GRND_RANDOM.
 282 The cryptographic algorithms used for
 283 .I /dev/urandom
 284 are quite conservative, and so should be sufficient for all purposes.
 285 The disadvantage of
 286 .B GRND_RANDOM
 287 is that it can block.
 288 Furthermore, dealing with the partially fulfilled
 289 .BR getrandom ()
 290 requests that can occur when using
 291 .B GRND_RANDOM
 292 increases code complexity.
 293 .SS Emulating OpenBSD's getentropy()
 294 The
 295 .BR getentropy ()
 296 system call in OpenBSD can be emulated using the following
 297 function:
 298
 299 .in +4n
 300 .nf
 301 int
 302 getentropy(void *buf, size_t buflen)
 303 {
 304     int ret;
 305
 306     if (buflen > 256)
 307         goto failure;
 308     ret = getrandom(buf, buflen, 0);
 309     if (ret < 0)
 310         return ret;
 311     if (ret == buflen)
 312         return 0;
 313 failure:
 314     errno = EIO;
 315     return \-1;
 316 }
 317 .fi
 318 .in
 319 .SH BUGS
 320 As of Linux 3.19, the following bug exists:
 321 .\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16
 322 .IP * 3
 323 Depending on CPU load,
 324 .BR getrandom ()
 325 does not react to interrupts before reading all bytes requested.
 326 .SH SEE ALSO
 327 .BR random (4),
 328 .BR urandom (4),
 329 .BR signal (7)
 330 .SH COLOPHON
 331 This page is part of release 3.79 of the Linux
 332 .I man-pages
 333 project.
 334 A description of the project,
 335 information about reporting bugs,
 336 and the latest version of this page,
 337 can be found at
 338 \%http://www.kernel.org/doc/man\-pages/.