1.. _module-pw_random: 2 3========= 4pw_random 5========= 6.. pigweed-module:: 7 :name: pw_random 8 9Pigweed's ``pw_random`` module provides a generic interface for random number 10generators, as well as some practical embedded-friendly implementations. While 11this module does not provide drivers for hardware random number generators, it 12acts as a user-friendly layer that can be used to abstract away such hardware. 13 14Embedded systems have the propensity to be more deterministic than your typical 15PC. Sometimes this is a good thing. Other times, it's valuable to have some 16random numbers that aren't predictable. In security contexts or areas where 17things must be marked with a unique ID, this is especially important. Depending 18on the project, true hardware random number generation peripherals may or may 19not be available. Even if RNG hardware is present, it might not always be active 20or accessible. ``pw_random`` provides libraries that make these situations 21easier to manage. 22 23--------------------- 24Using RandomGenerator 25--------------------- 26There's two sides to a RandomGenerator; the input, and the output. The outputs 27are relatively straightforward; ``GetInt(T&)`` randomizes the passed integer 28reference, ``GetInt(T&, T exclusive_upper_bound)`` produces a random integer 29less than ``exclusive_upper_bound``, and ``Get()`` dumps random values into the 30passed span. The inputs are in the form of the ``InjectEntropy*()`` functions. 31These functions are used to "seed" the random generator. In some 32implementations, this can simply be resetting the seed of a PRNG, while in 33others it might directly populate a limited buffer of random data. In all cases, 34entropy injection is used to improve the randomness of calls to ``Get*()``. 35 36It might not be easy to find sources of entropy in a system, but in general a 37few bits of noise from ADCs or other highly variable inputs can be accumulated 38in a RandomGenerator over time to improve randomness. Such an approach might 39not be sufficient for security, but it could help for less strict uses. 40 41------------- 42API reference 43------------- 44.. doxygennamespace:: pw::random 45 :members: 46 47----------- 48Future Work 49----------- 50A simple "entropy pool" implementation could buffer incoming entropy later use 51instead of requiring an application to directly poll the hardware RNG peripheral 52when the random data is needed. This would let a device collect entropy when 53idling, improving the latency of potentially performance-sensitive areas where 54random numbers are needed. 55 56 57.. toctree:: 58 :hidden: 59 :maxdepth: 1 60 61 backends 62