Cryptokit.Random

# 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 either uses the OS-provided RNG, if any, or 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 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

`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.