kernel::hil

Module entropy

Source
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
        }
    }
}

Enums§

  • Continue
    Denotes whether the Client wants to be notified when More randomness is available or if they are Done

Traits§