ChaCha Cipher-based RNG¶
- class randomgen.chacha.ChaCha(seed=None, *, counter=None, key=None, rounds=20, mode=None)¶
Container for the ChaCha family of Counter pseudo-random number generators
- Parameters:
- seed{None, int, array_like[uint64], SeedSequence}, optional
Random seed initializing the pseudo-random number generator. Can be an integer in [0, 2**256), an array of 4 uint64 values, a SeedSequence instance or
None
(the default). If seed isNone
, then data is read from/dev/urandom
(or the Windows analog) if available. If unavailable, a hash of the time and process ID is used.- counter{None, int, array_like[uint64]}, optional
Counter to use in the ChaCha state. Can be either a Python int in [0, 2**128) or a 2-element uint64 array. If not provided, the counter is initialized at 0.
- key{None, int, array_like[uint64]}, optional
Key to use in the ChaCha state. Unlike seed, which is run through another RNG before use, the value in key is directly set. Can be either a Python int in [0, 2**256) or a 4-element uint64 array. key and seed cannot both be used.
- roundsint, optional
Number of rounds to run the ChaCha mixer. Must be an even integer. The standard number of rounds in 20. Smaller values, usually 8 or more, can be used to reduce security properties of the random stream while improving performance.
- mode{None, “sequence”, “legacy”}, optional
The seeding mode to use. “legacy” uses the legacy SplitMix64-based initialization. “sequence” uses a SeedSequence to transforms the seed into an initial state. None defaults to “sequence”.
Notes
ChaCha is a 64-bit PRNG that uses a counter-based design based on the ChaCha cipher [1]. Instances using different values of the key produce distinct sequences.
ChaCha
has a period of \(2^{128}\) and supports arbitrary advancing and jumping the sequence in increments of \(2^{64}\). These features allow multiple non-overlapping sequences to be generated.ChaCha
provides a capsule containing function pointers that produce doubles, and unsigned 32 and 64- bit integers. These are not directly consumable in Python and must be consumed by aGenerator
or similar object that supports low-level access.See
AESCounter
a related counter-based PRNG.State and Seeding
The
ChaCha
state vector consists of a 16-element array of uint32 that capture buffered draws from the distribution, an 8-element array of uint32s holding the seed, and an 2-element array of uint64 that holds the counter ([low, high]). The elements of the seed are the value provided by the user (or from the entropy pool). The final value rounds contains the number of rounds used. Typical values are 8, 12, or 20 (for high security).ChaCha
is seeded using either a single 256-bit unsigned integer or a vector of 4 64-bit unsigned integers. In either case, the seed is used as an input for a second random number generator, SplitMix64, and the output of this PRNG function is used as the initial state. Using a single 64-bit value for the seed can only initialize a small range of the possible initial state values.Parallel Features
ChaCha
can be used in parallel applications by calling thejump
method to advances the state as-if \(2^{64}\) random numbers have been generated. Alternatively,advance
can be used to advance the counter for any positive step in [0, 2**128). When usingjump
, all generators should be initialized with the same seed to ensure that the segments come from the same sequence.>>> from numpy.random import Generator >>> from randomgen import ChaCha >>> rg = [Generator(ChaCha(1234)) for _ in range(10)] # Advance each ChaCha instances by i jumps >>> for i in range(10): ... rg[i].bit_generator.jump(i)
Alternatively,
ChaCha
can be used in parallel applications by using a sequence of distinct keys where each instance uses different key.>>> key = 2**93 + 2**65 + 2**33 + 2**17 + 2**9 >>> rg = [Generator(ChaCha(key=key+i)) for i in range(10)]
Compatibility Guarantee
ChaCha
makes a guarantee that a fixed seed and will always produce the same random integer stream.References
[1]Bernstein, D. J.. ChaCha, a variant of Salsa20. http://cr.yp.to/papers.html#chacha. 2008.01.28.
Examples
>>> from numpy.random import Generator >>> from randomgen import ChaCha >>> rg = Generator(ChaCha(1234, rounds=8)) >>> rg.standard_normal() 0.123 # random
- Attributes:
- lockthreading.Lock
Lock instance that is shared so that the same bit git generator can be used in multiple Generators without corrupting the state. Code that generates values from a bit generator should hold the bit generator’s lock.
- seed_seq{None, SeedSequence}
The SeedSequence instance used to initialize the generator if mode is “sequence” or is seed is a SeedSequence. None if mode is “legacy”.
Seeding and State¶
| Seed the generator |
Get or set the PRNG state |
Parallel generation¶
| Advance the underlying RNG as-if delta draws have occurred. |
| Jumps the state as-if 2**64 random numbers have been generated. |
| Returns a new bit generator with the state jumped |
Extending¶
CFFI interface | |
ctypes interface |
Testing¶
| Return randoms as generated by the underlying BitGenerator |