NoiseSource.cpp

/*
 * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

#include "NoiseSource.h"
#include "RNG.h"

/**
 * \class NoiseSource NoiseSource.h <NoiseSource.h>
 * \brief Abstract base class for random noise sources.
 *
 * \sa \link RNGClass RNG\endlink, TransistorNoiseSource
 */

/**
 * \brief Constructs a new random noise source.
 */
NoiseSource::NoiseSource()
{
}

/**
 * \brief Destroys this random noise source.
 */
NoiseSource::~NoiseSource()
{
}

/**
 * \fn bool NoiseSource::calibrating() const
 * \brief Determine if the noise source is still calibrating itself.
 *
 * \return 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 \link RNGClass::rand() RNG.rand()\endlink may be predictable.
 * Use \link RNGClass::available() RNG.available()\endlink 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.
 *
 * \sa stir()
 */

/**
 * \fn void NoiseSource::stir()
 * \brief 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.
 *
 * \sa calibrating(), output()
 */

/**
 * \brief Called when the noise source is added to RNG with
 * \link RNGClass::addNoiseSource() RNG.addNoiseSource()\endlink.
 *
 * This function is intended for noise source initialization tasks that
 * must be performed after \link RNGClass::begin() RNG.begin()\endlink
 * 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.
 */
void NoiseSource::added()
{
    // Nothing to do here.
}

/**
 * \brief Called from subclasses to output noise to the global random
 * number pool.
 *
 * \param data Points to the noise data.
 * \param len Number of bytes of noise data.
 * \param credit The number of bits of entropy to credit for the data.
 * Note that this is bits, not bytes.
 *
 * The default implementation of this function calls
 * \link RNGClass::stir() RNG.stir()\endlink 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.
 */
void NoiseSource::output(const uint8_t *data, size_t len, unsigned int credit)
{
    RNG.stir(data, len, credit);
}