bsd/man/man2/getentropy.2

   1 .\" Copyright (c) 2014 Theo de Raadt
   2 .\" Copyright (c) 2015 Apple Inc. All rights reserved.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd October 2 2015
  17 .Dt GETENTROPY 2
  18 .Os
  19 .Sh NAME
  20 .Nm getentropy
  21 .Nd get entropy
  22 .Sh SYNOPSIS
  23 .In sys/random.h
  24 .Ft int
  25 .Fn getentropy "void *buf" "size_t buflen"
  26 .Sh DESCRIPTION
  27 .Fn getentropy
  28 fills a buffer with random data, which can be used
  29 as input for process-context pseudorandom generators like
  30 .Xr arc4random 3 .
  31 .Pp
  32 The maximum buffer size permitted is 256 bytes.
  33 If
  34 .Fa buflen
  35 exceeds this, an error of
  36 .Er EIO
  37 will be indicated.
  38 .Pp
  39 .Fn getentropy
  40 should be used as a replacement for
  41 .Xr random 4
  42 when random data derived directly from the kernel random byte generator is required.
  43 Unlike the
  44 .Xr random 4
  45 pseudo-devices, it is not vulnerable to file descriptor exhaustion attacks
  46 and is available when sandboxed or in a chroot, making it more reliable for security-critical applications.
  47 .Pp
  48 However, it should be noted that
  49 .Fn getentropy
  50 is primarily intended for use in the construction and seeding of userspace PRNGs like
  51 .Xr arc4random 3
  52 or
  53 .Xr CC_crypto 3 .
  54 Clients who simply require random data should use
  55 .Xr arc4random 3 ,
  56 .Fn CCRandomGenerateBytes
  57 from
  58 .Xr CC_crypto 3 ,
  59 or
  60 .Fn SecRandomCopyBytes
  61 from the Security framework instead of
  62 .Fn getentropy
  63 or
  64 .Xr random 4
  65 .Sh RETURN VALUES
  66 .Rv -std
  67 .Sh ERRORS
  68 .Fn getentropy
  69 will succeed unless:
  70 .Bl -tag -width Er
  71 .It Bq Er EINVAL
  72 The
  73 .Fa buf
  74 parameter points to an
  75 invalid address.
  76 .It Bq Er EIO
  77 Too many bytes requested, or some other fatal error occurred.
  78 .El
  79 .Sh SEE ALSO
  80 .Xr arc4random 3
  81 .Xr CC_crypto 3
  82 .Xr random 4
  83 .Sh HISTORY
  84 The
  85 .Fn getentropy
  86 function appeared in
  87 OSX 10.12