🎲 RandomGenerator

The RandomGenerator class in LibSodium.Net provides access to cryptographically secure random values. It wraps several functions from libsodium's randombytes API and ensures correct initialization and exception safety.

🧂Based on libsodium's Generating random data
ℹ️ See also: API Reference for RandomGenerator

🌟 Features

Generate random 32-bit unsigned integers.
Generate bounded random integers.
Fill buffers with secure random bytes.
Generate deterministic random bytes using a seed.
Stir or close the RNG engine as needed.

📋 Getting Random Values

Get a random 32-bit unsigned integer: returns a cryptographically secure, uniformly distributed value.

uint value = RandomGenerator.GetUInt32();

Get a random value less than an upper bound: Returns a value in the range [0, upperBound).

uint lessThan100 = RandomGenerator.GetUInt32(100);

📋 Filling Buffers

🔐 When dealing with sensitive data (e.g., seeds, key material), prefer using SecureMemory<byte> for guarded heap allocations and automatic zeroing.

Fill a buffer with unpredictable cryptographic random bytes:

Span<byte> buffer = stackalloc byte[32];
RandomGenerator.Fill(buffer);

var buffer = new byte[32];
RandomGenerator.Fill(buffer);

using var buffer = SecureMemory.Create<byte>(32);
RandomGenerator.Fill(buffer);

Fill a buffer with deterministic random bytes:

Span<byte> seed = stackalloc byte[RandomGenerator.SeedLen];
RandomGenerator.Fill(seed); // Generate a secure seed

Span<byte> buffer = stackalloc byte[32];
RandomGenerator.FillDeterministic(buffer, seed);

var seed = new byte[RandomGenerator.SeedLen];
RandomGenerator.Fill(seed); // Generate a secure seed

var buffer = new byte[32];
RandomGenerator.FillDeterministic(buffer, seed);

using var seed = SecureMemory.Create<byte>(RandomGenerator.SeedLen);
RandomGenerator.Fill(seed); // Generate a secure seed

using var buffer = SecureMemory.Create<byte>(32);
RandomGenerator.FillDeterministic(buffer, seed);

The same seed and length will always produce the same output.

⚠️ Seed must be exactly RandomGenerator.SeedLen bytes long. Otherwise, ArgumentException is thrown.

📋 Stirring and Closing

Stir the RNG:

RandomGenerator.Stir();

This reseeds the RNG, recommended after forking a process or when explicitly needed.

Close the RNG:

RandomGenerator.Close();

Closes the randombytes subsystem. This may be needed in long-running processes or to release resources. Calling it more than once will throw LibSodiumException.

⚠️ Error Handling

ArgumentException — thrown when FillDeterministic receives an invalid seed length.
LibSodiumException — thrown when Close() fails (e.g., called twice).