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