1.\" $NetBSD: getentropy.3,v 1.8 2024/08/28 14:08:48 riastradh 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 August 28, 2024 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 46The 47.Nm 48function fills 49.Fa buf 50with exactly 51.Fa buflen 52independent uniform random bytes derived from the system's entropy 53pool. 54.Pp 55The output of 56.Nm 57is meant to be unpredictable to an adversary and fit for use in 58cryptography. 59See 60.Sx CAVEATS 61below. 62.Pp 63.Nm 64is meant for seeding random number generators, not for direct use by 65applications; most applications should use 66.Xr arc4random 3 . 67.Pp 68.Fa buflen 69must be at most 256. 70.Sh RETURN VALUES 71.Rv -std getentropy 72.Sh ERRORS 73.Nm 74will succeed unless: 75.Bl -tag -width Er 76.It Bq Er EFAULT 77The 78.Fa buf 79argument points to an invalid memory address. 80.It Bq Er EINVAL 81More than 256 bytes were requested. 82.El 83.Sh CAVEATS 84Security can only be guaranteed relative to whatever unpredictable 85physical processes or secret seed material are available to the system; 86see 87.Xr entropy 7 . 88.Pp 89On systems which have no hardware random number generator and which 90have not had secret seed material loaded, 91.Nx 92makes a reasonable effort to incorporate samples from various physical 93processes available to it that might be unpredictable from random 94jitter in timing. 95.Pp 96However, the 97.Nm 98interface alone can make no security guarantees without a physical 99system configuration that includes random number generation hardware or 100secret seed material from such hardware on another machine. 101.Pp 102.Nx 103attempts to reseed the system entropy pool when it has detected the 104system has been cloned as a guest in a virtual machine, so that 105subsequent calls to 106.Nm 107in the clones yield independent outputs. 108However, this relies on the virtual machine host to notify the guest, 109e.g. through the 110.Xr acpivmgenid 4 111device, and even so there is an unavoidable small window of time 112between when the virtual machine is actually cloned and when the system 113is reseeded during which 114.Nm 115may yield identical outputs in the clones. 116.Sh SEE ALSO 117.Xr arc4random 3 , 118.Xr rnd 4 , 119.Xr entropy 7 120.Sh STANDARDS 121The 122.Nm 123function conforms to 124.St -p1003.1-2024 . 125.Sh HISTORY 126The 127.Nm 128function first appeared in 129.Ox 5.6 , 130then in 131.Fx 12.0 , 132and in 133.Nx 10.0 . 134