lib/libc/gen/getentropy.3

   1 .\"     $OpenBSD: getentropy.2,v 1.8 2015/01/31 00:20:12 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org>
   4 .\" Copyright (c) 2014 Theo de Raadt
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd February 24, 2018
  19 .Dt GETENTROPY 3
  20 .Os
  21 .Sh NAME
  22 .Nm getentropy
  23 .Nd get entropy
  24 .Sh LIBRARY
  25 .Lb libc
  26 .Sh SYNOPSIS
  27 .In unistd.h
  28 .Ft int
  29 .Fn getentropy "void *buf" "size_t buflen"
  30 .Sh DESCRIPTION
  31 .Fn getentropy
  32 fills a buffer with high-quality random data.
  33 .Pp
  34 The maximum
  35 .Fa buflen
  36 permitted is 256 bytes.
  37 .Pp
  38 If it does not produce an error,
  39 .Fn getentropy
  40 always provides the requested number of bytes of random data.
  41 .Pp
  42 Similar to reading from
  43 .Pa /dev/urandom
  44 just after boot,
  45 .Fn getentropy
  46 may block until the system has collected enough entropy to seed the CSPRNG.
  47 .Sh IMPLEMENTATION NOTES
  48 The
  49 .Fn getentropy
  50 function is implemented using
  51 .Xr getrandom 2 .
  52 .Sh RETURN VALUES
  53 .Rv -std
  54 .Sh ERRORS
  55 .Fn getentropy
  56 will succeed unless:
  57 .Bl -tag -width Er
  58 .It Bq Er EFAULT
  59 The
  60 .Fa buf
  61 parameter points to an
  62 invalid address.
  63 .It Bq Er EIO
  64 Too many bytes requested, or some other fatal error occurred.
  65 .El
  66 .Sh SEE ALSO
  67 .Xr getrandom 2 ,
  68 .Xr arc4random 3 ,
  69 .Xr random 4
  70 .Sh STANDARDS
  71 .Fn getentropy
  72 is non-standard.
  73 It is present on
  74 .Ox
  75 and Linux.
  76 .Sh HISTORY
  77 The
  78 .Fn getentropy
  79 function appeared in
  80 .Ox 5.6 .
  81 The
  82 .Fx
  83 libc compatibility shim first appeared in
  84 .Fx 12.0 .