1 files changed, 80 insertions, 25 deletions

diff --git a/src/random.h b/src/random.h
index 00e90abbc5..4c73f3822a 100644
--- a/src/random.h
+++ b/src/random.h
@@ -13,33 +13,83 @@
 #include <stdint.h>
 #include <limits>
 
-/* Seed OpenSSL PRNG with additional entropy data */
-void RandAddSeed();
+/**
+ * Overall design of the RNG and entropy sources.
+ *
+ * We maintain a single global 256-bit RNG state for all high-quality randomness.
+ * The following (classes of) functions interact with that state by mixing in new
+ * entropy, and optionally extracting random output from it:
+ *
+ * - The GetRand*() class of functions, as well as construction of FastRandomContext objects,
+ *   perform 'fast' seeding, consisting of mixing in:
+ *   - A stack pointer (indirectly committing to calling thread and call stack)
+ *   - A high-precision timestamp (rdtsc when available, c++ high_resolution_clock otherwise)
+ *   - Hardware RNG (rdrand) when available.
+ *   These entropy sources are very fast, and only designed to protect against situations
+ *   where a VM state restore/copy results in multiple systems with the same randomness.
+ *   FastRandomContext on the other hand does not protect against this once created, but
+ *   is even faster (and acceptable to use inside tight loops).
+ *
+ * - The GetStrongRand*() class of function perform 'slow' seeding, including everything
+ *   that fast seeding includes, but additionally:
+ *   - OS entropy (/dev/urandom, getrandom(), ...). The application will terminate if
+ *     this entropy source fails.
+ *   - Bytes from OpenSSL's RNG (which itself may be seeded from various sources)
+ *   - Another high-precision timestamp (indirectly committing to a benchmark of all the
+ *     previous sources).
+ *   These entropy sources are slower, but designed to make sure the RNG state contains
+ *   fresh data that is unpredictable to attackers.
+ *
+ * - RandAddSeedSleep() seeds everything that fast seeding includes, but additionally:
+ *   - A high-precision timestamp before and after sleeping 1ms.
+ *   - (On Windows) Once every 10 minutes, performance monitoring data from the OS.
+ *   These just exploit the fact the system is idle to improve the quality of the RNG
+ *   slightly.
+ *
+ * On first use of the RNG (regardless of what function is called first), all entropy
+ * sources used in the 'slow' seeder are included, but also:
+ * - (On Windows) Performance monitoring data from the OS.
+ * - (On Windows) Through OpenSSL, the screen contents.
+ *
+ * When mixing in new entropy, H = SHA512(entropy || old_rng_state) is computed, and
+ * (up to) the first 32 bytes of H are produced as output, while the last 32 bytes
+ * become the new RNG state.
+*/
 
 /**
- * Functions to gather random data via the OpenSSL PRNG
+ * Generate random data via the internal PRNG.
+ *
+ * These functions are designed to be fast (sub microsecond), but do not necessarily
+ * meaningfully add entropy to the PRNG state.
+ *
+ * Thread-safe.
  */
-void GetRandBytes(unsigned char* buf, int num);
-uint64_t GetRand(uint64_t nMax);
-int GetRandInt(int nMax);
-uint256 GetRandHash();
+void GetRandBytes(unsigned char* buf, int num) noexcept;
+uint64_t GetRand(uint64_t nMax) noexcept;
+int GetRandInt(int nMax) noexcept;
+uint256 GetRandHash() noexcept;
 
 /**
- * Add a little bit of randomness to the output of GetStrongRangBytes.
- * This sleeps for a millisecond, so should only be called when there is
- * no other work to be done.
+ * Gather entropy from various sources, feed it into the internal PRNG, and
+ * generate random data using it.
+ *
+ * This function will cause failure whenever the OS RNG fails.
+ *
+ * Thread-safe.
  */
-void RandAddSeedSleep();
+void GetStrongRandBytes(unsigned char* buf, int num) noexcept;
 
 /**
- * Function to gather random data from multiple sources, failing whenever any
- * of those sources fail to provide a result.
+ * Sleep for 1ms, gather entropy from various sources, and feed them to the PRNG state.
+ *
+ * Thread-safe.
  */
-void GetStrongRandBytes(unsigned char* buf, int num);
+void RandAddSeedSleep();
 
 /**
  * Fast randomness source. This is seeded once with secure random data, but
- * is completely deterministic and insecure after that.
+ * is completely deterministic and does not gather more entropy after that.
+ *
  * This class is not thread-safe.
  */
 class FastRandomContext {
@@ -71,10 +121,10 @@ private:
     }
 
 public:
-    explicit FastRandomContext(bool fDeterministic = false);
+    explicit FastRandomContext(bool fDeterministic = false) noexcept;
 
     /** Initialize with explicit seed (only for testing) */
-    explicit FastRandomContext(const uint256& seed);
+    explicit FastRandomContext(const uint256& seed) noexcept;
 
     // Do not permit copying a FastRandomContext (move it, or create a new one to get reseeded).
     FastRandomContext(const FastRandomContext&) = delete;
@@ -85,7 +135,7 @@ public:
     FastRandomContext& operator=(FastRandomContext&& from) noexcept;
 
     /** Generate a random 64-bit integer. */
-    uint64_t rand64()
+    uint64_t rand64() noexcept
     {
         if (bytebuf_size < 8) FillByteBuffer();
         uint64_t ret = ReadLE64(bytebuf + 64 - bytebuf_size);
@@ -94,7 +144,7 @@ public:
     }
 
     /** Generate a random (bits)-bit integer. */
-    uint64_t randbits(int bits) {
+    uint64_t randbits(int bits) noexcept {
         if (bits == 0) {
             return 0;
         } else if (bits > 32) {
@@ -109,7 +159,7 @@ public:
     }
 
     /** Generate a random integer in the range [0..range). */
-    uint64_t randrange(uint64_t range)
+    uint64_t randrange(uint64_t range) noexcept
     {
         --range;
         int bits = CountBits(range);
@@ -123,19 +173,19 @@ public:
     std::vector<unsigned char> randbytes(size_t len);
 
     /** Generate a random 32-bit integer. */
-    uint32_t rand32() { return randbits(32); }
+    uint32_t rand32() noexcept { return randbits(32); }
 
     /** generate a random uint256. */
-    uint256 rand256();
+    uint256 rand256() noexcept;
 
     /** Generate a random boolean. */
-    bool randbool() { return randbits(1); }
+    bool randbool() noexcept { return randbits(1); }
 
     // Compatibility with the C++11 UniformRandomBitGenerator concept
     typedef uint64_t result_type;
     static constexpr uint64_t min() { return 0; }
     static constexpr uint64_t max() { return std::numeric_limits<uint64_t>::max(); }
-    inline uint64_t operator()() { return rand64(); }
+    inline uint64_t operator()() noexcept { return rand64(); }
 };
 
 /** More efficient than using std::shuffle on a FastRandomContext.
@@ -178,7 +228,12 @@ void GetOSRand(unsigned char *ent32);
  */
 bool Random_SanityCheck();
 
-/** Initialize the RNG. */
+/**
+ * Initialize global RNG state and log any CPU features that are used.
+ *
+ * Calling this function is optional. RNG state will be initialized when first
+ * needed if it is not called.
+ */
 void RandomInit();
 
 #endif // BITCOIN_RANDOM_H