/usr/share/doc/libbotan-2-doc/manual/rng.html is in libbotan-2-doc 2.4.0-5ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Random Number Generators — Botan</title>
<link rel="stylesheet" href="_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Hash Functions and Checksums" href="hash.html" />
<link rel="prev" title="Memory container" href="secmem.html" />
</head>
<body>
<div class="header-wrapper">
<div class="header">
<h1>Botan</h1>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="random-number-generators">
<span id="id1"></span><h1>Random Number Generators<a class="headerlink" href="#random-number-generators" title="Permalink to this headline">¶</a></h1>
<p>The base class <code class="docutils literal"><span class="pre">RandomNumberGenerator</span></code> is in the header <code class="docutils literal"><span class="pre">botan/rng.h</span></code>.</p>
<p>The major interfaces are</p>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator9randomizeEP7uint8_t6size_t">
<span id="RandomNumberGenerator::randomize__uint8_tP.s"></span>void <code class="descclassname">RandomNumberGenerator::</code><code class="descname">randomize</code><span class="sig-paren">(</span>uint8_t *<em>output_array</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator9randomizeEP7uint8_t6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Places <em>length</em> random bytes into the provided buffer.</p>
</dd></dl>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator11add_entropyEPK7uint8_t6size_t">
<span id="RandomNumberGenerator::add_entropy__uint8_tCP.s"></span>void <code class="descclassname">RandomNumberGenerator::</code><code class="descname">add_entropy</code><span class="sig-paren">(</span><em class="property">const</em> uint8_t *<em>data</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator11add_entropyEPK7uint8_t6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Incorporates provided data into the state of the PRNG, if at all
possible. This works for most RNG types, including the system and
TPM RNGs. But if the RNG doesn’t support this operation, the data is
dropped, no error is indicated.</p>
</dd></dl>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator20randomize_with_inputEP7uint8_t6size_tPK7uint8_t6size_t">
<span id="RandomNumberGenerator::randomize_with_input__uint8_tP.s.uint8_tCP.s"></span>void <code class="descclassname">RandomNumberGenerator::</code><code class="descname">randomize_with_input</code><span class="sig-paren">(</span>uint8_t *<em>data</em>, size_t <em>length</em>, <em class="property">const</em> uint8_t *<em>ad</em>, size_t <em>ad_len</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator20randomize_with_inputEP7uint8_t6size_tPK7uint8_t6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Like randomize, but first incorporates the additional input field
into the state of the RNG. The additional input could be anything which
parameterizes this request. Not all RNG types accept additional inputs.</p>
</dd></dl>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator23randomize_with_ts_inputEP7uint8_t6size_t">
<span id="RandomNumberGenerator::randomize_with_ts_input__uint8_tP.s"></span>void <code class="descclassname">RandomNumberGenerator::</code><code class="descname">randomize_with_ts_input</code><span class="sig-paren">(</span>uint8_t *<em>data</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator23randomize_with_ts_inputEP7uint8_t6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Creates a buffer with some timestamp values and calls <code class="docutils literal"><span class="pre">randomize_with_input</span></code></p>
</dd></dl>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator9next_byteEv">
<span id="RandomNumberGenerator::next_byte"></span>uint8_t <code class="descclassname">RandomNumberGenerator::</code><code class="descname">next_byte</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator9next_byteEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Generates a single random byte and returns it. Note that calling this
function several times is much slower than calling <code class="docutils literal"><span class="pre">randomize</span></code> once
to produce multiple bytes at a time.</p>
</dd></dl>
<div class="section" id="rng-types">
<h2>RNG Types<a class="headerlink" href="#rng-types" title="Permalink to this headline">¶</a></h2>
<p>The following RNG types are included</p>
<div class="section" id="hmac-drbg">
<h3>HMAC_DRBG<a class="headerlink" href="#hmac-drbg" title="Permalink to this headline">¶</a></h3>
<p>HMAC DRBG is a random number generator designed by NIST and specified
in SP 800-90A. It seems to be the most conservative generator of the
NIST approved options.</p>
<p>It can be instantiated with any HMAC but is typically used with
SHA-256, SHA-384, or SHA-512, as these are the hash functions approved
for this use by NIST.</p>
</div>
<div class="section" id="system-rng">
<h3>System_RNG<a class="headerlink" href="#system-rng" title="Permalink to this headline">¶</a></h3>
<p>In <code class="docutils literal"><span class="pre">system_rng.h</span></code>, objects of <code class="docutils literal"><span class="pre">System_RNG</span></code> reference a single
(process global) reference to the system PRNG (such as
<code class="docutils literal"><span class="pre">/dev/urandom</span></code> or <code class="docutils literal"><span class="pre">CryptGenRandom</span></code>).</p>
<p>You can also use the function <code class="docutils literal"><span class="pre">system_rng()</span></code> which returns a
reference to the global handle to the system RNG.</p>
</div>
<div class="section" id="autoseeded-rng">
<h3>AutoSeeded_RNG<a class="headerlink" href="#autoseeded-rng" title="Permalink to this headline">¶</a></h3>
<p>AutoSeeded_RNG is type naming a ‘best available’ userspace PRNG. The
exact definition of this has changed over time and may change in the
future, fortunately there is no compatability concerns when changing
any RNG since the only expectation is it produces bits
indistinguishable from random.</p>
<p>Note well: like most other classes in Botan, it is not safe to share
an instance of <code class="docutils literal"><span class="pre">AutoSeeded_RNG</span></code> among multiple threads without
serialization.</p>
<p>The current version uses the HMAC_DRBG with SHA-384 or SHA-256. The
initial seed is generated either by the system PRNG (if available) or
a default set of entropy sources. These are also used for periodic
reseeding of the RNG state.</p>
</div>
<div class="section" id="chacha-rng">
<h3>ChaCha_RNG<a class="headerlink" href="#chacha-rng" title="Permalink to this headline">¶</a></h3>
<p>This is a very fast userspace PRNG based on ChaCha20 and HMAC(SHA-256). The key
for ChaCha is derived by hashing entropy inputs with HMAC. Then the ChaCha
keystream generator is run, first to generate the new HMAC key (used for any
future entropy additions), then the desired RNG outputs.</p>
<p>This RNG composes two primitives thought to be secure (ChaCha and HMAC) in a
simple and well studied way (the extract-then-expand paradigm), but is still an
ad-hoc and non-standard construction. It is included because it is roughly 20x
faster then HMAC_DRBG, and certain applications need access to a very fast RNG.</p>
</div>
<div class="section" id="rdrand-rng">
<h3>RDRAND_RNG<a class="headerlink" href="#rdrand-rng" title="Permalink to this headline">¶</a></h3>
<p>This RNG type directly calls the x86 <code class="docutils literal"><span class="pre">rdrand</span></code> instruction. If the instruction
is not available it will throw at runtime, you can check beforehand by calling
<code class="docutils literal"><span class="pre">Botan::CPUID::has_rdrand()</span></code>.</p>
</div>
<div class="section" id="tpm-rng">
<h3>TPM_RNG<a class="headerlink" href="#tpm-rng" title="Permalink to this headline">¶</a></h3>
<p>This RNG type allows using the RNG exported from a TPM chip.</p>
</div>
<div class="section" id="pkcs11-rng">
<h3>PKCS11_RNG<a class="headerlink" href="#pkcs11-rng" title="Permalink to this headline">¶</a></h3>
<p>This RNG type allows using the RNG exported from a hardware token accessed via PKCS11.</p>
</div>
</div>
<div class="section" id="entropy-sources">
<h2>Entropy Sources<a class="headerlink" href="#entropy-sources" title="Permalink to this headline">¶</a></h2>
<p>An <code class="docutils literal"><span class="pre">EntropySource</span></code> is an abstract representation of some method of
gather “real” entropy. This tends to be very system dependent. The
<em>only</em> way you should use an <code class="docutils literal"><span class="pre">EntropySource</span></code> is to pass it to a PRNG
that will extract entropy from it – never use the output directly for
any kind of key or nonce generation!</p>
<p><code class="docutils literal"><span class="pre">EntropySource</span></code> has a pair of functions for getting entropy from
some external source, called <code class="docutils literal"><span class="pre">fast_poll</span></code> and <code class="docutils literal"><span class="pre">slow_poll</span></code>. These
pass a buffer of bytes to be written; the functions then return how
many bytes of entropy were gathered.</p>
<p>Note for writers of <code class="docutils literal"><span class="pre">EntropySource</span></code> subclasses: it isn’t necessary
to use any kind of cryptographic hash on your output. The data
produced by an EntropySource is only used by an application after it
has been hashed by the <code class="docutils literal"><span class="pre">RandomNumberGenerator</span></code> that asked for the
entropy, thus any hashing you do will be wasteful of both CPU cycles
and entropy.</p>
</div>
<div class="section" id="fork-safety">
<h2>Fork Safety<a class="headerlink" href="#fork-safety" title="Permalink to this headline">¶</a></h2>
<p>On Unix platforms, the <code class="docutils literal"><span class="pre">fork()</span></code> and <code class="docutils literal"><span class="pre">clone()</span></code> system calls can
be used to spawn a new child process. Fork safety ensures that the
child process doesn’t see the same output of random bytes as the
parent process. Botan tries to ensure fork safety by feeding the
process ID into the internal state of the random generator and by
automatically reseeding the random generator if the process ID
changed between two requests of random bytes. However, this does
not protect against PID wrap around. The process ID is usually
implemented as a 16 bit integer. In this scenario, a process will
spawn a new child process, which exits the parent process and
spawns a new child process himself. If the PID wrapped around, the
second child process may get assigned the process ID of it’s
grandparent and the fork safety can not be ensured.</p>
<p>Therefore, it is strongly recommended to explicitly reseed any
userspace random generators after forking a new process. If this is
not possible in your application, prefer using the system PRNG
instead.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="goals.html">Project Goals</a></li>
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Information</a></li>
<li class="toctree-l1"><a class="reference internal" href="building.html">Building The Library</a></li>
<li class="toctree-l1"><a class="reference internal" href="versions.html">Versioning</a></li>
<li class="toctree-l1"><a class="reference internal" href="secmem.html">Memory container</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Random Number Generators</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#rng-types">RNG Types</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#hmac-drbg">HMAC_DRBG</a></li>
<li class="toctree-l3"><a class="reference internal" href="#system-rng">System_RNG</a></li>
<li class="toctree-l3"><a class="reference internal" href="#autoseeded-rng">AutoSeeded_RNG</a></li>
<li class="toctree-l3"><a class="reference internal" href="#chacha-rng">ChaCha_RNG</a></li>
<li class="toctree-l3"><a class="reference internal" href="#rdrand-rng">RDRAND_RNG</a></li>
<li class="toctree-l3"><a class="reference internal" href="#tpm-rng">TPM_RNG</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pkcs11-rng">PKCS11_RNG</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#entropy-sources">Entropy Sources</a></li>
<li class="toctree-l2"><a class="reference internal" href="#fork-safety">Fork Safety</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="hash.html">Hash Functions and Checksums</a></li>
<li class="toctree-l1"><a class="reference internal" href="block_cipher.html">Block Ciphers</a></li>
<li class="toctree-l1"><a class="reference internal" href="stream_ciphers.html">Stream Ciphers</a></li>
<li class="toctree-l1"><a class="reference internal" href="message_auth_codes.html">Message Authentication Codes (MAC)</a></li>
<li class="toctree-l1"><a class="reference internal" href="cipher_modes.html">Cipher Modes</a></li>
<li class="toctree-l1"><a class="reference internal" href="pubkey.html">Public Key Cryptography</a></li>
<li class="toctree-l1"><a class="reference internal" href="x509.html">X.509 Certificates and CRLs</a></li>
<li class="toctree-l1"><a class="reference internal" href="tls.html">Transport Layer Security (TLS)</a></li>
<li class="toctree-l1"><a class="reference internal" href="credentials_manager.html">Credentials Manager</a></li>
<li class="toctree-l1"><a class="reference internal" href="bigint.html">BigInt</a></li>
<li class="toctree-l1"><a class="reference internal" href="kdf.html">Key Derivation Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="pbkdf.html">PBKDF Algorithms</a></li>
<li class="toctree-l1"><a class="reference internal" href="keywrap.html">AES Key Wrapping</a></li>
<li class="toctree-l1"><a class="reference internal" href="passhash.html">Password Hashing</a></li>
<li class="toctree-l1"><a class="reference internal" href="cryptobox.html">Cryptobox</a></li>
<li class="toctree-l1"><a class="reference internal" href="srp.html">Secure Remote Password</a></li>
<li class="toctree-l1"><a class="reference internal" href="psk_db.html">PSK Database</a></li>
<li class="toctree-l1"><a class="reference internal" href="filters.html">Pipe/Filter Message Processing</a></li>
<li class="toctree-l1"><a class="reference internal" href="fpe.html">Format Preserving Encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="compression.html">Lossless Data Compression</a></li>
<li class="toctree-l1"><a class="reference internal" href="pkcs11.html">PKCS#11</a></li>
<li class="toctree-l1"><a class="reference internal" href="tpm.html">Trusted Platform Module (TPM)</a></li>
<li class="toctree-l1"><a class="reference internal" href="otp.html">One Time Passwords</a></li>
<li class="toctree-l1"><a class="reference internal" href="ffi.html">FFI (C89) Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="python.html">Python Binding</a></li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">botan</a></li>
<li class="toctree-l1"><a class="reference internal" href="side_channels.html">Side Channels</a></li>
<li class="toctree-l1"><a class="reference internal" href="packaging.html">Notes for Distributors</a></li>
<li class="toctree-l1"><a class="reference internal" href="fuzzing.html">Fuzzing The Library</a></li>
<li class="toctree-l1"><a class="reference internal" href="deprecated.html">Deprecated Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="abi.html">ABI Stability</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="secmem.html" title="Memory container"
accesskey="P">previous</a> |
<a href="hash.html" title="Hash Functions and Checksums"
accesskey="N">next</a> |
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="genindex.html" title="General Index"
accesskey="I">index</a>
</div>
<div role="note" aria-label="source link">
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
Last updated on 2018-04-08.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
|