Module 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 re-run the tests.

Entropy: This trait does not promise high-entropy 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 high-entropy 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 low-bandwidth 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::ConvertTicks;
use kernel::hil::time::Frequency;
use kernel::hil::time::Time;
use kernel::ErrorCode;

struct RngTest<'a, A: 'a + hil::time::Alarm<'a>> {
    rng: &'a dyn hil::rng::Rng<'a>,
    alarm: &'a A
}

impl<'a, A: hil::time::Alarm<'a>> RngTest<'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: hil::time::Alarm<'a>> hil::time::AlarmClient for RngTest<'a, A> {
    fn alarm(&self) {
        self.rng.get();
    }
}

impl<'a, A: hil::time::Alarm<'a>> hil::rng::Client for RngTest<'a, A> {
    fn randomness_available(&self,
                            randomness: &mut dyn Iterator<Item = u32>,
                            error: Result<(), ErrorCode>) -> hil::rng::Continue {
        match randomness.next() {
            Some(random) => {
                println!("Rand {}", random);
                let now = self.alarm.now();
                let dt = self.alarm.ticks_from_seconds(1);

                self.alarm.set_alarm(now, dt);
                hil::rng::Continue::Done
            },
            None => hil::rng::Continue::More
        }
    }
}

Enums

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

Traits

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