[−][src]Module kernel::hil::entropy
Interfaces for accessing an entropy source.
An entropy source produces random bits that are computationally intractable to guess, even if the complete history of generated bits and state of the device can be observed. Entropy sources must generate bits from an underlying physical random process, such as thermal noise, radiation, avalanche noise, or circuit instability. These bits of entropy can be used to seed cryptographically strong random number generators. Because highquality entropy is critical for security and these APIs provide entropy, it is important to understand all of these requirements before implementing these traits. Otherwise you may subvert the security of the operating system.
Entropy: Entropy bits generated by this trait MUST have very high entropy, i.e. 1 bit of entropy per generated bit. If the underlying source generates <1 bit of entropy per bit, these lowentropy bits SHOULD be mixed and combined with a cryptographic hash function. A good, short reference on the difference between entropy and randomness as well as guidelines for highentropy sources is Recommendations for Randomness in the Operating System: How to Keep Evil Children Out of Your Pool and Other Random Facts, CorriganGibbs et al., HotOS 2015.
The interface is designed to work well with entropy generators that may not have values ready immediately. This is important when generating numbers from a lowbandwidth hardware entropy source generator or when virtualized among many consumers.
Entropy is yielded to a Client as an Iterator
which only
terminates when no more entropy is currently available. Clients
can request more entropy if needed and will be called again when
more is available.
Example
The following example is a simple capsule that prints out entropy
once a second using the Alarm
and Entropy
traits.
use kernel::hil; use kernel::hil::entropy::Entropy32; use kernel::hil::entropy::Client32; use kernel::hil::time::Alarm; use kernel::hil::time::Frequency; use kernel::hil::time::AlarmClient; use kernel::ReturnCode; struct EntropyTest<'a, A: 'a + Alarm<'a>> { entropy: &'a Entropy32 <'a>, alarm: &'a A } impl<'a, A: Alarm<'a>> EntropyTest<'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: Alarm<'a>> AlarmClient for EntropyTest<'a, A> { fn fired(&self) { self.entropy.get(); } } impl<'a, A: Alarm<'a>> Client32 for EntropyTest<'a, A> { fn entropy_available(&self, entropy: &mut Iterator<Item = u32>, error: ReturnCode) > hil::entropy::Continue { match entropy.next() { Some(val) => { println!("Entropy {}", val); let interval = 1 * <A::Frequency>::frequency(); let tics = self.alarm.now().wrapping_add(interval); self.alarm.set_alarm(tics); hil::entropy::Continue::Done }, None => hil::entropy::Continue::More } } }
Enums
Continue  Denotes whether the Client wants to be notified when

Traits
Client8  An Entropy8 client 
Client32  An Entropy32 client 
Entropy8  An 8bit entropy generator. 
Entropy32  Generic interface for a 32bit entropy source. 