man2/getrandom.2

   1 .\" Copyright (C) 2014, Theodore Ts'o <tytso@mit.edu>
   2 .\" Copyright (C) 2014, Heinrich Schuchardt <xypron.glpk@gmx.de>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of
  10 .\" this manual under the conditions for verbatim copying, provided that
  11 .\" the entire resulting derived work is distributed under the terms of
  12 .\" a permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume.
  16 .\" no responsibility for errors or omissions, or for damages resulting.
  17 .\" from the use of the information contained herein.  The author(s) may.
  18 .\" not have taken the same level of care in the production of this.
  19 .\" manual, which is licensed free of charge, as they might when working.
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25
  26 .TH GETRANDOM 2 2015-01-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 getrandom \- obtain a series of random bytes
  29 .SH SYNOPSIS
  30 .B #include <linux/random.h>
  31 .sp
  32 .BI "int getrandom(void *"buf ", size_t " buflen ", unsigned int " flags );
  33 .SH DESCRIPTION
  34 The
  35 .BR getrandom ()
  36 system call fills the buffer pointed to by
  37 .I buf
  38 with up to
  39 .I buflen
  40 random bytes.
  41 These can be used to seed user-space random number generators
  42 or for other cryptographic purposes.
  43 .PP
  44 .BR getrandom ()
  45 relies on entropy gathered from device drivers and other sources of
  46 environmental noise.
  47 Unnecessarily reading large quantities of data will have a negative impact
  48 on other users of the
  49 .I /dev/random
  50 and
  51 .I /dev/urandom
  52 devices.
  53 Therefore
  54 .BR getrandom ()
  55 should not be used for Monte Carlo simulations or other
  56 programs/algorithms which are doing probabilistic sampling.
  57
  58 By default,
  59 .BR getrandom ()
  60 draws entropy from the
  61 .IR /dev/urandom
  62 pool.
  63 This behavior can be changed via the
  64 .I flags
  65 argument.
  66 If the
  67 .IR /dev/urandom
  68 pool has been initialized, reading from that pool never blocks.
  69 If the pool has not yet been initialized, then the call blocks, unless
  70 .B GRND_RANDOM
  71 is specified in
  72 .IR flags .
  73
  74 The
  75 .I flags
  76 argument is a bit mask that can contain zero or more of the following values
  77 ORed together:
  78 .TP
  79 .B GRND_RANDOM
  80 If this bit is set, then random bytes are drawn from the
  81 .I /dev/random
  82 pool instead of the
  83 .I /dev/urandom
  84 pool.
  85 The
  86 .I /dev/random
  87 pool is limited based on the entropy that can be obtained from environmental
  88 noise.
  89 If the number of available bytes in
  90 .I /dev/random
  91 is less than requested in
  92 .IR buflen ,
  93 the call returns just the available random bytes.
  94 If no random bytes are available, the behavior depends on the presence of
  95 .B GRND_NONBLOCK
  96 in the
  97 .I flags
  98 argument.
  99 .TP
 100 .B GRND_NONBLOCK
 101 By default, if there are no random bytes available at all (when reading from
 102 .IR /dev/random ),
 103 or the entropy pool has not yet been initialized (when reading from
 104 .IR /dev/urandom ),
 105 .BR getrandom ()
 106 blocks until data is available.
 107 If the
 108 .B GRND_NONBLOCK
 109 flag is set, then
 110 .BR getrandom ()
 111 instead immediately returns \-1 with
 112 .I errno
 113 set to
 114 .BR EAGAIN .
 115 .SH RETURN VALUE
 116 On success,
 117 .BR getrandom ()
 118 returns the number of bytes that were copied to the buffer
 119 .IR buf .
 120 This may be less than the number of bytes requested via
 121 .I buflen
 122 if
 123 .BR GRND_RANDOM
 124 was specified in
 125 .IR flags
 126 and insufficient entropy was present in the
 127 .IR /dev/random
 128 pool, or if the system call was interrupted by a signal.
 129 .PP
 130 On error, \-1 is returned, and
 131 .I errno
 132 is set appropriately.
 133 .SH ERRORS
 134 .TP
 135 .B EINVAL
 136 An invalid flag was specified in
 137 .IR flags .
 138 .TP
 139 .B EFAULT
 140 The address referred to by
 141 .I buf
 142 is outside the accessible address space.
 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 EINTR
 152 While blocked waiting for entropy, the call was interrupted by a signal
 153 handler; see the description of how interrupted
 154 .BR read (2)
 155 calls on "slow" devices are handled with and without the
 156 .B SA_RESTART
 157 flag in the
 158 .BR signal (7)
 159 man page.
 160 .SH VERSIONS
 161 .BR getrandom ()
 162 was introduced in version 3.17 of the Linux kernel.
 163 .SH CONFORMING TO
 164 This system call is Linux-specific.
 165 .SH NOTES
 166 .SS Interruption by a signal handler
 167 A call to
 168 .BR getrandom ()
 169 can block only when called without the
 170 .B GRND_NONBLOCK
 171 flag.
 172 When reading from
 173 .I /dev/urandom
 174 .RB ( GRND_RANDOM
 175 is not set),
 176 blocking occurs only if the entropy pool has not been initialized yet.
 177 When reading from
 178 .I /dev/random
 179 .RB ( GRND_RANDOM
 180 is set),
 181 blocking occurs if not enough random bytes are available.
 182
 183 The behavior when a call to
 184 .BR getrandom ()
 185 that is blocked while reading from
 186 .I /dev/urandom
 187 is interrupted by a signal handler
 188 depends on the initialization state of the entropy buffer
 189 and on the request size,
 190 .IR buflen .
 191 If the entropy is not yet initialized or the request size is large
 192 .RI ( buflen "\ >\ 256),"
 193 then the call will fail with the
 194 .B EINTR
 195 error.
 196 If the entropy pool has been initialized and the request size is small
 197 .RI ( buflen "\ <=\ 256),"
 198 then
 199 .BR getrandom ()
 200 will not fail with
 201 .BR EINTR .
 202 Instead, it will return all of the bytes that have been requested.
 203 .PP
 204 When reading from
 205 .IR /dev/random ,
 206 these guarantees do
 207 .I not
 208 apply.
 209 .PP
 210 Calling
 211 .BR getrandom ()
 212 to read
 213 .I /dev/urandom
 214 for small values (<=\ 256) of
 215 .I buflen
 216 is the preferred mode of usage.
 217 .PP
 218 The special treatment of small values of
 219 .I buflen
 220 was designed for compatibility with
 221 OpenBSD's
 222 .BR getentropy ()
 223 system call.
 224 .PP
 225 The user of
 226 .BR getrandom ()
 227 .I must
 228 always check the return value,
 229 to determine whether either an error occurred
 230 or fewer bytes than requested were returned.
 231 In the case where
 232 .B GRND_RANDOM
 233 is not specified and
 234 .I buflen
 235 is less than or equal to 256,
 236 a return of fewer bytes than requested should never happen,
 237 but the careful programmer will check for this anyway!
 238 .SS Choice of random device
 239 Unless you are doing long-term key generation (and perhaps not even
 240 then), you probably shouldn't be using
 241 .B GRND_RANDOM.
 242 The cryptographic algorithms used for
 243 .I /dev/urandom
 244 are quite conservative, and so should be sufficient for all purposes.
 245 The disadvantage of
 246 .B GRND_RANDOM
 247 is that it can block.
 248 Furthermore, dealing with the partially fulfilled
 249 .BR getrandom ()
 250 requests that can occur when using
 251 .B GRND_RANDOM
 252 increases code complexity.
 253 .SS Emulating OpenBSD's getentropy()
 254 The
 255 .BR getentropy ()
 256 system call in OpenBSD can be emulated using the following
 257 function:
 258
 259 .in +4n
 260 .nf
 261 int
 262 getentropy(void *buf, size_t buflen)
 263 {
 264     int ret;
 265
 266     if (buflen > 256)
 267         goto failure;
 268     ret = getrandom(buf, buflen, 0);
 269     if (ret < 0)
 270         return ret;
 271     if (ret == buflen)
 272         return 0;
 273 failure:
 274     errno = EIO;
 275     return \-1;
 276 }
 277 .fi
 278 .in
 279 .SH BUGS
 280 As of Linux 3.19, the following bug exists:
 281 .\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16
 282 .IP * 3
 283 Depending on CPU load,
 284 .BR getrandom ()
 285 does not react to interrupts before reading all bytes requested.
 286 .SH SEE ALSO
 287 .BR random (4),
 288 .BR urandom (4)