Document use of /dev/urandom vs /dev/random (#311)

Also, on platforms where the devices are the same, prefer using
/dev/urandom.

Documentation of the devices being the same:
- macOS [`random(4)`](https://www.unix.com/man-page/mojave/4/urandom/)
- DragonFly [`getrandom(2)`](https://leaf.dragonflybsd.org/cgi/web-man?command=getrandom)
- Haiku [implementation](https://github.com/haiku/haiku/blob/f40bacae87f37276be7d107a6b3d41ca97b4d82c/src/add-ons/kernel/bus_managers/random/driver.cpp#L217-L222)

Signed-off-by: Joe Richey <[email protected]>

Signed-off-by: Joe Richey <[email protected]>

Author: josephlr

src/lib.rs

@@ -14,21 +14,21 @@
 //! | ----------------- | ------------------ | --------------
 //! | Linux, Android    | `*‑linux‑*`        | [`getrandom`][1] system call if available, otherwise [`/dev/urandom`][2] after successfully polling `/dev/random`
 //! | Windows           | `*‑windows‑*`      | [`BCryptGenRandom`]
-//! | macOS             | `*‑apple‑darwin`   | [`getentropy`][3] if available, otherwise [`/dev/random`][4] (identical to `/dev/urandom`)
+//! | macOS             | `*‑apple‑darwin`   | [`getentropy`][3] if available, otherwise [`/dev/urandom`][4] (identical to `/dev/random`)
 //! | iOS               | `*‑apple‑ios`      | [`SecRandomCopyBytes`]
 //! | FreeBSD           | `*‑freebsd`        | [`getrandom`][5] if available, otherwise [`kern.arandom`][6]
 //! | OpenBSD           | `*‑openbsd`        | [`getentropy`][7]
 //! | NetBSD            | `*‑netbsd`         | [`kern.arandom`][8]
-//! | Dragonfly BSD     | `*‑dragonfly`      | [`getrandom`][9] if available, otherwise [`/dev/random`][10]
+//! | Dragonfly BSD     | `*‑dragonfly`      | [`getrandom`][9] if available, otherwise [`/dev/urandom`][10] (identical to `/dev/random`)
 //! | Solaris, illumos  | `*‑solaris`, `*‑illumos` | [`getrandom`][11] if available, otherwise [`/dev/random`][12]
 //! | Fuchsia OS        | `*‑fuchsia`        | [`cprng_draw`]
 //! | Redox             | `*‑redox`          | `/dev/urandom`
-//! | Haiku             | `*‑haiku`          | `/dev/random` (identical to `/dev/urandom`)
+//! | Haiku             | `*‑haiku`          | `/dev/urandom` (identical to `/dev/random`)
 //! | Hermit            | `x86_64-*-hermit`  | [`RDRAND`]
 //! | SGX               | `x86_64‑*‑sgx`     | [`RDRAND`]
 //! | VxWorks           | `*‑wrs‑vxworks‑*`  | `randABytes` after checking entropy pool initialization with `randSecure`
 //! | ESP-IDF           | `*‑espidf`         | [`esp_fill_random`]
-//! | Emscripten        | `*‑emscripten`     | `/dev/random` (identical to `/dev/urandom`)
+//! | Emscripten        | `*‑emscripten`     | `/dev/urandom` (identical to `/dev/random`)
 //! | WASI              | `wasm32‑wasi`      | [`random_get`]
 //! | Web Browser and Node.js | `wasm32‑*‑unknown` | [`Crypto.getRandomValues`] if available, then [`crypto.randomFillSync`] if on Node.js, see [WebAssembly support]
 //! | SOLID             | `*-kmc-solid_*`    | `SOLID_RNG_SampleRandomBytes`
@@ -150,7 +150,7 @@
 //! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html
 //! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html
 //! [3]: https://www.unix.com/man-page/mojave/2/getentropy/
-//! [4]: https://www.unix.com/man-page/mojave/4/random/
+//! [4]: https://www.unix.com/man-page/mojave/4/urandom/
 //! [5]: https://www.freebsd.org/cgi/man.cgi?query=getrandom&manpath=FreeBSD+12.0-stable
 //! [6]: https://www.freebsd.org/cgi/man.cgi?query=random&sektion=4
 //! [7]: https://man.openbsd.org/getentropy.2

src/use_file.rs

@@ -18,16 +18,21 @@ use core::{
     sync::atomic::{AtomicUsize, Ordering::Relaxed},
 };
 
+// We prefer using /dev/urandom and only use /dev/random if the OS
+// documentation indicates that /dev/urandom is insecure.
+// On Solaris/Illumos, see src/solaris_illumos.rs
+// On Dragonfly, Haiku, and macOS, the devices are identical.
+#[cfg(any(target_os = "solaris", target_os = "illumos"))]
+const FILE_PATH: &str = "/dev/random\0";
 #[cfg(any(
+    target_os = "android",
+    target_os = "linux",
+    target_os = "redox",
     target_os = "dragonfly",
     target_os = "emscripten",
     target_os = "haiku",
-    target_os = "macos",
-    target_os = "solaris",
-    target_os = "illumos"
+    target_os = "macos"
 ))]
-const FILE_PATH: &str = "/dev/random\0";
-#[cfg(any(target_os = "android", target_os = "linux", target_os = "redox"))]
 const FILE_PATH: &str = "/dev/urandom\0";
 
 pub fn getrandom_inner(dest: &mut [MaybeUninit<u8>]) -> Result<(), Error> {