Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RANDOM(4)	       FreeBSD Kernel Interfaces Manual		     RANDOM(4)

NAME
     random -- the entropy device

SYNOPSIS
     options RANDOM_LOADABLE
     options RANDOM_ENABLE_ETHER
     options RANDOM_ENABLE_UMA

DESCRIPTION
     The random	device returns an endless supply of random bytes when read.

     The generator will	start in an unseeded state, and	will block reads until
     it	is seeded for the first	time.

     To	provide	prompt access to the random device at boot time, FreeBSD auto-
     matically persists	some entropy data in /boot/entropy for the loader to
     provide to	the kernel.  Additional	entropy	is regularly saved in
     /var/db/entropy.  This saved entropy is sufficient	to unblock the random
     device on devices with writeable media.

     Embedded applications without writable media must determine their own
     scheme for	re-seeding the random device on	boot, or accept	that the de-
     vice will remain unseeded and block reads indefinitely.  See SECURITY
     CONSIDERATIONS for	more detail.

     In	addition to read(2), the direct	output of the abstract kernel entropy
     device can	be read	with getrandom(2), getentropy(3), or the sysctl(8)
     pseudo-variable kern.arandom.

     To	see the	current	settings of the	software random	device,	use the	com-
     mand line:

	   sysctl kern.random

     which results in something	like:

	   kern.random.block_seeded_status: 0
	   kern.random.fortuna.minpoolsize: 64
	   kern.random.harvest.mask_symbolic: ENABLEDSOURCE,[DISABLEDSOURCE],...,CACHED
	   kern.random.harvest.mask_bin: 00000010000000111011111
	   kern.random.harvest.mask: 66015
	   kern.random.use_chacha20_cipher: 0
	   kern.random.random_sources: 'Intel Secure Key RNG'
	   kern.random.initial_seeding.bypass_before_seeding: 1
	   kern.random.initial_seeding.read_random_bypassed_before_seeding: 0
	   kern.random.initial_seeding.arc4random_bypassed_before_seeding: 0
	   kern.random.initial_seeding.disable_bypass_warnings:	0

     Other than	kern.random.block_seeded_status,
     kern.random.fortuna.minpoolsize, and kern.random.harvest.mask, all	set-
     tings are read-only.

     The kern.random.fortuna.minpoolsize sysctl	is used	to set the seed
     threshold.	 A smaller number gives	a faster seed, but a less secure one.
     In	practice, values between 64 and	256 are	acceptable.

     The kern.random.harvest.mask bitmask is used to select the	possible en-
     tropy sources.  A 0 (zero)	value means the	corresponding source is	not
     considered	as an entropy source.  Set the bit to 1	(one) if you wish to
     use that source.  The kern.random.harvest.mask_bin	and
     kern.random.harvest.mask_symbolic sysctls can be used to confirm settings
     in	a human	readable form.	Disabled items in the latter item are listed
     in	square brackets.  See random_harvest(9)	for more on the	harvesting of
     entropy.

FILES
     /dev/random

     /dev/urandom

DIAGNOSTICS
     The following tunables are	related	to initial seeding of the random de-
     vice:

     kern.random.initial_seeding.bypass_before_seeding
       Defaults	to 1 (on).  When set, the system will bypass the random	device
       prior to	initial	seeding.  On is	unsafe,	but provides availability on
       many systems that lack early sources of entropy,	or cannot load
       /boot/entropy sufficiently early	in boot	for random consumers.  When
       unset (0), the system will block	read_random(9) and arc4random(9) re-
       quests if and until the random device is	initially seeded.

     kern.random.initial_seeding.disable_bypass_warnings
       Defaults	to 0 (off).  When set non-zero,	disables warnings in dmesg
       when the	random device is bypassed.

     The following read-only sysctl(8) variables allow programmatic diagnostic
     of	whether	random device bypass occurred during boot.  If they are	set
     (non-zero), the specific functional unit bypassed the strong random de-
     vice output and either produced no	output (read_random(9))	or seeded it-
     self with minimal,	non-cryptographic entropy (arc4random(9)).

     +o	 kern.random.initial_seeding.read_random_bypassed_before_seeding

     +o	 kern.random.initial_seeding.arc4random_bypassed_before_seeding

SEE ALSO
     getrandom(2), arc4random(3), getentropy(3), random(3), sysctl(8),
     random(9)

     Ferguson, Schneier, and Kohno, Cryptography Engineering, Wiley, ISBN
     978-0-470-47424-2.

HISTORY
     A random device appeared in FreeBSD 2.2.  The implementation was changed
     to	the Yarrow algorithm in	FreeBSD	5.0.  In FreeBSD 11.0, the Fortuna al-
     gorithm was introduced as the default.  In	FreeBSD	12.0, Yarrow was re-
     moved entirely.

AUTHORS
     The current random	code was authored by Mark R V Murray, with significant
     contributions from	many people.

     The Fortuna algorithm was designed	by Niels Ferguson, Bruce Schneier, and
     Tadayoshi Kohno.

CAVEATS
     When options RANDOM_LOADABLE is enabled, the /dev/random device is	not
     created until an "algorithm module" is loaded.  The only module built by
     default is	random_fortuna.	 Loadable random modules are less efficient
     than their	compiled-in equivalents.  This is because some functions must
     be	locked against load and	unload events, and also	must be	indirect calls
     to	allow for removal.

     When options RANDOM_ENABLE_UMA is enabled,	the /dev/random	device will
     obtain entropy from the zone allocator.  This is a	very high rate source
     with significant performance impact.  Therefore, it is disabled by	de-
     fault.

     When options RANDOM_ENABLE_ETHER is enabled, the random device will ob-
     tain entropy from mbuf structures passing through the network stack.
     This source is both extremely expensive and a poor	source of entropy, so
     it	is disabled by default.

SECURITY CONSIDERATIONS
     The initial seeding of random number generators is	a bootstrapping	prob-
     lem that needs very careful attention.  When writable media is available,
     the Fortuna paper describes a robust system for rapidly reseeding the de-
     vice.

     In	some embedded cases, it	may be difficult to find enough	randomness to
     seed a random number generator until a system is fully operational.  In
     these cases, is the responsibility	of the system architect	to ensure that
     blocking is acceptable, or	that the random	device is seeded.  (This ad-
     vice does not apply to typical consumer systems.)

     To	emulate	embedded systems, developers may set the
     kern.random.block_seeded_status tunable to	1 to verify boot does not re-
     quire early availability of the random device.

FreeBSD	13.0			April 19, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | FILES | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHORS | CAVEATS | SECURITY CONSIDERATIONS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=random&sektion=4&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help