1.\" $NetBSD: getentropy.3,v 1.6 2023/06/30 22:15:14 uwe Exp $ $ 2.\" 3.\" Copyright (c) 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Nia Alarie. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 28, 2023 31.Dt GETENTROPY 3 32.Os 33.Sh NAME 34.Nm getentropy 35.Nd generate uniform random seeds from system entropy for cryptography 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In unistd.h 40.Ft int 41.Fn getentropy "void *buf" "size_t buflen" 42.In limits.h 43.Pp 44.Li #define GETENTROPY_MAX 256 45.Sh DESCRIPTION 46.Pp 47The 48.Nm 49function fills 50.Fa buf 51with exactly 52.Fa buflen 53independent uniform random bytes derived from the system's entropy 54pool. 55.Pp 56The output of 57.Nm 58is meant to be unpredictable to an adversary and fit for use in 59cryptography. 60See 61.Sx CAVEATS 62below. 63.Pp 64.Nm 65is meant for seeding random number generators, not for direct use by 66applications; most applications should use 67.Xr arc4random 3 . 68.Pp 69.Fa buflen 70must be at most 256. 71.Sh RETURN VALUES 72.Rv -std getentropy 73.Sh ERRORS 74.Fn getentropy 75will succeed unless: 76.Bl -tag -width Er 77.It Bq Er EFAULT 78The 79.Fa buf 80argument points to an invalid memory address. 81.It Bq Er EINVAL 82More than 256 bytes were requested. 83.El 84.Sh CAVEATS 85Security can only be guaranteed relative to whatever unpredictable 86physical processes or secret seed material are available to the system; 87see 88.Xr entropy 7 . 89.Pp 90On systems which have no hardware random number generator and which 91have not had secret seed material loaded, 92.Nx 93makes a reasonable effort to incorporate samples from various physical 94processes available to it that might be unpredictable from random 95jitter in timing. 96.Pp 97However, the 98.Nm 99interface alone can make no security guarantees without a physical 100system configuration that includes random number generation hardware or 101secret seed material from such hardware on another machine. 102.Sh SEE ALSO 103.Xr arc4random 3 , 104.Xr rnd 4 , 105.Xr entropy 7 106.Sh STANDARDS 107The 108.Fn getentropy 109function is nonstandard. 110However, it is likely to be included in the next revision of POSIX. 111.Sh HISTORY 112The 113.Fn getentropy 114function first appeared in 115.Ox 5.6 , 116then in 117.Fx 12.0 , 118and in 119.Nx 10.0 . 120