[apple/xnu.git] / bsd / man / man4 / random.4

.Dd September 6, 2001
.Dt RANDOM 4
.Os Darwin
.Sh NAME
.Nm random
,
.Nm urandom
.Nd random data source devices.
.Sh SYNOPSIS
.Cd "pseudo-device random"
.Sh DESCRIPTION
The
.Nm
device produces uniformly distributed random byte values
of potentially high quality.
.Pp
To obtain random bytes, open
.Nm /dev/random
for reading and read from it.
.Pp
To add entropy to the random generation system, open
.Nm /dev/random
for writing and write data that you believe to be somehow random.
.Pp
.Nm /dev/urandom
is a compatibility nod to Linux. On Linux,
.Nm /dev/urandom
will produce lower quality output if the entropy pool drains, while
.Nm /dev/random
will prefer to block and wait for additional entropy to be collected.
With Yarrow, this choice and distinction is not necessary, and
the two devices behave identically. You may use either.
.Sh OPERATION
The
.Nm
device implements the
.Nm Yarrow
pseudo random number generator algorithm and maintains its entropy pool.
Addditional entropy is fed to the generator regularly by the
.Nm SecurityServer
daemon from random jitter measurements of the kernel.
.Nm SecurityServer
is also responsible for periodically saving some entropy to disk
and reloading it during startup to provide entropy in early system
operation.
.Pp
You may feed additional entropy to the generator by writing it to the
.Nm
device, though this is not required in a normal operating environment.
.Sh LIMITATIONS AND WARNINGS
.Nm Yarrow
is a fairly resilient algorithm, and is believed
to be resistant to non-root.
The quality of its output is however dependent on regular addition
of appropriate entropy. If the
.Nm SecurityServer
system daemon fails for any reason, output quality will suffer
over time without any explicit indication from the
.Nm
device itself.
.Pp
Paranoid programmers can counter-act this risk somewhat by collecting
entropy of their choice (e.g. from keystroke or mouse timings)
and seeding it into
.Nm
directly before obtaining important random numbers.
.Sh FILES
.Bl -tag -width /dev/urandom -compact
.It Pa /dev/random
.It Pa /dev/urandom
.El
.Sh HISTORY
A
.Nm
device appeared in Linux operating system.
Commit	Line	Data
9bccf70c A	1	.Dd September 6, 2001
	2	.Dt RANDOM 4
	3	.Os Darwin
	4	.Sh NAME
	5	.Nm random
	6	,
	7	.Nm urandom
	8	.Nd random data source devices.
	9	.Sh SYNOPSIS
	10	.Cd "pseudo-device random"
	11	.Sh DESCRIPTION
	12	The
	13	.Nm
	14	device produces uniformly distributed random byte values
	15	of potentially high quality.
	16	.Pp
	17	To obtain random bytes, open
	18	.Nm /dev/random
	19	for reading and read from it.
	20	.Pp
	21	To add entropy to the random generation system, open
	22	.Nm /dev/random
	23	for writing and write data that you believe to be somehow random.
	24	.Pp
	25	.Nm /dev/urandom
	26	is a compatibility nod to Linux. On Linux,
	27	.Nm /dev/urandom
	28	will produce lower quality output if the entropy pool drains, while
	29	.Nm /dev/random
	30	will prefer to block and wait for additional entropy to be collected.
	31	With Yarrow, this choice and distinction is not necessary, and
	32	the two devices behave identically. You may use either.
	33	.Sh OPERATION
	34	The
	35	.Nm
	36	device implements the
	37	.Nm Yarrow
	38	pseudo random number generator algorithm and maintains its entropy pool.
	39	Addditional entropy is fed to the generator regularly by the
	40	.Nm SecurityServer
	41	daemon from random jitter measurements of the kernel.
	42	.Nm SecurityServer
	43	is also responsible for periodically saving some entropy to disk
	44	and reloading it during startup to provide entropy in early system
	45	operation.
	46	.Pp
	47	You may feed additional entropy to the generator by writing it to the
	48	.Nm
	49	device, though this is not required in a normal operating environment.
	50	.Sh LIMITATIONS AND WARNINGS
	51	.Nm Yarrow
	52	is a fairly resilient algorithm, and is believed
	53	to be resistant to non-root.
	54	The quality of its output is however dependent on regular addition
	55	of appropriate entropy. If the
	56	.Nm SecurityServer
	57	system daemon fails for any reason, output quality will suffer
	58	over time without any explicit indication from the
	59	.Nm
	60	device itself.
	61	.Pp
	62	Paranoid programmers can counter-act this risk somewhat by collecting
	63	entropy of their choice (e.g. from keystroke or mouse timings)
	64	and seeding it into
65	.Nm
66	directly before obtaining important random numbers.
67	.Sh FILES
68	.Bl -tag -width /dev/urandom -compact
69	.It Pa /dev/random
70	.It Pa /dev/urandom
71	.El
72	.Sh HISTORY
73	A
74	.Nm
75	device appeared in Linux operating system.