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