1.. _module-pw_random: 2 3--------- 4pw_random 5--------- 6Pigweed's ``pw_random`` module provides a generic interface for random number 7generators, as well as some practical embedded-friendly implementations. While 8this module does not provide drivers for hardware random number generators, it 9acts as a user-friendly layer that can be used to abstract away such hardware. 10 11Embedded systems have the propensity to be more deterministic than your typical 12PC. Sometimes this is a good thing. Other times, it's valuable to have some 13random numbers that aren't predictable. In security contexts or areas where 14things must be marked with a unique ID, this is especially important. Depending 15on the project, true hardware random number generation peripherals may or may 16not be available. Even if RNG hardware is present, it might not always be active 17or accessible. ``pw_random`` provides libraries that make these situations 18easier to manage. 19 20Using RandomGenerator 21===================== 22There's two sides to a RandomGenerator; the input, and the output. The outputs 23are relatively straightforward; ``GetInt()`` randomizes the passed integer 24reference, and ``Get()`` dumps random values into a the passed span. The inputs 25are in the form of the ``InjectEntropy*()`` functions. These functions are used 26to "seed" the random generator. In some implementations, this can simply be 27resetting the seed of a PRNG, while in others it might directly populate a 28limited buffer of random data. In all cases, entropy injection is used to 29improve the randomness of calls to ``Get*()``. 30 31It might not be easy to find sources of entropy in a system, but in general a 32few bits of noise from ADCs or other highly variable inputs can be accumulated 33in a RandomGenerator over time to improve randomness. Such an approach might 34not be sufficient for security, but it could help for less strict uses. 35 36Algorithms 37========== 38xorshift* 39--------- 40The ``xorshift*`` algorithm is a pseudo-random number generation algorithm. It's 41very simple in principle; the state is represented as an integer that, with each 42generation, performs exclusive OR operations on different left/right bit shifts 43of itself. The "*" refers to a final multiplication that is applied to the 44output value. 45 46Pigweed's implementation augments this with an ability to inject entropy to 47reseed the generator throughout its lifetime. When entropy is injected, the 48results of the generator are no longer completely deterministic based on the 49original seed. 50 51Note that this generator is NOT cryptographically secure. 52 53For more information, see: 54 55 * https://en.wikipedia.org/wiki/Xorshift 56 * https://www.jstatsoft.org/article/view/v008i14 57 * http://vigna.di.unimi.it/ftp/papers/xorshift.pdf 58 59Future Work 60=========== 61A simple "entropy pool" implementation could buffer incoming entropy later use 62instead of requiring an application to directly poll the hardware RNG peripheral 63when the random data is needed. This would let a device collect entropy when 64idling, improving the latency of potentially performance-sensitive areas where 65random numbers are needed. 66