Documentation

Random

Read time 2 minutes Package: Nalix.Environment
On this page

Namespace: Nalix.Environment.Random
Assembly: Nalix.Environment

Csprng provides thread-safe, cryptographically strong random number generation backed directly by the operating system’s CSPRNG (OsCsprng).

Source Mapping

  • src/Nalix.Environment/Random/Csprng.cs
  • src/Nalix.Environment/Random/OsCsprng.cs

Platform Entropy Backends (OsCsprng)

OsCsprng.Fill(Span<byte>) invokes native OS entropy primitives directly without intermediate allocations:

  • Windows: BCryptGenRandom (bcrypt.dll, BCRYPT_USE_SYSTEM_PREFERRED_RNG)
  • Linux / Android: getrandom syscall (libc) with /dev/urandom fallback
  • macOS / iOS / tvOS: SecRandomCopyBytes (Security.framework) with /dev/urandom fallback
  • Other POSIX: /dev/urandom (managed via a persistent file descriptor that can be closed on application shutdown via OsCsprng.Shutdown())

Csprng Public Members

MemberSignatureDescription
MaxByteArrayLengthpublic const int MaxByteArrayLength = SerializerBounds.MaxArray; (1_048_576)Maximum byte array length accepted by allocation-returning helpers.
Fillpublic static void Fill(Span<byte> data)Fills data in-place with cryptographically strong random bytes (zero allocations).
GetBytespublic static byte[] GetBytes(int length)Allocates and returns a byte[length] filled with random bytes (0 <= length <= MaxByteArrayLength).
CreateNoncepublic static byte[] CreateNonce(int length = 12)Allocates and returns a random nonce (defaults to 12 bytes for ChaCha20-Poly1305).
NextBytes(byte[])public static void NextBytes(byte[] buffer)Fills buffer in-place with random bytes.
NextBytes(Span<byte>)public static void NextBytes(Span<byte> buffer)Fills buffer in-place with random bytes.
GetInt32(int, int)public static int GetInt32(int minValue, int maxValue)Returns an unbiased random int in [minValue, maxValue) using bitmask rejection sampling.
GetInt32(int)public static int GetInt32(int maxValue)Shortcut for GetInt32(0, maxValue).
NextUInt32public static uint NextUInt32()Returns a cryptographically random 32-bit unsigned integer.
NextUInt64public static ulong NextUInt64()Returns a cryptographically random 64-bit unsigned integer.
NextDoublepublic static double NextDouble()Returns a random double in [0.0, 1.0) with 53 bits of cryptographic precision.

Usage Example

using System;
using Nalix.Environment.Random;

// Zero-allocation 12-byte nonce on the stack
Span<byte> nonce = stackalloc byte[12];
Csprng.Fill(nonce);

// Unbiased random port in dynamic range [49152, 65535)
int ephemeralPort = Csprng.GetInt32(49152, 65535);

// 32-byte handshake challenge
byte[] challenge = Csprng.GetBytes(32);