Module Cryptokit.Random

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

random_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 reads from /dev/random on systems that supports it, or interrogate 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:

• the value of the environment variable EGD_SOCKET;
• $HOME/.gnupg/entropy;
• /var/run/egd-pool; /dev/egd-pool; /etc/egd-pool.

The method secure_rng#random_bytes fails if neither /dev/random nor EGD are available. secure_rng#random_bytes may block until enough entropy has been gathered. Do not use for generating large quantities of random data, else you might exhaust the entropy sources of the system.

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

device_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 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 55 characters are used. Technically, the first 16 characters of seed are used as a key for the AES cipher in CBC mode, which encrypts the output of a lagged Fibonacci generator X(i) = (X(i-24) + X(i-55)) mod 256 seeded with the first 55 characters of seed. 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, 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.