<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="Start" href="index.html">
<link rel="next" href="Cryptokit.Padding.html">
<link rel="Up" href="Cryptokit.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Cryptokit" rel="Chapter" href="Cryptokit.html"><title>Cryptokit.Random</title>
</head>
<body>
<div class="navbar"> <a href="Cryptokit.html">Up</a>
<a href="Cryptokit.Padding.html">Next</a>
</div>
<center><h1>Module <a href="type_Cryptokit.Random.html">Cryptokit.Random</a></h1></center>
<br>
<pre><span class="keyword">module</span> Random: <code class="code">sig</code> <a href="Cryptokit.Random.html">..</a> <code class="code">end</code></pre>The <code class="code">Random</code> module provides random and pseudo-random number generators
suitable for generating cryptographic keys, nonces, or challenges.<br>
<hr width="100%">
<pre><span class="keyword">class type</span> <a name="TYPErng"></a><a href="Cryptokit.Random.rng.html">rng</a> = <code class="code">object</code> <a href="Cryptokit.Random.rng.html">..</a> <code class="code">end</code></pre><div class="info">
Generic interface for a random number generator.
</div>
<pre><span class="keyword">val</span> <a name="VALstring"></a>string : <code class="type"><a href="Cryptokit.Random.rng.html">rng</a> -> int -> string</code></pre><div class="info">
<code class="code">random_string rng len</code> returns a string of <code class="code">len</code> random bytes
read from the generator <code class="code">rng</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALsecure_rng"></a>secure_rng : <code class="type"><a href="Cryptokit.Random.rng.html">rng</a></code></pre><div class="info">
A high-quality random number generator, using hard-to-predict
system data to generate entropy. This generator either uses
the OS-provided RNG, if any, or reads from
<code class="code">/dev/random</code> on systems that supports it, or interrogate
the EGD daemon otherwise (see <code class="code">http://egd.sourceforge.net/</code>).
For EGD, the following paths are tried to locate the Unix socket
used to communicate with EGD:<ul>
<li>the value of the environment variable <code class="code">EGD_SOCKET</code>;</li>
<li><code class="code">$HOME/.gnupg/entropy</code>;</li>
<li><code class="code">/var/run/egd-pool</code>; <code class="code">/dev/egd-pool</code>; <code class="code">/etc/egd-pool</code>.</li>
</ul>
The method <code class="code">secure_rng#random_bytes</code> fails
if no suitable RNG is available.
<code class="code">secure_rng#random_bytes</code> may block until enough entropy
has been gathered. Do not use for generating large quantities
of random data, otherwise you could exhaust the entropy sources
of the system.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALsystem_rng"></a>system_rng : <code class="type">unit -> <a href="Cryptokit.Random.rng.html">rng</a></code></pre><div class="info">
<code class="code">system_rng ()</code> returns a random number generator derived
from the OS-provided RNG. It raises <code class="code">Error No_entropy_source</code>
if the OS does not provide a secure RNG. Currently, this function
is supported under Win32, and always fails under Unix.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALdevice_rng"></a>device_rng : <code class="type">string -> <a href="Cryptokit.Random.rng.html">rng</a></code></pre><div class="info">
<code class="code">device_rng devicename</code> returns a random number generator
that reads from the special file <code class="code">devicename</code>, e.g.
<code class="code">/dev/random</code> or <code class="code">/dev/urandom</code>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALegd_rng"></a>egd_rng : <code class="type">string -> <a href="Cryptokit.Random.rng.html">rng</a></code></pre><div class="info">
<code class="code">device_rng egd_socket</code> returns a random number generator
that uses the Entropy Gathering Daemon (<code class="code">http://egd.sourceforge.net/</code>).
<code class="code">egd_socket</code> is the path to the Unix socket that EGD uses for
communication.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALpseudo_rng"></a>pseudo_rng : <code class="type">string -> <a href="Cryptokit.Random.rng.html">rng</a></code></pre><div class="info">
<code class="code">pseudo_rng seed</code> returns a pseudo-random number generator
seeded by the string <code class="code">seed</code>. <code class="code">seed</code> must contain at least
16 characters, and can be arbitrarily longer than this,
except that only the first 55 characters are used.
Technically, the first 16 characters of <code class="code">seed</code> are used as
a key for the AES cipher in CBC mode, which encrypts the output
of a lagged Fibonacci generator <code class="code">X(i) = (X(i-24) + X(i-55)) mod 256</code>
seeded with the first 55 characters of <code class="code">seed</code>.
While this generator is believed to have good statistical properties,
it still does not generate ``true'' randomness: the entropy of
the strings it creates cannot exceed the entropy contained in
the seed. As a typical use,
<code class="code">Random.pseudo_rng (Random.string Random.secure_rng 20)</code> returns a
generator that can generate arbitrarily long strings of pseudo-random
data without delays, and with a total entropy of approximately
160 bits.<br>
</div>
</body></html>
