diff options
Diffstat (limited to 'static/netbsd/man9/cprng.9 3.html')
| -rw-r--r-- | static/netbsd/man9/cprng.9 3.html | 218 |
1 files changed, 0 insertions, 218 deletions
diff --git a/static/netbsd/man9/cprng.9 3.html b/static/netbsd/man9/cprng.9 3.html deleted file mode 100644 index 4949c78c..00000000 --- a/static/netbsd/man9/cprng.9 3.html +++ /dev/null @@ -1,218 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">CPRNG(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">CPRNG(9)</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">cprng</code>, - <code class="Nm">cprng_strong_create</code>, - <code class="Nm">cprng_strong_destroy</code>, - <code class="Nm">cprng_strong</code>, - <code class="Nm">cprng_strong32</code>, - <code class="Nm">cprng_strong64</code>, <code class="Nm">cprng_fast</code>, - <code class="Nm">cprng_fast32</code>, <code class="Nm">cprng_fast64</code> - — <span class="Nd">cryptographic pseudorandom number - generators</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/cprng.h</a>></code></p> -<p class="Pp"><var class="Ft">cprng_strong_t *</var> - <br/> - <code class="Fn">cprng_strong_create</code>(<var class="Fa" style="white-space: nowrap;">const - char *name</var>, <var class="Fa" style="white-space: nowrap;">int - ipl</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">cprng_strong_destroy</code>(<var class="Fa" style="white-space: nowrap;">cprng_strong_t - *cprng</var>);</p> -<p class="Pp"><var class="Ft">size_t</var> - <br/> - <code class="Fn">cprng_strong</code>(<var class="Fa" style="white-space: nowrap;">cprng_strong_t - *cprng</var>, <var class="Fa" style="white-space: nowrap;">void *buf</var>, - <var class="Fa" style="white-space: nowrap;">size_t len</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">uint32_t</var> - <br/> - <code class="Fn">cprng_strong32</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> -<p class="Pp"><var class="Ft">uint64_t</var> - <br/> - <code class="Fn">cprng_strong64</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> -<p class="Pp"><var class="Ft">size_t</var> - <br/> - <code class="Fn">cprng_fast</code>(<var class="Fa" style="white-space: nowrap;">void - *buf</var>, <var class="Fa" style="white-space: nowrap;">size_t - len</var>);</p> -<p class="Pp"><var class="Ft">uint32_t</var> - <br/> - <code class="Fn">cprng_fast32</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> -<p class="Pp"><var class="Ft">uint64_t</var> - <br/> - <code class="Fn">cprng_fast64</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> -<div class="Bd Pp Li"> -<pre>#define CPRNG_MAX_LEN 524288</pre> -</div> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">cprng</code> family of functions provide - cryptographic pseudorandom number generators automatically seeded from the - kernel entropy pool. All applications in the kernel requiring random data or - random choices should use the <code class="Nm">cprng_strong</code> family of - functions, unless performance constraints demand otherwise.</p> -<p class="Pp">The <code class="Nm">cprng_fast</code> family of functions may be - used in applications that can tolerate exposure of past random data, such as - initialization vectors or transaction ids that are sent over the internet - anyway, if the applications require higher throughput or lower per-request - latency than the <code class="Nm">cprng_strong</code> family of functions - provide. If in doubt, choose <code class="Nm">cprng_strong</code>.</p> -<p class="Pp" id="cprng_strong_create">A single instance of the fast generator - serves the entire kernel. A well-known instance of the strong generator, - <code class="Dv">kern_cprng</code>, may be used by any in-kernel caller, but - separately seeded instances of the strong generator can also be created by - calling - <a class="permalink" href="#cprng_strong_create"><code class="Fn">cprng_strong_create</code></a>().</p> -<p class="Pp" id="cprng_strong_create~2">The <code class="Nm">cprng</code> - functions may be used in soft interrupt context, except for - <a class="permalink" href="#cprng_strong_create~2"><code class="Fn">cprng_strong_create</code></a>() - and <code class="Fn">cprng_strong_destroy</code>() which are allowed only at - <code class="Dv">IPL_NONE</code> in thread context; see - <a class="Xr">spl(9)</a>.</p> -<p class="Pp">The <code class="Nm">cprng</code> functions replace the legacy - <a class="Xr">arc4random(9)</a> and <a class="Xr">rnd_extract_data(9)</a> - functions.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> -<dl class="Bl-tag"> - <dt id="cprng_strong_create~3"><a class="permalink" href="#cprng_strong_create~3"><code class="Fn">cprng_strong_create</code></a>(<var class="Fa">name</var>, - <var class="Fa">ipl</var>, <var class="Fa">flags</var>)</dt> - <dd>Create an instance of the cprng_strong generator. This generator currently - implements the NIST SP 800-90A Hash_DRBG with SHA-256 as the hash - function. - <p class="Pp">The <var class="Fa">name</var> argument is used to - “personalize” the Hash_DRBG according to the standard, so - that its initial state will depend both on seed material from the - entropy pool and also on the personalization string (name).</p> - <p class="Pp">The <var class="Fa">ipl</var> argument specifies the interrupt - priority level for the mutex which will serialize access to the new - instance of the generator (see <a class="Xr">spl(9)</a>), and must be no - higher than <code class="Dv">IPL_SOFTSERIAL</code>.</p> - <p class="Pp">The <var class="Fa">flags</var> argument must be zero.</p> - <p class="Pp">Creation will succeed even if full entropy for the generator - is not available. In this case, the first request to read from the - generator may cause reseeding.</p> - <p class="Pp" id="cprng_strong_create~4"><a class="permalink" href="#cprng_strong_create~4"><code class="Fn">cprng_strong_create</code></a>() - may sleep to allocate memory.</p> - </dd> - <dt><code class="Fn">cprng_strong_destroy</code>(<var class="Fa">cprng</var>)</dt> - <dd>Destroy <var class="Fa">cprng</var>. - <p class="Pp" id="cprng_strong_destroy"><a class="permalink" href="#cprng_strong_destroy"><code class="Fn">cprng_strong_destroy</code></a>() - may sleep.</p> - </dd> - <dt id="cprng_strong"><a class="permalink" href="#cprng_strong"><code class="Fn">cprng_strong</code></a>(<var class="Fa">cprng</var>, - <var class="Fa">buf</var>, <var class="Fa">len</var>, - <var class="Fa">flags</var>)</dt> - <dd>Fill memory location <var class="Fa">buf</var> with up to - <var class="Fa">len</var> bytes from the generator - <var class="Fa">cprng</var>, and return the number of bytes. - <var class="Fa">len</var> must be at most - <code class="Dv">CPRNG_MAX_LEN</code>. <var class="Fa">flags</var> must be - zero.</dd> - <dt><code class="Fn">cprng_strong32</code>()</dt> - <dd>Generate 32 bits using the <code class="Dv">kern_cprng</code> strong - generator. - <p class="Pp" id="cprng_strong32"><a class="permalink" href="#cprng_strong32"><code class="Fn">cprng_strong32</code></a>() - does not sleep.</p> - </dd> - <dt><code class="Fn">cprng_strong64</code>()</dt> - <dd>Generate 64 bits using the <code class="Dv">kern_cprng</code> strong - generator. - <p class="Pp" id="cprng_strong64"><a class="permalink" href="#cprng_strong64"><code class="Fn">cprng_strong64</code></a>() - does not sleep.</p> - </dd> - <dt><code class="Fn">cprng_fast</code>(<var class="Fa">buf</var>, - <var class="Fa">len</var>)</dt> - <dd>Fill memory location <var class="Fa">buf</var> with - <var class="Fa">len</var> bytes from the fast generator. - <p class="Pp" id="cprng_fast"><a class="permalink" href="#cprng_fast"><code class="Fn">cprng_fast</code></a>() - does not sleep.</p> - </dd> - <dt><code class="Fn">cprng_fast32</code>()</dt> - <dd>Generate 32 bits using the fast generator. - <p class="Pp" id="cprng_fast32"><a class="permalink" href="#cprng_fast32"><code class="Fn">cprng_fast32</code></a>() - does not sleep.</p> - </dd> - <dt><code class="Fn">cprng_fast64</code>()</dt> - <dd>Generate 64 bits using the fast generator. - <p class="Pp" id="cprng_fast64"><a class="permalink" href="#cprng_fast64"><code class="Fn">cprng_fast64</code></a>() - does not sleep.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SECURITY_MODEL"><a class="permalink" href="#SECURITY_MODEL">SECURITY - MODEL</a></h1> -<p class="Pp">The <code class="Nm">cprng</code> family of functions provide the - following security properties:</p> -<ul class="Bl-bullet Bd-indent"> - <li>An attacker who has seen some outputs of any of the - <code class="Nm">cprng</code> functions cannot predict past or future - unseen outputs.</li> - <li>An attacker who has compromised kernel memory cannot predict past outputs - of the <code class="Nm">cprng_strong</code> functions. However, such an - attacker may be able to predict past outputs of the - <code class="Nm">cprng_fast</code> functions.</li> -</ul> -<p class="Pp">The second property is sometimes called “backtracking - resistance”, “forward secrecy”, or “key - erasure” in the cryptography literature. The - <code class="Nm">cprng_strong</code> functions provide backtracking - resistance; the <code class="Nm">cprng_fast</code> functions do not.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE - REFERENCES</a></h1> -<p class="Pp">The <code class="Nm">cprng_strong</code> functions are implemented - in <span class="Pa">sys/kern/subr_cprng.c</span>, and use the NIST SP - 800-90A Hash_DRBG implementation in - <span class="Pa">sys/crypto/nist_hash_drbg</span>. The - <code class="Nm">cprng_fast</code> functions are implemented in - <span class="Pa">sys/crypto/cprng_fast/cprng_fast.c</span>, and use the - ChaCha8 stream cipher.</p> -</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">condvar(9)</a>, <a class="Xr">rnd(9)</a>, - <a class="Xr">spl(9)</a></p> -<p class="Pp"><cite class="Rs"><span class="RsA">Elaine Barker</span> and - <span class="RsA">John Kelsey</span>, <span class="RsT">Recommendation for - Random Number Generation Using Deterministic Random Bit Generators - (Revised)</span>, <i class="RsI">National Institute of Standards and - Technology</i>, <span class="RsD">2011</span>, <span class="RsO">NIST - Special Publication 800-90A, Rev 1</span>.</cite></p> -<p class="Pp"><cite class="Rs"><span class="RsA">Daniel J. Bernstein</span>, - <span class="RsT">ChaCha, a variant of Salsa20</span>, - <a class="RsU" href="http://cr.yp.to/papers.html#chacha">http://cr.yp.to/papers.html#chacha</a>, - <span class="RsD">2008-01-28</span>, <span class="RsO">Document ID: - 4027b5256e17b9796842e6d0f68b0b5e</span>.</cite></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The cprng family of functions first appeared in - <span class="Ux">NetBSD 6.0</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">August 16, 2020</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |