Ch26.17: Random and Entropy
1. Two Different Problems
“Random” covers two unrelated requirements. A simulation needs a reproducible sequence with good statistical properties. A password, key or token needs unpredictability even to an attacker who knows the program. fast_io separates the two: the white-hole family reads the operating system's entropy source; `std::mt19937_64` is a seeded PRNG for reproducibility.
| Requirement | Use | Predictable? |
|---|---|---|
| Reproducible simulation | A seeded PRNG such as std::mt19937_64 |
Yes, by design. |
| Keys, tokens, salts | ibuf_white_hole_engine or the OS entropy source directly |
No. |
| Shuffling a game deck | A seeded PRNG | Yes, when the seed is known. |
| Shuffling a security-sensitive list | An entropy engine | No. |
2. The White-Hole Family
A “white hole” emits random bytes; it does not absorb them. The native type reads the platform's entropy source; the buffered type batches reads and wipes its buffer on destruction.
| Name | Role | Module |
|---|---|---|
native_white_hole |
Unbuffered raw entropy source. | fast_io |
ibuf_white_hole |
Buffered entropy source with secure buffer clearing. | header-side |
native_white_hole_engine |
Uniform random bit generator over the native source. | header-side |
ibuf_white_hole_engine |
Uniform random bit generator over the buffered source. | header-side |
::fast_io::ibuf_white_hole_engine eng;
::std::uniform_int_distribution<::std::uint32_t> dist{1, 100};
auto const value{dist(eng)};
The engine satisfies the C++ UniformRandomBitGenerator requirement, so it works with the
distributions in <random>. Each engine instance owns its own source and
buffer; do not share one engine across threads without synchronization.
3. Entropy Reporting
basic_white_hole_engine::entropy() returns the platform's entropy estimate
when the source exposes one, clamped to the result width. A source without an entropy
method returns 0.0. Do not treat that value as a proof of security; it is a
hint from the OS.
The engine's min() is 0 and max() is the maximum value of its
result_type. operator() reads enough bytes for one result and
returns it. On POSIX the source is getrandom or /dev/urandom; on
Windows it is RtlGenRandom/BCryptGenRandom or the platform
equivalent; on WASI it is random_get.
4. Reproducible PRNGs
For simulation, testing and procedural content, use a seeded engine from
<random>. The seed is part of the experiment: record it and replay it.
::std::mt19937_64 eng{0x123456789abcdef0ULL};
::std::uniform_real_distribution<double> dist{0.0, 1.0};
double const sample{dist(eng)};
A default-constructed engine uses a fixed seed, so every run produces the same sequence. That is useful for tests and wrong for anything security-sensitive. If you want a random seed, read it from the entropy source first, then seed the PRNG.
5. Distributions and Bias
Do not reduce an engine value modulo a range:
// wrong: biased toward the low end
auto bad{eng() % 100u};
// right: the distribution removes the bias
::std::uniform_int_distribution<::std::uint32_t> dist{0, 99};
auto good{dist(eng)};
The standard distributions are the correct layer for ranges, Bernoulli trials, normal samples and shuffling. They consume the engine's raw bits according to the distribution's contract, not according to a hand-written modulo.
6. random_generate
random_generate(distribution, engine) is a small wrapper that calls the
distribution and converts a legacy exception crossing the boundary back to the
herbception channel. It is header-side and is useful when a distribution implementation
throws.
auto value{::fast_io::random_generate(dist, eng)};
7. Module and Header Boundary
The fast_io module exports native_white_hole. The buffered
source, the engines and random_generate are header-side today. The
distributions themselves come from <random> and are not fast_io types.
Key Takeaways
- Reproducible PRNGs and cryptographic entropy are different tools.
native_white_holeis module-exported; the buffered source and engines are header-side.ibuf_white_hole_enginesatisfies UniformRandomBitGenerator and works with standard distributions.- The buffered engine wipes its internal buffer on destruction.
- Default-constructed PRNGs are deterministic; record and replay seeds for simulation.
- Never use modulo reduction for a range; use a distribution.
random_generatebridges distribution exceptions into the herbception channel.