# 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 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:

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