<!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: '1.10.17',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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="top" title="Botan" href="contents.html" />
<link rel="next" title="Format Preserving Encryption" href="fpe.html" />
<link rel="prev" title="Password Hashing" href="passhash.html" />
</head>
<body role="document">
<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 random number generators provided in Botan are meant for creating
keys, IVs, padding, nonces, and anything else that requires ‘random’
data. It is important to remember that the output of these classes
will vary, even if they are supplied with the same seed (ie, two
<code class="docutils literal"><span class="pre">Randpool</span></code> objects with similar initial states will not produce the
same output, because the value of high resolution timers is added to
the state at various points).</p>
<p>To create a random number generator, instantiate a <code class="docutils literal"><span class="pre">AutoSeeded_RNG</span></code>
object. This object will handle choosing the right algorithms from the
set of enabled ones and doing seeding using OS specific
routines. The main service a RandomNumberGenerator provides is, of
course, random numbers:</p>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator6randomEv">
<span id="RandomNumberGenerator::random"></span>byte <code class="descclassname">RandomNumberGenerator::</code><code class="descname">random</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator6randomEv" title="Permalink to this definition">¶</a></dt>
<dd><p>Generates a single random byte and returns it</p>
</dd></dl>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator9randomizeEP4byte6size_t">
<span id="RandomNumberGenerator::randomize__byteP.s"></span>void <code class="descclassname">RandomNumberGenerator::</code><code class="descname">randomize</code><span class="sig-paren">(</span>byte *<em>data</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator9randomizeEP4byte6size_t" title="Permalink to this definition">¶</a></dt>
<dd><p>Places <em>length</em> bytes into the array pointed to by <em>data</em></p>
</dd></dl>
<p>To ensure good quality output, a PRNG needs to be seeded with truly
random data. Normally this is done for you. However it may happen that
your application has access to data that is potentially unpredictable
to an attacker. If so, use</p>
<dl class="function">
<dt id="_CPPv2N21RandomNumberGenerator11add_entropyEPK4byte6size_t">
<span id="RandomNumberGenerator::add_entropy__byteCP.s"></span>void <code class="descclassname">RandomNumberGenerator::</code><code class="descname">add_entropy</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>data</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv2N21RandomNumberGenerator11add_entropyEPK4byte6size_t" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>which incorporates the data into the current randomness state. Don’t
worry about filtering the data or doing any kind of cryptographic
preprocessing (such as hashing); the RNG objects in botan are designed
such that you can feed them any arbitrary non-random or even
maliciously chosen data - as long as at some point some of the seed
data was good the output will be secure.</p>
<div class="section" id="implementation-notes">
<h2>Implementation Notes<a class="headerlink" href="#implementation-notes" title="Permalink to this headline">¶</a></h2>
<div class="section" id="randpool">
<h3>Randpool<a class="headerlink" href="#randpool" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">Randpool</span></code> is the primary PRNG within Botan. In recent versions all
uses of it have been wrapped by an implementation of the X9.31 PRNG
(see below). If for some reason you should have cause to create a PRNG
instead of using the “global” one owned by the library, it would be
wise to consider the same on the grounds of general caution; while
<code class="docutils literal"><span class="pre">Randpool</span></code> is designed with known attacks and PRNG weaknesses in
mind, it is not an standard/official PRNG. The remainder of this
section is a (fairly technical, though high-level) description of the
algorithms used in this PRNG. Unless you have a specific interest in
this subject, the rest of this section might prove somewhat
uninteresting.</p>
<p><code class="docutils literal"><span class="pre">Randpool</span></code> has an internal state called pool, which is 512 bytes
long. This is where entropy is mixed into and extracted from. There is also a
small output buffer (called buffer), which holds the data which has already
been generated but has just not been output yet.</p>
<p>It is based around a MAC and a block cipher (which are currently
HMAC(SHA-256) and AES-256). Where a specific size is mentioned, it
should be taken as a multiple of the cipher’s block size. For example,
if a 256-bit block cipher were used instead of AES, all the sizes
internally would double. Every time some new output is needed, we
compute the MAC of a counter and a high resolution timer. The
resulting MAC is XORed into the output buffer (wrapping as needed),
and the output buffer is then encrypted with AES, producing 16 bytes
of output.</p>
<p>After 8 blocks (or 128 bytes) have been produced, we mix the pool. To
do this, we first rekey both the MAC and the cipher; the new MAC key
is the MAC of the current pool under the old MAC key, while the new
cipher key is the MAC of the current pool under the just-chosen MAC
key. We then encrypt the entire pool in CBC mode, using the current
(unused) output buffer as the IV. We then generate a new output
buffer, using the mechanism described in the previous paragraph.</p>
<p>To add randomness to the PRNG, we compute the MAC of the input and XOR
the output into the start of the pool. Then we remix the pool and
produce a new output buffer. The initial MAC operation should make it
very hard for chosen inputs to harm the security of <code class="docutils literal"><span class="pre">Randpool</span></code>, and
as HMAC should be able to hold roughly 256 bits of state, it is
unlikely that we are wasting much input entropy (or, if we are, it
doesn’t matter, because we have a very abundant supply).</p>
</div>
<div class="section" id="ansi-x9-31">
<h3>ANSI X9.31<a class="headerlink" href="#ansi-x9-31" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">ANSI_X931_PRNG</span></code> is the standard issue X9.31 Appendix A.2.4 PRNG,
though using AES-256 instead of 3DES as the block cipher. This PRNG
implementation has been checked against official X9.31 test vectors.</p>
<p>Internally, the PRNG holds a pointer to another PRNG (typically
Randpool). This internal PRNG generates the key and seed used by the
X9.31 algorithm, as well as the date/time vectors. Each time an X9.31
PRNG object receives entropy, it passes it along to the PRNG it is
holding, and then pulls out some random bits to generate a new key and
seed. This PRNG considers itself seeded as soon as the internal PRNG
is seeded.</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>
</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">Welcome</a></li>
<li class="toctree-l1"><a class="reference internal" href="reading.html">Recommended Reading</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="firststep.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="filters.html">Information Flow: Pipes and Filters</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">Certificate Handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="ssl.html">SSL and TLS</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="lowlevel.html">The Low-Level Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="secmem.html">Secure Memory Containers</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="passhash.html">Password Hashing</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="#implementation-notes">Implementation Notes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#entropy-sources">Entropy Sources</a></li>
</ul>
</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="python.html">Python Binding</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="passhash.html" title="Password Hashing"
accesskey="P">previous</a> |
<a href="fpe.html" title="Format Preserving Encryption"
accesskey="N">next</a> |
<a href="genindex.html" title="General Index"
accesskey="I">index</a>
</div>
<div role="note" aria-label="source link">
<br/>
<a href="_sources/rng.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright 2000-2011, Jack Lloyd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.9.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
