diff options
Diffstat (limited to 'static/freebsd/man4/random.4 3.html')
| -rw-r--r-- | static/freebsd/man4/random.4 3.html | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/static/freebsd/man4/random.4 3.html b/static/freebsd/man4/random.4 3.html new file mode 100644 index 00000000..58dfa2bf --- /dev/null +++ b/static/freebsd/man4/random.4 3.html @@ -0,0 +1,203 @@ +<table class="head"> + <tr> + <td class="head-ltitle">RANDOM(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">RANDOM(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">random</code> — <span class="Nd">the + entropy device</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">options RANDOM_LOADABLE</code> + <br/> + <code class="Cd">options RANDOM_ENABLE_ETHER</code> + <br/> + <code class="Cd">options RANDOM_ENABLE_TPM</code> + <br/> + <code class="Cd">options RANDOM_ENABLE_UMA</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">random</code> device returns an endless + supply of random bytes when read.</p> +<p class="Pp" id="unseeded">The generator will start in an + <a class="permalink" href="#unseeded"><i class="Em">unseeded</i></a> state, + and will block reads until it is seeded for the first time.</p> +<p class="Pp">To provide prompt access to the random device at boot time, + <span class="Ux">FreeBSD</span> automatically saves some entropy data in + <span class="Pa">/boot/entropy</span> for the <a class="Xr">loader(8)</a> to + provide to the kernel. Additional entropy is regularly saved in + <span class="Pa">/var/db/entropy</span>. This saved entropy is sufficient to + unblock the random device on devices with writeable media.</p> +<p class="Pp">Embedded applications without writable media must determine their + own scheme for re-seeding the random device on boot, or accept that the + device will remain unseeded and block reads indefinitely. See + <a class="Sx" href="#SECURITY_CONSIDERATIONS">SECURITY CONSIDERATIONS</a> + for more detail.</p> +<p class="Pp">In addition to <a class="Xr">read(2)</a>, the direct output of the + abstract kernel entropy device can be read with + <a class="Xr">getrandom(2)</a>, <a class="Xr">getentropy(3)</a>, or the + <a class="Xr">sysctl(8)</a> pseudo-variable + <var class="Va">kern.arandom</var>.</p> +<p class="Pp">To see the current settings of the software + <code class="Nm">random</code> device, use the command line:</p> +<p class="Pp"></p> +<div class="Bd Bd-indent"><code class="Li">sysctl kern.random</code></div> +<p class="Pp">which results in something like:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>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</pre> +</div> +<p class="Pp">Other than <var class="Va">kern.random.block_seeded_status</var>, + <var class="Va">kern.random.fortuna.minpoolsize</var>, and + <var class="Va">kern.random.harvest.mask</var>, all settings are read-only + via <a class="Xr">sysctl(8)</a>.</p> +<p class="Pp">The <span class="Pa">kern.random.fortuna.minpoolsize</span> 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.</p> +<p class="Pp">The <var class="Va">kern.random.harvest.mask</var> bitmask is used + to select the possible entropy 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 + <var class="Va">kern.random.harvest.mask_bin</var> and + <var class="Va">kern.random.harvest.mask_symbolic</var> sysctls can be used + to confirm settings in a human readable form. Disabled items in the latter + are listed in square brackets. See <a class="Xr">random_harvest(9)</a> for + more on the harvesting of entropy.</p> +<p class="Pp">The <var class="Va">kern.random.nist_healthtest_enabled</var> + tunable can be used to enable the entropy source health tests outlined in + section 4 of NIST Special Publication 800-90B. When enabled, all entropy + sources will be subject to the repetition count and adaptive proportion + tests described in that document. If one of the tests fails, the source will + be disabled, i.e., all subsequent entropy samples from that source will be + discarded. The implementation performs startup testing, during which entropy + sources are discarded.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag"> + <dt><span class="Pa">/dev/random</span></dt> + <dd style="width: auto;"> </dd> + <dt><span class="Pa">/dev/urandom</span></dt> + <dd style="width: auto;"> </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">The following tunables are related to initial seeding of the + <code class="Nm">random</code> device:</p> +<dl class="Bl-tag"> + <dt id="kern.random.initial_seeding.bypass_before_seeding"><var class="Va">kern.random.initial_seeding.bypass_before_seeding</var></dt> + <dd>Defaults to 1 (on). When set, the system will bypass the + <code class="Nm">random</code> device prior to initial seeding. On is + <a class="permalink" href="#unsafe"><i class="Em" id="unsafe">unsafe</i></a>, + but provides availability on many systems that lack early sources of + entropy, or cannot load <span class="Pa">/boot/entropy</span> sufficiently + early in boot for <code class="Nm">random</code> consumers. When unset + (0), the system will block <a class="Xr">read_random(9)</a> and + <a class="Xr">arc4random(9)</a> requests if and until the + <code class="Nm">random</code> device is initially seeded.</dd> + <dt id="kern.random.initial_seeding.disable_bypass_warnings"><var class="Va">kern.random.initial_seeding.disable_bypass_warnings</var></dt> + <dd>Defaults to 0 (off). When set non-zero, disables warnings in dmesg when + the <code class="Nm">random</code> device is bypassed.</dd> +</dl> +<p class="Pp">The following read-only <a class="Xr">sysctl(8)</a> variables + allow programmatic diagnostic of whether <code class="Nm">random</code> + device bypass occurred during boot. If they are set (non-zero), the specific + functional unit bypassed the strong <code class="Nm">random</code> device + output and either produced no output (<a class="Xr">read_random(9)</a>) or + seeded itself with minimal, non-cryptographic entropy + (<a class="Xr">arc4random(9)</a>).</p> +<ul class="Bl-bullet"> + <li id="kern.random.initial_seeding.read_random_bypassed_before_seeding"><var class="Va">kern.random.initial_seeding.read_random_bypassed_before_seeding</var></li> + <li id="kern.random.initial_seeding.arc4random_bypassed_before_seeding"><var class="Va">kern.random.initial_seeding.arc4random_bypassed_before_seeding</var></li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">getrandom(2)</a>, <a class="Xr">arc4random(3)</a>, + <a class="Xr">getentropy(3)</a>, <a class="Xr">random(3)</a>, + <a class="Xr">sysctl(8)</a>, <a class="Xr">random(9)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Ferguson</span>, + <span class="RsA">Schneier</span>, and <span class="RsA">Kohno</span>, + <i class="RsB">Cryptography Engineering</i>, <i class="RsI">Wiley</i>, + <span class="RsO">ISBN 978-0-470-47424-2</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">A <code class="Nm">random</code> device appeared in + <span class="Ux">FreeBSD 2.2</span>. The implementation was changed to the + <a class="permalink" href="#Yarrow"><i class="Em" id="Yarrow">Yarrow + algorithm in</i></a> <span class="Ux">FreeBSD 5.0</span>. In + <span class="Ux">FreeBSD 11.0</span>, the Fortuna algorithm was introduced + as the default. In <span class="Ux">FreeBSD 12.0</span>, Yarrow was removed + entirely.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The current <code class="Nm">random</code> code was authored by + <span class="An">Mark R V Murray</span>, with significant contributions from + many people.</p> +<p class="Pp">The <i class="Em">Fortuna</i> algorithm was designed by + <span class="An">Niels Ferguson</span>, <span class="An">Bruce + Schneier</span>, and <span class="An">Tadayoshi Kohno</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">When <code class="Cd">options RANDOM_LOADABLE</code> is enabled, + the <span class="Pa">/dev/random</span> device is not created until an + "algorithm module" is loaded. The only module built by default is + <a class="permalink" href="#random_fortuna"><i class="Em" id="random_fortuna">random_fortuna</i></a>. + 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.</p> +<p class="Pp">When <code class="Cd">options RANDOM_ENABLE_UMA</code> is enabled, + the <span class="Pa">/dev/random</span> device will obtain entropy from the + zone allocator. This is a very high rate source with significant performance + impact. Therefore, it is disabled by default.</p> +<p class="Pp">When <code class="Cd">options RANDOM_ENABLE_ETHER</code> is + enabled, the <code class="Nm">random</code> device will obtain entropy from + <var class="Vt">mbuf</var> structures passing through the network stack. + This source is both extremely expensive and a poor source of entropy, so it + is disabled by default.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SECURITY_CONSIDERATIONS"><a class="permalink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +<p class="Pp">The initial seeding of random number generators is a bootstrapping + problem that needs very careful attention. When writable media is available, + the <i class="Em">Fortuna</i> paper describes a robust system for rapidly + reseeding the device.</p> +<p class="Pp">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 advice does not apply to typical consumer systems.)</p> +<p class="Pp">To emulate embedded systems, developers may set the + <var class="Va">kern.random.block_seeded_status</var> tunable to 1 to verify + boot does not require early availability of the + <code class="Nm">random</code> device.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 28, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |