auto merge of #13820 : klutzy/rust/urandom, r=alexcrichton

This patch adds document which explains when to use `OSRng` in
cryptographic context, and explains why we use `/dev/urandom` instead
of `/dev/random`.

src/librand/lib.rs

@@ -30,20 +30,27 @@ after generating 32 KiB of random data.
 
 # Cryptographic security
 
-An application that requires random numbers for cryptographic purposes
+An application that requires an entropy source for cryptographic purposes
-should prefer `OSRng`, which reads randomness from one of the source
+must use `OSRng`, which reads randomness from the source that the operating
-that the operating system provides (e.g. `/dev/urandom` on
+system provides (e.g. `/dev/urandom` on Unixes or `CryptGenRandom()` on Windows).
-Unixes). The other random number generators provided by this module
+The other random number generators provided by this module are not suitable
-are either known to be insecure (`XorShiftRng`), or are not verified
+for such purposes.
-to be secure (`IsaacRng`, `Isaac64Rng` and `StdRng`).
 
-*Note*: on Linux, `/dev/random` is more secure than `/dev/urandom`,
+*Note*: many Unix systems provide `/dev/random` as well as `/dev/urandom`.
-but it is a blocking RNG, and will wait until it has determined that
+This module uses `/dev/urandom` for the following reasons:
-it has collected enough entropy to fulfill a request for random
+
-data. It can be used with the `Rng` trait provided by this module by
+-   On Linux, `/dev/random` may block if entropy pool is empty; `/dev/urandom` will not block.
-opening the file and passing it to `reader::ReaderRng`. Since it
+    This does not mean that `/dev/random` provides better output than
-blocks, `/dev/random` should only be used to retrieve small amounts of
+    `/dev/urandom`; the kernel internally runs a cryptographically secure pseudorandom
-randomness.
+    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.
+    If an application likely to be run soon after first booting, or on a system with very
+    few entropy sources, one should consider using `/dev/random` via `ReaderRng`.
+-   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.)
 
 # Examples
 

src/librand/os.rs

@@ -109,6 +109,7 @@ mod imp {
                                      CRYPT_VERIFYCONTEXT | CRYPT_SILENT)
             };
 
+            // FIXME #13259:
             // It turns out that if we can't acquire a context with the
             // NTE_BAD_SIGNATURE error code, the documentation states:
             //