## Expand description

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 high-quality 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 low-entropy 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 high-entropy sources is
Recommendations for Randomness in the Operating System: How to
Keep Evil Children Out of Your Pool and Other Random Facts,
Corrigan-Gibbs 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 low-bandwidth 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::ConvertTicks;
use kernel::hil::time::Frequency;
use kernel::hil::time::AlarmClient;
use kernel::ErrorCode;
struct EntropyTest<'a, A: 'a + Alarm<'a>> {
entropy: &'a dyn Entropy32 <'a>,
alarm: &'a A
}
impl<'a, A: Alarm<'a>> EntropyTest<'a, A> {
pub fn initialize(&self) {
let now = self.alarm.now();
let dt = self.alarm.ticks_from_seconds(1);
self.alarm.set_alarm(now, dt);
}
}
impl<'a, A: Alarm<'a>> AlarmClient for EntropyTest<'a, A> {
fn alarm(&self) {
self.entropy.get();
}
}
impl<'a, A: Alarm<'a>> Client32 for EntropyTest<'a, A> {
fn entropy_available(&self,
entropy: &mut dyn Iterator<Item = u32>,
error: Result<(), ErrorCode>) -> hil::entropy::Continue {
match entropy.next() {
Some(val) => {
println!("Entropy {}", val);
let now = self.alarm.now();
let dt = self.alarm.ticks_from_seconds(1);
self.alarm.set_alarm(now, dt);
hil::entropy::Continue::Done
},
None => hil::entropy::Continue::More
}
}
}
```