RingOscillatorNoiseSource Class Reference

Processes the signal from a ring oscillator based noise source. More...

#include <RingOscillatorNoiseSource.h>

Inheritance diagram for RingOscillatorNoiseSource:

Public Member Functions
bool	calibrating () const
	Determine if the noise source is still calibrating itself. More...
void	stir ()
	Stirs entropy from this noise source into the global random number pool. More...
Public Member Functions inherited from NoiseSource
	NoiseSource ()
	Constructs a new random noise source.
virtual	~NoiseSource ()
	Destroys this random noise source.
virtual void	added ()
	Called when the noise source is added to RNG with RNG.addNoiseSource(). More...

Additional Inherited Members
Protected Member Functions inherited from NoiseSource
virtual void	output (const uint8_t *data, size_t len, unsigned int credit)
	Called from subclasses to output noise to the global random number pool. More...

Detailed Description

Processes the signal from a ring oscillator based noise source.

This class processes input from a ring oscillator noise source, such as that described here.

Note

The output from a ring oscillator is not generally as good as a "true" noise source. The oscillation can easily settle into regular patterns or sync up with other clock sources on the board. It is even possible to "hack" a ring oscillator by injecting chosen frequencies on the power supply rails to force the oscillation into a predictable waveform (see this paper for an example). It is very important that the output of this class be whitened with RNG before it is used for cryptography and that the device is isolated from attacker-controlled sources of power. Unless you have a very good reason to use a ring oscillator, TransistorNoiseSource is usually a better option.

The noise is read from an input capture pin on the Arduino and stirred into the random number pool on a regular basis. The following pins are used on different Arduino variants:

Variant	Arduino Pin / AVR Pin	Timer
Arduino Uno	D8 / PB0	Timer 1
Arduino Leonardo	D4 / PD4	Timer 1
Arduino Mega or Mega 2560	D49 / PL0	Timer 4

If your board is not pin-compatible with one of the above, then the source for the RingOscillatorNoiseSource class will need to be modified to use a different pin/timer combination. Also, when the timer is in use by this class it cannot be used for other application tasks.

The example below shows how to initialize a ring oscillator based noise source and use it with RNG:

#include <Crypto.h>
#include <RNG.h>
#include <RingOscillatorNoiseSource.h>
 
// Noise source to seed the random number generator.
RingOscillatorNoiseSource noise;
 
void setup() {
    // Initialize the random number generator with the application tag
    // "MyApp 1.0" and load the previous seed from EEPROM address 500.
    RNG.begin("MyApp 1.0", 500);
 
    // Add the noise source to the list of sources known to RNG.
    RNG.addNoiseSource(noise);
 
    // ...
}
 
void loop() {
    // ...
 
    // Perform regular housekeeping on the random number generator.
    RNG.loop();
 
    // ...
}

For more information, see the documentation for RNG.

See also

RNG, NoiseSource, TransistorNoiseSource

Definition at line 29 of file RingOscillatorNoiseSource.h.

Member Function Documentation

calibrating()

bool RingOscillatorNoiseSource::calibrating ( ) const

virtual

Determine if the noise source is still calibrating itself.

Returns

Returns true if calibration is in progress; false if the noise source is generating valid random data.

Noise sources that require calibration start doing so at system startup and then switch over to random data generation once calibration is complete. Since no random data is being generated during calibration, the output from RNG.rand() may be predictable. Use RNG.available() to determine when sufficient entropy is available to generate good random values.

It is possible that the noise source never exits calibration. This can happen if the input voltage is insufficient to trigger noise or if the noise source is not connected. Noise sources may also periodically recalibrate themselves.

See also

stir()

Implements NoiseSource.

Definition at line 178 of file RingOscillatorNoiseSource.cpp.

stir()

void RingOscillatorNoiseSource::stir ( )

virtual

Stirs entropy from this noise source into the global random number pool.

This function should call output() to add the entropy from this noise source to the global random number pool.

The noise source should batch up the entropy data, providing between 16 and 48 bytes of data each time. If the noise source does not have sufficient entropy data at the moment, it should return without stiring the current data in.

See also

calibrating(), output()

Implements NoiseSource.

Definition at line 201 of file RingOscillatorNoiseSource.cpp.

---

The documentation for this class was generated from the following files:

• RingOscillatorNoiseSource.h
• RingOscillatorNoiseSource.cpp