Botan  1.11.15
src/lib/entropy/entropy_src.h
Go to the documentation of this file.
00001 /*
00002 * EntropySource
00003 * (C) 2008-2009,2014 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_ENTROPY_SOURCE_BASE_H__
00009 #define BOTAN_ENTROPY_SOURCE_BASE_H__
00010 
00011 #include <botan/secmem.h>
00012 #include <string>
00013 #include <functional>
00014 
00015 namespace Botan {
00016 
00017 /**
00018 * Class used to accumulate the poll results of EntropySources
00019 */
00020 class BOTAN_DLL Entropy_Accumulator
00021    {
00022    public:
00023       /**
00024       * Initialize an Entropy_Accumulator
00025       * @param goal is how many bits we would like to collect
00026       */
00027       Entropy_Accumulator(std::function<bool (const byte[], size_t, double)> accum) :
00028          m_accum_fn(accum), m_done(false) {}
00029 
00030       virtual ~Entropy_Accumulator() {}
00031 
00032       /**
00033       * Get a cached I/O buffer (purely for minimizing allocation
00034       * overhead to polls)
00035       *
00036       * @param size requested size for the I/O buffer
00037       * @return cached I/O buffer for repeated polls
00038       */
00039       secure_vector<byte>& get_io_buffer(size_t size)
00040          {
00041          m_io_buffer.clear();
00042          m_io_buffer.resize(size);
00043          return m_io_buffer;
00044          }
00045 
00046       /**
00047       * @return if our polling goal has been achieved
00048       */
00049       bool polling_goal_achieved() const { return m_done; }
00050 
00051       /**
00052       * Add entropy to the accumulator
00053       * @param bytes the input bytes
00054       * @param length specifies how many bytes the input is
00055       * @param entropy_bits_per_byte is a best guess at how much
00056       * entropy per byte is in this input
00057       */
00058       void add(const void* bytes, size_t length, double entropy_bits_per_byte)
00059          {
00060          m_done = m_accum_fn(reinterpret_cast<const byte*>(bytes),
00061                              length, entropy_bits_per_byte * length);
00062          }
00063 
00064       /**
00065       * Add entropy to the accumulator
00066       * @param v is some value
00067       * @param entropy_bits_per_byte is a best guess at how much
00068       * entropy per byte is in this input
00069       */
00070       template<typename T>
00071       void add(const T& v, double entropy_bits_per_byte)
00072          {
00073          add(&v, sizeof(T), entropy_bits_per_byte);
00074          }
00075    private:
00076       std::function<bool (const byte[], size_t, double)> m_accum_fn;
00077       bool m_done;
00078       secure_vector<byte> m_io_buffer;
00079    };
00080 
00081 /**
00082 * Abstract interface to a source of entropy
00083 */
00084 class BOTAN_DLL EntropySource
00085    {
00086    public:
00087       static void poll_available_sources(class Entropy_Accumulator& accum);
00088 
00089       /**
00090       * @return name identifying this entropy source
00091       */
00092       virtual std::string name() const = 0;
00093 
00094       /**
00095       * Perform an entropy gathering poll
00096       * @param accum is an accumulator object that will be given entropy
00097       */
00098       virtual void poll(Entropy_Accumulator& accum) = 0;
00099 
00100       virtual ~EntropySource() {}
00101    };
00102 
00103 }
00104 
00105 #endif