prg documentation

Author: anderspkd

include/scl/primitives/prg.h

@@ -20,45 +20,43 @@
 
 #include <array>
 #include <cstddef>
-#include <memory>
 #include <stdexcept>
 #include <string>
 #include <vector>
 
 #include <emmintrin.h>
 
-/**
- * @brief 64 bit nonce which is prepended to the counter in the PRG.
- */
-#ifndef PRG_NONCE
-#define PRG_NONCE 0x0123456789ABCDEF
-#endif
-
-/**
- * @brief The initial value of the PRG counter.
- */
-#ifndef PRG_INITIAL_COUNTER
-#define PRG_INITIAL_COUNTER 0
-#endif
-
 namespace scl {
 
 /**
- * @brief Pseudorandom generator based on AES-CTR.
+ * @brief Pseudorandom generator.
+ *
+ * @code
+ * auto prg = PRG::create();
  *
- * The <code>PRG</code> class implements a pseudorandom generator based on
- * AES-CTR where the n'th block of output is generated by encrypting a
- * counter. A block of random data is generated by computing
+ * std::array<unsigned char, 10> buffer;
+ * prg.next(buffer);  // buffer is filled with random bytes
  *
- *   <code>block := AES(seed, counter)</code>
+ * std::vector<unsigned char> rands = prg.next(42);
+ * assert(rands.size() == 42);
  *
- * where <code>seed</code> is either all 0s or a user supplied value, and
- * <code>counter</code> is a 128-bit counter initialized to be
+ * auto prg1 = PRG::create("seed1");
+ * auto prg2 = PRG::create("seed2");
  *
- *  <code>counter_init := PRG_NONCE || 0 ... 0</code>
+ * assert(prg1.next(42) != prg2.next(42));
+ * @endcode
  *
- * where each half is 64 bits. The value of PRG_NONCE can be set by defining it
- * as a macro. It defaults to <code>0x0123456789ABCDEF</code>.
+ * The underlying implementation of PRG is based on AES128 in counter mode.
+ * When supplying an explicit seed, only the first PRG::seedSize() bytes are
+ * used. For the current implementation this means only the first 16 bytes are
+ * counted.
+ *
+ * @code
+ * auto prg1 = PRG::create("abcdef0123456789abc");
+ * auto prg2 = PRG::create("abcdef0123456789xyz");
+ *
+ * assert(prg1.next(42) == prg2.next(42));
+ * @endcode
  */
 class PRG {
  private:
@@ -80,60 +78,41 @@ class PRG {
 
   /**
    * @brief Create a new PRG with a provided seed.
-   * @param seed the seed.
-   * @param seed_len length of the seed
    */
   static PRG create(const unsigned char* seed, std::size_t seed_len);
 
   /**
    * @brief Create a new PRG from a provided seed.
-   * @param seed the seed.
    */
   static PRG create(const std::string& seed);
 
   /**
    * @brief Reset the PRG.
-   *
-   * This method allows resetting a PRG object to its initial state.
    */
   void reset();
 
   /**
    * @brief Generate random data and store it in a supplied buffer.
-   * @param buffer the buffer
-   * @param n how many bytes of random data to generate
    */
   void next(unsigned char* buffer, std::size_t n);
 
   /**
    * @brief Generate random data and store it in a supplied buffer.
-   * @param buffer the buffer with space pre-allocated
-   *
-   * How many bytes of random data to generate is decided based on the output of
-   * <code>buffer.size()</code>.
    */
   void next(std::vector<unsigned char>& buffer) {
     next(buffer.data(), buffer.size());
   }
 
   /**
    * @brief Generate random data and store it in a supplied buffer.
-   * @param buffer the buffer.
    */
   template <std::size_t N>
   void next(std::array<unsigned char, N>& buffer) {
-    Next(buffer.data(), N);
+    next(buffer.data(), N);
   }
 
   /**
    * @brief Generate random data and store in in a supplied buffer.
-   * @param buffer the buffer
-   * @param n how many random bytes to generate
-   * @throws std::invalid_argument if \p n is greater than
-   * <code>buffer.size()</code>.
-   *
-   * The capacity of \p buffer is not affected in any way by this method and it
-   * requires that it has room for at least \p n elements.
    */
   void next(std::vector<unsigned char>& buffer, std::size_t n) {
     if (buffer.size() < n) {
@@ -144,13 +123,12 @@ class PRG {
 
   /**
    * @brief Generate and return random data.
-   * @param n the number of random bytes to generate
-   * @return the random bytes.
    */
   std::vector<unsigned char> next(std::size_t n) {
-    auto buffer = std::make_unique<unsigned char[]>(n);
-    next(buffer.get(), n);
-    return std::vector<unsigned char>(buffer.get(), buffer.get() + n);
+    std::vector<unsigned char> buffer;
+    buffer.reserve(n);
+    next(buffer);
+    return buffer;
   }
 
   /**
@@ -161,12 +139,12 @@ class PRG {
   }
 
  private:
-  PRG(std::array<unsigned char, BLOCK_SIZE> seed) : m_seed(seed) {};
-
   std::array<unsigned char, BLOCK_SIZE> m_seed = {0};
-  long m_counter = PRG_INITIAL_COUNTER;
+  long m_counter = 0;
   BlockType m_state[11];
 
+  PRG(std::array<unsigned char, BLOCK_SIZE> seed) : m_seed(seed) {};
+
   void update();
   void init();
 };

src/scl/primitives/prg.cc

@@ -80,7 +80,7 @@ void aes128Enc(const __m128i* key_schedule, __m128i m, unsigned char* ct) {
 }
 
 auto createMask(long counter) {
-  return _mm_set_epi64x(PRG_NONCE, counter);
+  return _mm_set_epi64x(0x0123456789ABCDEF, counter);
 }
 
 }  // namespace
@@ -117,7 +117,7 @@ void scl::PRG::init() {
 
 void scl::PRG::reset() {
   init();
-  m_counter = PRG_INITIAL_COUNTER;
+  m_counter = 0;
 }
 
 void scl::PRG::next(unsigned char* buffer, size_t n) {