On Unix-based systems and on Windows, Sodium uses the facilities provided by the operating system when generating random numbers is required.
Other operating systems do not support /dev/urandom or it might not be suitable for cryptographic applications. These systems might provide a different way to gather random numbers.
And, on embedded operating systems, even if the system may not have such a facility, a hardware-based random number generator might be available.
In addition, reproducible results instead of unpredictable ones may be required in a testing environment.
For all these scenarios, Sodium provides a way to replace the default implementations generating random numbers.
typedef struct randombytes_implementation {
const char *(*implementation_name)(void);
uint32_t (*random)(void);
void (*stir)(void);
uint32_t (*uniform)(const uint32_t upper_bound);
void (*buf)(void * const buf, const size_t size);
int (*close)(void);
} randombytes_implementation;
int randombytes_set_implementation(randombytes_implementation *impl);The randombytes_set_implementation() function defines the set of functions required by the randombytes_* interface.
This function should only be called once, before sodium_init().
Sodium ships with a sample alternative randombytes implementation based on the ChaCha20 stream cipher in randombytes_internal_random.c file.
This implementation only requires access to /dev/urandom or /dev/random (or to RtlGenRandom() on Windows) once, during sodium_init().
It might be used instead of the default implementations in order to avoid system calls when random numbers are required.
It might also be used if a non-blocking random device is not available or not safe, but blocking would only be acceptable at initialization time.
It can be enabled with:
randombytes_set_implementation(&randombytes_internal_implementation);Before calling sodium_init().
It does fast key erasure. However, it is not thread-safe (locks must be added if this is a requirement), and was designed to be just a boilerplate for writing implementations for embedded operating systems. randombytes_stir() also has to be called to rekey the generator after fork()ing.
If you are using Windows or a modern Unix-based system, you should stick to the default implementations.
Internally, all the functions requiring random numbers use the randombytes_* interface.
Replacing the default implementations will affect explicit calls to randombytes_* functions as well as functions generating keys and nonces.
Since version 1.0.3, custom RNGs don’t need to provide randombytes_stir() nor randombytes_close() if they are not required (for example if the data comes from a system call). These can be NULL pointers instead. randombytes_uniform() doesn’t have to be defined either: a default implementation will be used if a NULL pointer is given.