Arduino Cryptography Library
Public Member Functions | Protected Member Functions | List of all members
NoiseSource Class Referenceabstract

Abstract base class for random noise sources. More...

#include <NoiseSource.h>

Inheritance diagram for NoiseSource:
RingOscillatorNoiseSource TransistorNoiseSource

Public Member Functions

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

Protected Member Functions

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

Abstract base class for random noise sources.

See also
RNG, TransistorNoiseSource

Definition at line 29 of file NoiseSource.h.

Member Function Documentation

◆ added()

void NoiseSource::added ( )
virtual

Called when the noise source is added to RNG with RNG.addNoiseSource().

This function is intended for noise source initialization tasks that must be performed after RNG.begin() has been called to initialize the global random number pool. For example, if the noise source has a unique identifier or serial number then this function can stir it into the pool at startup time.

Definition at line 95 of file NoiseSource.cpp.

◆ calibrating()

bool NoiseSource::calibrating ( ) const
pure 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()

Implemented in TransistorNoiseSource, and RingOscillatorNoiseSource.

◆ output()

void NoiseSource::output ( const uint8_t *  data,
size_t  len,
unsigned int  credit 
)
protectedvirtual

Called from subclasses to output noise to the global random number pool.

Parameters
dataPoints to the noise data.
lenNumber of bytes of noise data.
creditThe number of bits of entropy to credit for the data. Note that this is bits, not bytes.

The default implementation of this function calls RNG.stir() to add the entropy from this noise source to the global random number pool.

This function may be overridden by subclasses to capture the raw output from the noise source before it is mixed into the pool to allow the raw data to be analyzed for randomness.

Definition at line 117 of file NoiseSource.cpp.

◆ stir()

void NoiseSource::stir ( )
pure 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()

Implemented in TransistorNoiseSource, and RingOscillatorNoiseSource.


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