[apple/xnu.git] / bsd / man / man2 / getentropy.2

.\" Copyright (c) 2014 Theo de Raadt
.\" Copyright (c) 2015 Apple Inc. All rights reserved.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd October 2 2015
.Dt GETENTROPY 2
.Os
.Sh NAME
.Nm getentropy
.Nd get entropy
.Sh SYNOPSIS
.In sys/random.h
.Ft int
.Fn getentropy "void *buf" "size_t buflen"
.Sh DESCRIPTION
.Fn getentropy
fills a buffer with random data, which can be used
as input for process-context pseudorandom generators like
.Xr arc4random 3 .
.Pp
The maximum buffer size permitted is 256 bytes.
If
.Fa buflen
exceeds this, an error of
.Er EIO
will be indicated.
.Pp
.Fn getentropy
should be used as a replacement for
.Xr random 4
when random data derived directly from the kernel random byte generator is required.
Unlike the
.Xr random 4
pseudo-devices, it is not vulnerable to file descriptor exhaustion attacks
and is available when sandboxed or in a chroot, making it more reliable for security-critical applications.
.Pp
However, it should be noted that
.Fn getentropy
is primarily intended for use in the construction and seeding of userspace PRNGs like
.Xr arc4random 3
or
.Xr CC_crypto 3 .
Clients who simply require random data should use
.Xr arc4random 3 ,
.Fn CCRandomGenerateBytes
from
.Xr CC_crypto 3 ,
or
.Fn SecRandomCopyBytes
from the Security framework instead of
.Fn getentropy
or
.Xr random 4
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
.Fn getentropy
will succeed unless:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa buf
parameter points to an
invalid address.
.It Bq Er EIO
Too many bytes requested, or some other fatal error occurred.
.El
.Sh SEE ALSO
.Xr arc4random 3
.Xr CC_crypto 3
.Xr random 4
.Sh HISTORY
The
.Fn getentropy
function appeared in
OSX 10.12
Commit	Line	Data
39037602 A	1	.\" Copyright (c) 2014 Theo de Raadt
	2	.\" Copyright (c) 2015 Apple Inc. All rights reserved.
	3	.\"
	4	.\" Permission to use, copy, modify, and distribute this software for any
	5	.\" purpose with or without fee is hereby granted, provided that the above
	6	.\" copyright notice and this permission notice appear in all copies.
	7	.\"
	8	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
	9	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	10	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
	11	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	12	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
	13	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
	14	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	15	.\"
	16	.Dd October 2 2015
	17	.Dt GETENTROPY 2
	18	.Os
	19	.Sh NAME
	20	.Nm getentropy
	21	.Nd get entropy
	22	.Sh SYNOPSIS
	23	.In sys/random.h
	24	.Ft int
	25	.Fn getentropy "void *buf" "size_t buflen"
	26	.Sh DESCRIPTION
	27	.Fn getentropy
	28	fills a buffer with random data, which can be used
	29	as input for process-context pseudorandom generators like
	30	.Xr arc4random 3 .
	31	.Pp
	32	The maximum buffer size permitted is 256 bytes.
	33	If
	34	.Fa buflen
	35	exceeds this, an error of
	36	.Er EIO
	37	will be indicated.
	38	.Pp
	39	.Fn getentropy
	40	should be used as a replacement for
	41	.Xr random 4
	42	when random data derived directly from the kernel random byte generator is required.
	43	Unlike the
	44	.Xr random 4
	45	pseudo-devices, it is not vulnerable to file descriptor exhaustion attacks
	46	and is available when sandboxed or in a chroot, making it more reliable for security-critical applications.
	47	.Pp
	48	However, it should be noted that
	49	.Fn getentropy
	50	is primarily intended for use in the construction and seeding of userspace PRNGs like
	51	.Xr arc4random 3
	52	or
	53	.Xr CC_crypto 3 .
	54	Clients who simply require random data should use
	55	.Xr arc4random 3 ,
	56	.Fn CCRandomGenerateBytes
	57	from
	58	.Xr CC_crypto 3 ,
	59	or
	60	.Fn SecRandomCopyBytes
	61	from the Security framework instead of
	62	.Fn getentropy
	63	or
	64	.Xr random 4
65	.Sh RETURN VALUES
66	.Rv -std
67	.Sh ERRORS
68	.Fn getentropy
69	will succeed unless:
70	.Bl -tag -width Er
71	.It Bq Er EINVAL
72	The
73	.Fa buf
74	parameter points to an
75	invalid address.
76	.It Bq Er EIO
77	Too many bytes requested, or some other fatal error occurred.
78	.El
79	.Sh SEE ALSO
80	.Xr arc4random 3
81	.Xr CC_crypto 3
82	.Xr random 4
83	.Sh HISTORY
84	The
85	.Fn getentropy
86	function appeared in
87	OSX 10.12