Libsodium documentation
  • Introduction
  • Installation
  • Quickstart and FAQ
  • Projects using libsodium
  • Commercial support
  • Bindings for other languages
  • Usage
  • Helpers
  • Padding
  • Secure memory
  • Generating random data
  • Secret-key cryptography
    • Authenticated encryption
    • Encrypted streams and file encryption
    • Encrypting a set of related messages
    • Authentication
    • AEAD constructions
      • ChaCha20-Poly1305
        • Original ChaCha20-Poly1305 construction
        • IETF ChaCha20-Poly1305 construction
        • XChaCha20-Poly1305 construction
      • AEGIS-256
      • AEGIS-128L
      • AES256-GCM
        • AES256-GCM with precomputation
  • Public-key cryptography
    • Authenticated encryption
    • Public-key signatures
    • Sealed boxes
  • Hashing
    • Generic hashing
    • Short-input hashing
  • Password hashing
    • The pwhash* API
  • Key derivation
    • HKDF
  • Key exchange
  • Advanced
    • SHA-2
    • HMAC-SHA-2
    • The Scrypt function
    • Point*scalar multiplication
    • One-time authentication
    • Stream ciphers
      • ChaCha20
      • XChaCha20
      • Salsa20
      • XSalsa20
    • Ed25519 to Curve25519
    • Finite field arithmetic
      • Ristretto
    • Custom RNG
  • Internals
  • Roadmap
Powered by GitBook
On this page
  • Usage
  • Example
  • Notes
  1. Advanced

Custom RNG

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.

Usage

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

Example

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.

Notes

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.

PreviousRistrettoNextInternals

Last updated 1 year ago