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, 0 insertions, 203 deletions
diff --git a/static/freebsd/man4/random.4 3.html b/static/freebsd/man4/random.4 3.html deleted file mode 100644 index 58dfa2bf..00000000 --- a/static/freebsd/man4/random.4 3.html +++ /dev/null @@ -1,203 +0,0 @@ -<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> |