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