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.\" 18e9ac2743SConrad Meyer.\" $FreeBSD$ 19e9ac2743SConrad Meyer.\" 20e9ac2743SConrad Meyer.Dd February 24, 2018 21e9ac2743SConrad Meyer.Dt GETENTROPY 3 22e9ac2743SConrad Meyer.Os 23e9ac2743SConrad Meyer.Sh NAME 24e9ac2743SConrad Meyer.Nm getentropy 25e9ac2743SConrad Meyer.Nd get entropy 26e9ac2743SConrad Meyer.Sh LIBRARY 27e9ac2743SConrad Meyer.Lb libc 28e9ac2743SConrad Meyer.Sh SYNOPSIS 29e9ac2743SConrad Meyer.In unistd.h 30e9ac2743SConrad Meyer.Ft int 31e9ac2743SConrad Meyer.Fn getentropy "void *buf" "size_t buflen" 32e9ac2743SConrad Meyer.Sh DESCRIPTION 33e9ac2743SConrad Meyer.Fn getentropy 34e9ac2743SConrad Meyerfills a buffer with high-quality random data. 35e9ac2743SConrad Meyer.Pp 36e9ac2743SConrad MeyerThe maximum 37e9ac2743SConrad Meyer.Fa buflen 38e9ac2743SConrad Meyerpermitted is 256 bytes. 39e9ac2743SConrad Meyer.Pp 40e9ac2743SConrad MeyerIf it does not produce an error, 41e9ac2743SConrad Meyer.Fn getentropy 42e9ac2743SConrad Meyeralways provides the requested number of bytes of random data. 43e9ac2743SConrad Meyer.Pp 44e9ac2743SConrad MeyerSimilar to reading from 45e9ac2743SConrad Meyer.Pa /dev/urandom 46e9ac2743SConrad Meyerjust after boot, 47e9ac2743SConrad Meyer.Fn getentropy 48e9ac2743SConrad Meyermay block until the system has collected enough entropy to seed the CSPRNG. 49e9ac2743SConrad Meyer.Sh IMPLEMENTATION NOTES 50e9ac2743SConrad MeyerThe 51e9ac2743SConrad Meyer.Fn getentropy 52e9ac2743SConrad Meyerfunction is implemented using 53e9ac2743SConrad Meyer.Xr getrandom 2 . 54e9ac2743SConrad Meyer.Sh RETURN VALUES 55e9ac2743SConrad Meyer.Rv -std 56e9ac2743SConrad Meyer.Sh ERRORS 57e9ac2743SConrad Meyer.Fn getentropy 58e9ac2743SConrad Meyerwill succeed unless: 59e9ac2743SConrad Meyer.Bl -tag -width Er 60e9ac2743SConrad Meyer.It Bq Er EFAULT 61e9ac2743SConrad MeyerThe 62e9ac2743SConrad Meyer.Fa buf 63e9ac2743SConrad Meyerparameter points to an 64e9ac2743SConrad Meyerinvalid address. 65e9ac2743SConrad Meyer.It Bq Er EIO 66e9ac2743SConrad MeyerToo many bytes requested, or some other fatal error occurred. 67e9ac2743SConrad Meyer.El 68e9ac2743SConrad Meyer.Sh SEE ALSO 69e9ac2743SConrad Meyer.Xr getrandom 2 , 70*eca1933aSEnji Cooper.Xr arc4random 3 , 71e9ac2743SConrad Meyer.Xr random 4 72e9ac2743SConrad Meyer.Sh STANDARDS 73e9ac2743SConrad Meyer.Fn getentropy 74e9ac2743SConrad Meyeris non-standard. 75e9ac2743SConrad MeyerIt is present on 76e9ac2743SConrad Meyer.Ox 77e9ac2743SConrad Meyerand Linux. 78e9ac2743SConrad Meyer.Sh HISTORY 79e9ac2743SConrad MeyerThe 80e9ac2743SConrad Meyer.Fn getentropy 81e9ac2743SConrad Meyerfunction appeared in 82e9ac2743SConrad Meyer.Ox 5.6 . 83e9ac2743SConrad MeyerThe 84e9ac2743SConrad Meyer.Fx 85e9ac2743SConrad Meyerlibc compatibility shim first appeared in 86e9ac2743SConrad Meyer.Fx 12.0 . 87