From 242ec20724e5a39bc5f2ddb1f7bf2e8a234182a9 Mon Sep 17 00:00:00 2001 From: Paul Dicker Date: Sun, 25 Mar 2018 16:20:05 +0200 Subject: [PATCH 1/3] Improve OsRng documentation --- src/os.rs | 67 +++++++++++++++++++++++-------------------------------- 1 file changed, 28 insertions(+), 39 deletions(-) diff --git a/src/os.rs b/src/os.rs index b4380831477..72c8f94f311 100644 --- a/src/os.rs +++ b/src/os.rs @@ -14,55 +14,44 @@ use std::fmt; use rand_core::{RngCore, Error, impls}; -/// A random number generator that retrieves randomness straight from -/// the operating system. +/// A random number generator that retrieves randomness straight from the +/// operating system. This is the preferred external source of randomness for +/// most applications. Commonly it is used to initialize a user-space RNG, which +/// can then be used with much lower overhead. /// -/// Platform sources: +/// You may prefer to use [`EntropyRng`] instead of `OsRng`. Is is unlikely, but +/// not entirely theoretical, for `OsRng` to fail. In such cases `EntropyRng` +/// falls back on a good alternative entropy source. /// -/// - Linux, Android: read from `getrandom(2)` system call if available, -/// otherwise from` /dev/urandom`. -/// - MacOS, iOS: calls SecRandomCopyBytes. -/// - Windows: calls `RtlGenRandom`, exported from `advapi32.dll` as -/// `SystemFunction036`. +/// `OsRng` usually does not block. On some systems, and notably virtual +/// machines, it may block very early in the init process, when the OS CSPRNG +/// has not yet been seeded. +/// +/// `OsRng::new()` is guaranteed to be very cheap (after first call), and will +/// never consume more than one file handle per process. +/// +/// ## Platform sources: +/// +/// - Linux, Android: reads from the `getrandom(2)` system call if available, +/// otherwise from `/dev/urandom`. +/// - macOS, iOS: calls `SecRandomCopyBytes`. +/// - Windows: calls `RtlGenRandom`. /// - WASM: calls `window.crypto.getRandomValues` in browsers, -/// `require("crypto").randomBytes` in Node.js. +/// and in Node.js `require("crypto").randomBytes`. /// - OpenBSD: calls `getentropy(2)`. /// - FreeBSD: uses the `kern.arandom` `sysctl(2)` mib. /// - Fuchsia: calls `cprng_draw`. /// - Redox: reads from `rand:` device. /// - CloudABI: calls `random_get`. -/// - Other Unix-like systems: read directly from `/dev/urandom`. -/// -/// This usually does not block. On some systems (e.g. FreeBSD, OpenBSD, -/// Max OS X, and modern Linux) this may block very early in the init -/// process, if the CSPRNG has not been seeded yet.[1] -/// -/// *Note*: many Unix systems provide `/dev/random` as well as `/dev/urandom`. -/// This module uses `getrandom` if available, otherwise `/dev/urandom`, for -/// the following reasons: +/// - Other Unix-like systems: reads directly from `/dev/urandom`. +/// Note: many Unix systems provide `/dev/random` as well as `/dev/urandom`. +/// On all modern systems these two interfaces offer identical quality, with +/// the difference that on some systems `/dev/random` may block. This is a +/// dated design, and `/dev/urandom` is preferred by cryptography experts. [1] /// -/// - On Linux, `/dev/random` may block if entropy pool is empty; -/// `/dev/urandom` will not block. This does not mean that `/dev/random` -/// provides better output than `/dev/urandom`; the kernel internally runs a -/// cryptographically secure pseudorandom number generator (CSPRNG) based on -/// entropy pool for random number generation, so the "quality" of -/// `/dev/random` is not better than `/dev/urandom` in most cases. However, -/// this means that `/dev/urandom` can yield somewhat predictable randomness -/// if the entropy pool is very small, such as immediately after first -/// booting. Linux 3.17 added the `getrandom(2)` system call which solves -/// the issue: it blocks if entropy pool is not initialized yet, but it does -/// not block once initialized. `OsRng` tries to use `getrandom(2)` if -/// available, and use `/dev/urandom` fallback if not. If an application -/// does not have `getrandom` and likely to be run soon after first booting, -/// or on a system with very few entropy sources, one should consider using -/// `/dev/random` via `ReadRng`. -/// - On some systems (e.g. FreeBSD, OpenBSD and Mac OS X) there is no -/// difference between the two sources. (Also note that, on some systems -/// e.g. FreeBSD, both `/dev/random` and `/dev/urandom` may block once if -/// the CSPRNG has not seeded yet.) +/// [1] See [Myths about urandom](https://www.2uo.de/myths-about-urandom/). /// -/// [1] See for a more -/// in-depth discussion. +/// [`EntropyRng`]: struct.EntropyRng.html #[allow(unused)] // not used by all targets pub struct OsRng(imp::OsRng); From 1bf9b6bcc78dd8f972a1a4e2ad4f50428e35cfac Mon Sep 17 00:00:00 2001 From: Paul Dicker Date: Sun, 25 Mar 2018 16:42:11 +0200 Subject: [PATCH 2/3] Update changelog --- CHANGELOG.md | 3 +-- UPDATING.md | 8 ++------ 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1521352a43b..83e0008e57e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,7 +60,6 @@ You may also find the [Update Guide](UPDATING.md) useful. - All PRNGs are now portable across big- and little-endian architectures. (#209) - `Isaac64Rng::next_u32` no longer throws away half the results. (#209) - Add `IsaacRng::new_from_u64` and `Isaac64Rng::new_from_u64`. (#209) -- Remove `IsaacWordRng` wrapper. (#277) - Add the HC-128 CSPRNG `Hc128Rng`. (#210) - Add `ChaChaRng::set_rounds` method. (#243) - Changes to `JitterRng` to get its size down from 2112 to 24 bytes. (#251) @@ -71,6 +70,7 @@ You may also find the [Update Guide](UPDATING.md) useful. - Remove support for NaCl. (#225) - WASM support for `OsRng` via stdweb, behind the `stdweb` feature. (#272, #336) - Use `getrandom` on more platforms for Linux, and on Android. (#338) +- Use the `SecRandomCopyBytes` interface on macOS. (#322) - On systems that do not have a syscall interface, only keep a single file descriptor open for `OsRng`. (#239) - On Unix, first try a single read from `/dev/random`, then `/dev/urandom`. (#338) - Better error handling and reporting in `OsRng` (using new error type). (#225) @@ -90,7 +90,6 @@ You may also find the [Update Guide](UPDATING.md) useful. - Use widening multiply method for much faster integer range reduction. (#274) - `Uniform` distributions for `bool` uses `Range`. (#274) - `Uniform` distributions for `bool` uses sign test. (#274) -- Add `HighPrecision01` distribution. (#320) ## [0.4.2] - 2018-01-06 diff --git a/UPDATING.md b/UPDATING.md index 967814b3ab2..e159285632b 100644 --- a/UPDATING.md +++ b/UPDATING.md @@ -226,18 +226,14 @@ distribution). The `Open01` and `Closed01` wrappers have been removed. `Rng::gen()` (via `Uniform`) now yields samples from `(0, 1)` for floats; i.e. the same as the old -`Open01`. This is considered sufficient for most uses. If you require more -precision, use the `HighPrecision01` distribution. +`Open01`. This is considered sufficient for most uses. #### Uniform distributions -Three new distributions are available: +Two new distributions are available: - `Uniform` produces uniformly-distributed samples for many different types, and acts as a replacement for `Rand` -- `HighPrecision01` generates floating-point numbers in the range `[0, 1)` - (similar to `Uniform`) but with as much precision as the floating point - format can represent - `Alphanumeric` samples `char`s from the ranges `a-z A-Z 0-9` ##### Ranges From 54f9413e825bc5beb8d5feb3c8371d0fc5711961 Mon Sep 17 00:00:00 2001 From: Paul Dicker Date: Mon, 26 Mar 2018 20:38:17 +0200 Subject: [PATCH 3/3] Reword first paragraph --- src/os.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/os.rs b/src/os.rs index 72c8f94f311..579c30f9bd4 100644 --- a/src/os.rs +++ b/src/os.rs @@ -15,9 +15,9 @@ use std::fmt; use rand_core::{RngCore, Error, impls}; /// A random number generator that retrieves randomness straight from the -/// operating system. This is the preferred external source of randomness for -/// most applications. Commonly it is used to initialize a user-space RNG, which -/// can then be used with much lower overhead. +/// operating system. This is the preferred external source of entropy for most +/// applications. Commonly it is used to initialize a user-space RNG, which can +/// then be used to generate random values with much less overhead than `OsRng`. /// /// You may prefer to use [`EntropyRng`] instead of `OsRng`. Is is unlikely, but /// not entirely theoretical, for `OsRng` to fail. In such cases `EntropyRng`