[−][src]Module kernel::hil::rng
Interfaces for accessing a random number generator.
A random number generator produces a stream of random numbers, either from hardware or based on an initial seed. The RNG trait provides a simple, implementation agnostic interface for getting new random values.
Randomness: Random numbers generated by this trait MUST pass standard randomness tests, such as A. Rukhin, J. Soto, J. Nechvatal, M. Smid, E. Barker, S. Leigh, M. Levenson, M. Vangel, D. Banks, A. Heckert, J. Dray, and S. Vo. A statistical test suite for random and pseudorandom number generators for cryptographic applications. Technical report, NIST, 2010. It is acceptable for implementations to rely on prior verification of the algorithm being used. For example, if the implementation chooses to use a Fishman and Moore Linear Congruence Generator (LCG) with the parameters specified in the NIST report above, it does not need to rerun the tests.
Entropy: This trait does not promise highentropy random numbers,
although it MAY generate them. Implementations of this interface
MAY generate random numbers using techniques other than true
random number generation (through entropy) or cryptographically
secure pseudorandom number generation. Other traits, described
elsewhere, provide random numbers with entropy guarantees. This
trait MUST NOT be used for randomness needed for security or
cryptography. If highentropy randomness is needed, the Entropy
trait should be used instead.
The Rng trait is designed to work well with random number
generators that may not have values ready immediately. This is
important when generating numbers from a lowbandwidth hardware
random number generator or when the RNG is virtualized among many
consumers. Random numbers are yielded to the
Client as an Iterator
which only terminates
when no more numbers are currently available. Clients can request
more randomness if needed and will be called again when more is
available.
The Random trait is synchronous, so designed to work with arithmetically simple random number generators that can return a result quickly.
Example
The following example is a simple capsule that prints out a random number
once a second using the Alarm
and RNG
traits.
use kernel::hil; use kernel::hil::time::Frequency; use kernel::ReturnCode; struct RngTest<'a, A: 'a + hil::time::Alarm<'a>> { rng: &'a hil::rng::Rng<'a>, alarm: &'a A } impl<'a, A: hil::time::Alarm<'a>> RngTest<'a, A> { pub fn initialize(&self) { let interval = 1 * <A::Frequency>::frequency(); let tics = self.alarm.now().wrapping_add(interval); self.alarm.set_alarm(tics); } } impl<'a, A: hil::time::Alarm<'a>> hil::time::AlarmClient for RngTest<'a, A> { fn fired(&self) { self.rng.get(); } } impl<'a, A: hil::time::Alarm<'a>> hil::rng::Client for RngTest<'a, A> { fn randomness_available(&self, randomness: &mut Iterator<Item = u32>, error: ReturnCode) > hil::rng::Continue { match randomness.next() { Some(random) => { println!("Rand {}", random); let interval = 1 * <A::Frequency>::frequency(); let tics = self.alarm.now().wrapping_add(interval); self.alarm.set_alarm(tics); hil::rng::Continue::Done }, None => hil::rng::Continue::More } } }
Enums
Continue  Denotes whether the Client wants to be notified when

Traits
Client  An Rng client 
Random  Generic interface for a synchronous 32bit random number generator. 
Rng  Generic interface for a 32bit random number generator. 