module Random:sig
..end
The Random
module provides random and pseudo-random number generators
suitable for generating cryptographic keys, nonces, or challenges.
class type rng =object
..end
Generic interface for a random number generator.
val string : rng -> int -> string
string rng len
returns a string of len
random bytes
read from the generator rng
.
val secure_rng : rng
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
/dev/random
on systems that supports it, or interrogates
the EGD daemon otherwise (see http://egd.sourceforge.net/
).
For EGD, the following paths are tried to locate the Unix socket
used to communicate with EGD:
EGD_SOCKET
;$HOME/.gnupg/entropy
;/var/run/egd-pool
; /dev/egd-pool
; /etc/egd-pool
.The method secure_rng#random_bytes
fails
if no suitable RNG is available.
secure_rng#random_bytes
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.
val system_rng : unit -> rng
system_rng ()
returns a random number generator derived
from the OS-provided RNG. It raises Error No_entropy_source
if the OS does not provide a secure RNG. Currently, this function
is supported under Win32, and always fails under Unix.
val device_rng : string -> rng
device_rng devicename
returns a random number generator
that reads from the special file devicename
, e.g.
/dev/random
or /dev/urandom
.
val egd_rng : string -> rng
egd_rng egd_socket
returns a random number generator
that uses the Entropy Gathering Daemon (http://egd.sourceforge.net/
).
egd_socket
is the path to the Unix socket that EGD uses for
communication.
val hardware_rng : unit -> rng
A hardware random number generator based on the RDRAND
instruction
of the x86 architecture. Available only on recent Intel and AMD
x86 processors in 64-bit mode. Raises Error No_entropy_source
if not available.
val pseudo_rng : string -> rng
pseudo_rng seed
returns a pseudo-random number generator
seeded by the string seed
. seed
must contain at least
16 characters, and can be arbitrarily longer than this,
except that only the first 32 characters are used.
The seed is used as a key for the Chacha20 stream cipher.
The generated pseudo-random data is the result of encrypting
the all-zero input with Chacha20.
While this generator is believed to have very good statistical
properties, it still does not generate ``true'' randomness:
the entropy of the byte strings it produces cannot exceed the
entropy contained in the seed. As a typical use,
Random.pseudo_rng (Random.string Random.secure_rng 20)
returns a
generator that can generate arbitrarily long strings of pseudo-random
data without delays, and with a total entropy of approximately
160 bits.
val pseudo_rng_aes_ctr : string -> rng
This is another pseudo-random number generator, based on the AES
block cipher in counter mode. It is slightly slower than pseudo_rng
while having similar randomness characteristics.
The only reason to use it instead of pseudo_rng
is that AES
has been cryptanalyzed even more than Chacha20.
The seed
argument must contain at least 16 characters. Only the
first 16 characters are used, as an AES key. The generated
pseudo-random data is the result of encrypting the 128-bit integers
0, 1, 2, ...
with this key.