Generating random data

The library provides a set of functions to generate unpredictable data, suitable for creating secret keys.

• On Windows systems, the RtlGenRandom() function is used.

• On OpenBSD, the arc4random() function is used.

• On recent FreeBSD and Linux kernels, the getrandom system call is used.

• On other Unices, the /dev/urandom device is used.

• If none of these options can safely be used, custom implementations can easily be hooked.

Usage

uint32_t randombytes_random(void);

The randombytes_random() function returns an unpredictable value between 0 and 0xffffffff (included).

uint32_t randombytes_uniform(const uint32_t upper_bound);

The randombytes_uniform() function returns an unpredictable value between 0 and upper_bound (excluded). Unlike randombytes_random() % upper_bound, it guarantees a uniform distribution of the possible output values even when upper_bound is not a power of 2. Note that an upper_bound < 2 leaves only a single element to be chosen, namely 0.

void randombytes_buf(void * const buf, const size_t size);

The randombytes_buf() function fills size bytes starting at buf with an unpredictable sequence of bytes.

void randombytes_buf_deterministic(void * const buf, const size_t size,
                                   const unsigned char seed[randombytes_SEEDBYTES]);

The randombytes_buf_deterministic function stores size bytes into buf indistinguishable from random bytes without knowing seed.

For a given seed, this function will always output the same sequence. size can be up to 2^38 (256 GB).

seed is randombytes_SEEDBYTES bytes long.

This function is mainly useful for writing tests and was introduced in libsodium 1.0.12. Under the hood, it uses the ChaCha20 stream cipher.

Up to 256 GB can be produced with a single seed.

int randombytes_close(void);

This deallocates the global resources used by the pseudo-random number generator. More specifically, when the /dev/urandom device is used, it closes the descriptor. Explicitly calling this function is almost never required.

void randombytes_stir(void);

The randombytes_stir() function reseeds the pseudo-random number generator if it supports this operation. Calling this function is not required with the default generator, even after a fork() call, unless the descriptor for /dev/urandom was closed using randombytes_close().

If a non-default implementation is being used (see randombytes_set_implementation()), randombytes_stir() must be called by the child after a fork() call.

Note

If this is used in an application inside a VM, and the VM is snapshotted and restored, then the above functions may produce the same output.