Class CryptoRandomSource

An IRandomSource adapter that wraps RandomNumberGenerator to provide cryptographically strong non-deterministic random values.

Inheritance
object
CryptoRandomSource
Implements
Inherited Members
Namespace: Scylla.Core.Util.Random
Assembly: ScyllaCore.dll
Syntax
public sealed class CryptoRandomSource : IRandomSource, IDisposable
Remarks

Use this source for security-sensitive operations where predictability must be ruled out, such as generating:

  • Session tokens and authentication nonces
  • Encryption keys and initialization vectors
  • Unique identifiers that must not be guessable

Because RandomNumberGenerator draws entropy from the operating system's cryptographic provider, each call is non-deterministic and cannot be seeded or replayed. Do not use this source in gameplay code where reproducibility is required. For gameplay, prefer Xoshiro256StarStar or PCG32.

CryptoRandomSource is significantly slower than the algorithm-based sources due to the overhead of system entropy collection. Avoid calling it in hot paths.

This class implements IDisposable. Dispose the instance when it is no longer needed to release the underlying RandomNumberGenerator resource.

Thread-safety is not guaranteed. Use separate instances per thread or apply external synchronization when sharing an instance across threads.

Constructors

CryptoRandomSource(RandomNumberGenerator)

Initializes a new CryptoRandomSource, optionally wrapping a caller-supplied RandomNumberGenerator.

Declaration
public CryptoRandomSource(RandomNumberGenerator rng = null)
Parameters
Type Name Description
RandomNumberGenerator rng

An existing RandomNumberGenerator instance to wrap. When null (the default), a new instance is created via Create(). If a custom instance is supplied, Dispose() will dispose it when this source is disposed.

Methods

Dispose()

Releases the underlying RandomNumberGenerator and all associated unmanaged resources. After calling Dispose(), any further calls to NextUInt32(), NextUInt64(), or NextBytes(byte[], int, int) will throw an ObjectDisposedException.

Declaration
public void Dispose()

NextBytes(byte[], int, int)

Fills a contiguous region of a byte array with cryptographically strong random bytes drawn from the operating system's entropy source.

Declaration
public void NextBytes(byte[] buffer, int offset = 0, int count = -1)
Parameters
Type Name Description
byte[] buffer

The destination byte array. Must not be null.
int offset

The zero-based starting index within buffer at which filling begins. Must be in the range [0, buffer.Length]. Defaults to 0.
int count

The number of bytes to fill. Pass -1 (the default) to fill all bytes from offset to the end of the array. The sum offset + count must not exceed buffer.Length.
Remarks

When offset is 0 and count equals buffer.Length, the entire buffer is passed directly to GetBytes(byte[]) with no intermediate copy. For partial fills a temporary array of length count is allocated and then block-copied into the target region.

Exceptions
Type Condition
ArgumentNullException

Thrown when buffer is null.
ArgumentOutOfRangeException

Thrown when offset is negative or greater than buffer.Length, when count is less than -1, or when offset + count exceeds buffer.Length.

NextUInt32()

Returns a cryptographically strong unsigned 32-bit random integer drawn from the operating system's entropy source, uniformly distributed across [0, 2^32).

Declaration
public uint NextUInt32()
Returns
Type Description
uint

A non-deterministic uint value. Each call may produce any value in the range [0, 4294967295] with equal probability.
Remarks

Internally allocates a 4-byte temporary buffer for each call. Prefer NextBytes(byte[], int, int) when generating multiple values to reduce allocation overhead.

NextUInt64()

Returns a cryptographically strong unsigned 64-bit random integer drawn from the operating system's entropy source, uniformly distributed across [0, 2^64).

Declaration
public ulong NextUInt64()
Returns
Type Description
ulong

A non-deterministic ulong value. Each call may produce any value in the range [0, 18446744073709551615] with equal probability.
Remarks

Internally allocates an 8-byte temporary buffer for each call. Prefer NextBytes(byte[], int, int) when generating multiple values to reduce allocation overhead.

Implements

Extension Methods

See Also