GoeaLabs.Chaos 2.0.1

GoeaLabs.Caos

Project Description

• A cryptographically secure deterministic random number generator (CSDRNG) for .NET6+, based on RFC8439 ChaCha.
• Chaos and ChaCha are algorithmically indistinguishable, but Chaos includes additional features that make it distinct enough to merit a separate name.
• To provide clarity and facilitate comparison, a comparison table is often the best approach:

Technical summary

For any given kernel (seed), Chaos is capable of producing $2^{64}$ streams, each stream containing $2^{64}$ pebbles (blocks), each pebble being composed out of 16 UInt32(s) or 64 UInt8(s).

Features

• The software is licensed under the Apache 2.0 license, which is a commercially-friendly open-source license.
• The algorithm has been rigorously tested and validated against all test vectors provided in RFC8439, a widely recognized standard for cryptographic algorithms
• Chaos's CSDRNG offers a rich set of APIs that enable developers to easily integrate random number generation into their applications.
• The library is designed to be endian-neutral, ensuring consistent behavior and results across both Little Endian and Big Endian systems.
• With support for min-max scaling, developers can easily adjust the output of number producing methods to fit within a specific range, without having to perform manual scaling calculations.
• The library has undergone rigorous testing, including hundreds of automated tests covering a wide range of scenarios and use cases.
• With a focus on simplicity and ease of use, the API is free from unnecessary restrictions or complications.

Compatibility

The library is fully integrated with .NET6 and .NET7, offering advanced functionality and operations on the latest numeric types, including UInt128 and Int128.

Terminology

• kernel means the generator's seed (or key as per RFC8439 parlance);
• pebble means the index of a Chaos block;
• stream means the index of a Chaos stream;

API

The IChaos interface provides several methods for generating random numbers, including next(s), fill(s), load(s), and the logistic method GoTo(ulong?, ulong?). Additionally, all number-generating methods (as opposed to block-generating methods) include an optional min-max scaling feature, which allows the user to specify the range of values produced by the method in any sub-interval using arithmetic notation [minVal, maxVal]. This powerful feature makes it easy to generate random numbers with specific properties or constraints.

Next(s)

These methods produce random blocks or numbers while automatically advancing the engine's coordinates.

Fill(s)

These methods fill buffers with random numbers while automatically advancing the engine's coordinates.

Load(s)

These methods enable the retrieval of any block or number at arbitrary coordinates.

Logistics

Chaos provides 1 logistic method GoTo(ulong?, ulong?) enabling arbitrary positioning of the enigene's coordinate system.

• A call to GoTo(null, null) effectively resets the engine's coordinates;
• A call to GoTo(null, 9000) positions the engine at the very beginning of stream 9000. Doing GoTo(0, 9000) will result in a call to next(s) or fill(s) to skip the pebble at index 0 due to the fact that these methods first advance the coordinates and then do their work;
• Use load(s) for arbitrary jumps at various coordinates. Use GoTo(ulong?, ulong?) for positioning the engine before further calls to next(s) or fill(s).

Examples

Automatic engine initialization with random kernel and 20 rounds:

using GoeaLabs.Security.Random;

var engine = new Chaos();

User defined initialization with user defined kernel and rounds:

using GoeaLabs.Security.Random;

// IChaCha.KL (8 uint(s))
var kernel = new uint[] { 0, 1, 2, 3, 4, 5, 6, 7 };
var rounds = 40;
var engine = new Chaos(kernel, rounds);

The user needs 1 random byte:

using GoeaLabs.Security.Random;

var engine = new Chaos();
var number = engine.NextUInt8();

The user needs 1 random byte, but scaled to interval [1,6] (die roll):

using GoeaLabs.Security.Random;

var engine = new Chaos();
var number = engine.NextUInt8(1, 6);

The user needs to simulate a dice roll for a game with 6 dice:

using GoeaLabs.Security.Random;

var engine = new Chaos();
Span<byte> rolls = stackalloc byte[6];
engine.FillUInt8(rolls, 1, 6);

The user needs a random 128 bit unsigned integer:

using GoeaLabs.Security.Random;

var engine = new Chaos();
var number = engine.NextBigUInt128();

On NET7+, the user needs a random 128 bit unsigned integer:

using GoeaLabs.Security.Random;

var engine = new Chaos();
var number = engine.NextUInt128();

The user needs 100 random 128 bit signed integers in the interval $[-2^{80}, 2^{80}]$:

using GoeaLabs.Security.Random;

var engine = new Chaos();
var result = new BigInteger[100];

engine.FillBigInt128(result, -BigInteger.Pow(2, 80), BigInteger.Pow(2, 80));

The user needs a random 256 bit unsigned integer in the interval $[2^{130}, 2^{140}]$:

using GoeaLabs.Security.Random;

var engine = new Chaos();
var number = engine.NextUInt256(BigInteger.Pow(2, 130), BigInteger.Pow(2, 140));

The user needs 100 random 256 bit unsigned integers in the interval $[2^{130}, 2^{140}]$:

using GoeaLabs.Security.Random;

var engine = new Chaos();
var result = new BigInteger[100];

engine.FillBigUInt256(result, BigInteger.Pow(2, 130), BigInteger.Pow(2, 140));

The user needs to load the 1981th block from the 2023th stream and needs it raw, as UInt32:

using GoeaLabs.Security.Random;

var pebble = 1981;
var stream = 2023;
var engine = new Chaos();
Span<uint> result = stackalloc uint[IChaCha.SL];
engine.Load(pebble, stream, result);

The user needs to load the 1981th block from the 2023th stream and needs it as UInt8(s):

using GoeaLabs.Security.Random;

var pebble = 1981;
var stream = 2023;
var engine = new Chaos();
Span<byte> result = stackalloc byte[IChaCha.SL * sizeof(uint)];
engine.Load(pebble, stream, result);

The user needs to load the 1981th block from the 2023th as an UInt8 scaled in the interval [1,6]:

using GoeaLabs.Security.Random;

var pebble = 1981;
var stream = 2023;
var engine = new Chaos();
var number = engine.LoadUInt8(pebble, stream, 1, 6);

The user needs to retrieve 3 random UInt8(s) starting at 100th block of the 3000th stream, then reset the engine completely:

using GoeaLabs.Security.Random;

// Not a typo: we set the pebble at desired position - 1
var pebble = 99;
var stream = 3000;
Span<byte> result = stackalloc byte[3];

var engine = new Chaos().GoTo(pebble, stream);

engine.FillUInt8(result);
engine.GoTo(null, null);
// ... more work

See tests for more examples.

Installation

Install with NuGet Package Manager Console

Install-Package GoeaLabs.Chaos

Install with .NET CLI

dotnet add package GoeaLabs.Chaos