Simplify and deprecate EntropyRng

Author: dhardy

README.md

@@ -102,9 +102,6 @@ functionality depending on `std`:
 
 - `thread_rng()`, and `random()` are not available, as they require thread-local
   storage and an entropy source.
-- `OsRng` and `EntropyRng` are unavailable.
-- `JitterRng` code is still present, but a nanosecond timer must be provided via
-  `JitterRng::new_with_timer`
 - Since no external entropy is available, it is not possible to create
   generators with fresh seeds using the `FromEntropy` trait (user must provide
   a seed).

benches/generators.rs

@@ -25,7 +25,7 @@ use test::{black_box, Bencher};
 
 use rand::prelude::*;
 use rand::rngs::adapter::ReseedingRng;
-use rand::rngs::{OsRng, JitterRng, EntropyRng};
+use rand::rngs::{OsRng, JitterRng};
 use rand_isaac::{IsaacRng, Isaac64Rng};
 use rand_chacha::ChaChaRng;
 use rand_hc::{Hc128Rng, Hc128Core};
@@ -185,7 +185,7 @@ const RESEEDING_THRESHOLD: u64 = 1024*1024*1024; // something high enough to get
 fn reseeding_hc128_bytes(b: &mut Bencher) {
     let mut rng = ReseedingRng::new(Hc128Core::from_entropy(),
                                     RESEEDING_THRESHOLD,
-                                    EntropyRng::new());
+                                    OsRng);
     let mut buf = [0u8; BYTES_LEN];
     b.iter(|| {
         for _ in 0..RAND_BENCH_N {
@@ -202,7 +202,7 @@ macro_rules! reseeding_uint {
         fn $fnn(b: &mut Bencher) {
             let mut rng = ReseedingRng::new(Hc128Core::from_entropy(),
                                             RESEEDING_THRESHOLD,
-                                            EntropyRng::new());
+                                            OsRng);
             b.iter(|| {
                 let mut accum: $ty = 0;
                 for _ in 0..RAND_BENCH_N {

src/lib.rs

@@ -456,7 +456,7 @@ impl_as_byte_slice_arrays!(!div 4096, N,N,N,N,N,N,N,);
 /// entropy. This trait is automatically implemented for any PRNG implementing
 /// [`SeedableRng`] and is not intended to be implemented by users.
 ///
-/// This is equivalent to using `SeedableRng::from_rng(EntropyRng::new())` then
+/// This is equivalent to using `SeedableRng::from_rng(OsRng)` then
 /// unwrapping the result.
 ///
 /// Since this is convenient and secure, it is the recommended way to create
@@ -477,7 +477,7 @@ impl_as_byte_slice_arrays!(!div 4096, N,N,N,N,N,N,N,);
 /// println!("Random die roll: {}", rng.gen_range(1, 7));
 /// ```
 ///
-/// [`EntropyRng`]: rngs::EntropyRng
+/// [`OsRng`]: rngs::OsRng
 #[cfg(feature="std")]
 pub trait FromEntropy: SeedableRng {
     /// Creates a new instance, automatically seeded with fresh entropy.
@@ -497,11 +497,11 @@ pub trait FromEntropy: SeedableRng {
     /// ```
     /// # use rand::Error;
     /// use rand::prelude::*;
-    /// use rand::rngs::EntropyRng;
+    /// use rand::rngs::OsRng;
     ///
     /// # fn try_inner() -> Result<(), Error> {
     /// // This uses StdRng, but is valid for any R: SeedableRng
-    /// let mut rng = StdRng::from_rng(EntropyRng::new())?;
+    /// let mut rng = StdRng::from_rng(OsRng)?;
     ///
     /// println!("random number: {}", rng.gen_range(1, 10));
     /// # Ok(())
@@ -515,7 +515,7 @@ pub trait FromEntropy: SeedableRng {
 #[cfg(feature="std")]
 impl<R: SeedableRng> FromEntropy for R {
     fn from_entropy() -> R {
-        R::from_rng(rngs::EntropyRng::new()).unwrap_or_else(|err|
+        R::from_rng(rngs::OsRng).unwrap_or_else(|err|
             panic!("FromEntropy::from_entropy() failed: {}", err))
     }
 }

src/rngs/entropy.rs

@@ -8,51 +8,20 @@
 
 //! Entropy generator, or wrapper around external generators
 
-use rand_core::{RngCore, CryptoRng, Error, ErrorKind, impls};
+#![allow(deprecated)]   // whole module is deprecated
+
+use rand_core::{RngCore, CryptoRng, Error};
 #[allow(unused)]
-use rngs;
+use rngs::OsRng;
 
 /// An interface returning random data from external source(s), provided
 /// specifically for securely seeding algorithmic generators (PRNGs).
 ///
-/// Where possible, `EntropyRng` retrieves random data from the operating
-/// system's interface for random numbers ([`OsRng`]); if that fails it will
-/// fall back to the [`JitterRng`] entropy collector. In the latter case it will
-/// still try to use [`OsRng`] on the next usage.
-///
-/// If no secure source of entropy is available `EntropyRng` will panic on use;
-/// i.e. it should never output predictable data.
-///
-/// This is either a little slow ([`OsRng`] requires a system call) or extremely
-/// slow ([`JitterRng`] must use significant CPU time to generate sufficient
-/// jitter); for better performance it is common to seed a local PRNG from
-/// external entropy then primarily use the local PRNG ([`thread_rng`] is
-/// provided as a convenient, local, automatically-seeded CSPRNG).
-///
-/// # Panics
-///
-/// On most systems, like Windows, Linux, macOS and *BSD on common hardware, it
-/// is highly unlikely for both [`OsRng`] and [`JitterRng`] to fail. But on
-/// combinations like webassembly without Emscripten or stdweb both sources are
-/// unavailable. If both sources fail, only [`try_fill_bytes`] is able to
-/// report the error, and only the one from `OsRng`. The other [`RngCore`]
-/// methods will panic in case of an error.
-///
-/// [`OsRng`]: rngs::OsRng
-/// [`thread_rng`]: crate::thread_rng
-/// [`JitterRng`]: crate::rngs::JitterRng
-/// [`try_fill_bytes`]: RngCore::try_fill_bytes
+/// This is deprecated. It is suggested you use [`rngs::OsRng`] instead.
 #[derive(Debug)]
+#[deprecated(since="0.7.0", note="use rngs::OsRng instead")]
 pub struct EntropyRng {
-    source: Source,
-}
-
-#[derive(Debug)]
-enum Source {
-    Os(Os),
-    Custom(Custom),
-    Jitter(Jitter),
-    None,
+    source: OsRng,
 }
 
 impl EntropyRng {
@@ -62,7 +31,7 @@ impl EntropyRng {
     /// those are done on first use. This is done to make `new` infallible,
     /// and `try_fill_bytes` the only place to report errors.
     pub fn new() -> Self {
-        EntropyRng { source: Source::None }
+        EntropyRng { source: OsRng }
     }
 }
 
@@ -74,167 +43,25 @@ impl Default for EntropyRng {
 
 impl RngCore for EntropyRng {
     fn next_u32(&mut self) -> u32 {
-        impls::next_u32_via_fill(self)
+        self.source.next_u32()
     }
 
     fn next_u64(&mut self) -> u64 {
-        impls::next_u64_via_fill(self)
+        self.source.next_u64()
     }
 
     fn fill_bytes(&mut self, dest: &mut [u8]) {
-        self.try_fill_bytes(dest).unwrap_or_else(|err|
-                panic!("all entropy sources failed; first error: {}", err))
+        self.source.fill_bytes(dest)
     }
 
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
-        let mut reported_error = None;
-
-        if let Source::Os(ref mut os_rng) = self.source {
-            match os_rng.fill(dest) {
-                Ok(()) => return Ok(()),
-                Err(err) => {
-                    warn!("EntropyRng: OsRng failed \
-                          [trying other entropy sources]: {}", err);
-                    reported_error = Some(err);
-                },
-            }
-        } else if Os::is_supported() {
-            match Os::new_and_fill(dest) {
-                Ok(os_rng) => {
-                    debug!("EntropyRng: using OsRng");
-                    self.source = Source::Os(os_rng);
-                    return Ok(());
-                },
-                Err(err) => { reported_error = reported_error.or(Some(err)) },
-            }
-        }
-
-        if let Source::Custom(ref mut rng) = self.source {
-            match rng.fill(dest) {
-                Ok(()) => return Ok(()),
-                Err(err) => {
-                    warn!("EntropyRng: custom entropy source failed \
-                          [trying other entropy sources]: {}", err);
-                    reported_error = Some(err);
-                },
-            }
-        } else if Custom::is_supported() {
-            match Custom::new_and_fill(dest) {
-                Ok(custom) => {
-                    debug!("EntropyRng: using custom entropy source");
-                    self.source = Source::Custom(custom);
-                    return Ok(());
-                },
-                Err(err) => { reported_error = reported_error.or(Some(err)) },
-            }
-        }
-
-        if let Source::Jitter(ref mut jitter_rng) = self.source {
-            match jitter_rng.fill(dest) {
-                Ok(()) => return Ok(()),
-                Err(err) => {
-                    warn!("EntropyRng: JitterRng failed: {}", err);
-                    reported_error = Some(err);
-                },
-            }
-        } else if Jitter::is_supported() {
-            match Jitter::new_and_fill(dest) {
-                Ok(jitter_rng) => {
-                    debug!("EntropyRng: using JitterRng");
-                    self.source = Source::Jitter(jitter_rng);
-                    return Ok(());
-                },
-                Err(err) => { reported_error = reported_error.or(Some(err)) },
-            }
-        }
-
-        if let Some(err) = reported_error {
-            Err(Error::with_cause(ErrorKind::Unavailable,
-                                  "All entropy sources failed",
-                                  err))
-        } else {
-            Err(Error::new(ErrorKind::Unavailable,
-                           "No entropy sources available"))
-        }
+        self.source.try_fill_bytes(dest)
     }
 }
 
 impl CryptoRng for EntropyRng {}
 
 
-
-trait EntropySource {
-    fn new_and_fill(dest: &mut [u8]) -> Result<Self, Error>
-        where Self: Sized;
-
-    fn fill(&mut self, dest: &mut [u8]) -> Result<(), Error>;
-
-    fn is_supported() -> bool { true }
-}
-
-#[allow(unused)]
-#[derive(Clone, Debug)]
-struct NoSource;
-
-#[allow(unused)]
-impl EntropySource for NoSource {
-    fn new_and_fill(dest: &mut [u8]) -> Result<Self, Error> {
-        Err(Error::new(ErrorKind::Unavailable, "Source not supported"))
-    }
-
-    fn fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
-        unreachable!()
-    }
-
-    fn is_supported() -> bool { false }
-}
-
-
-#[cfg(feature="getrandom")]
-#[derive(Clone, Debug)]
-pub struct Os(rngs::OsRng);
-
-#[cfg(feature="getrandom")]
-impl EntropySource for Os {
-    fn new_and_fill(dest: &mut [u8]) -> Result<Self, Error> {
-        let rng = rngs::OsRng;
-        rngs::OsRng.try_fill_bytes(dest)?;
-        Ok(Os(rng))
-    }
-
-    fn fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
-        self.0.try_fill_bytes(dest)
-    }
-}
-
-#[cfg(not(feature="std"))]
-type Os = NoSource;
-
-
-type Custom = NoSource;
-
-
-#[cfg(not(target_arch = "wasm32"))]
-#[derive(Clone, Debug)]
-pub struct Jitter(rngs::JitterRng);
-
-#[cfg(not(target_arch = "wasm32"))]
-impl EntropySource for Jitter {
-    fn new_and_fill(dest: &mut [u8]) -> Result<Self, Error> {
-        let mut rng = rngs::JitterRng::new()?;
-        rng.try_fill_bytes(dest)?;
-        Ok(Jitter(rng))
-    }
-
-    fn fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
-        self.0.try_fill_bytes(dest)
-    }
-}
-
-#[cfg(target_arch = "wasm32")]
-type Jitter = NoSource;
-
-
 #[cfg(test)]
 mod test {
     use super::*;

src/rngs/mod.rs

@@ -10,7 +10,7 @@
 //!
 //! - [`ThreadRng`], a fast, secure, auto-seeded thread-local generator
 //! - [`StdRng`] and [`SmallRng`], algorithms to cover typical usage
-//! - [`EntropyRng`], [`OsRng`] and [`JitterRng`] as entropy sources
+//! - [`OsRng`] as an entropy source
 //! - [`mock::StepRng`] as a simple counter for tests
 //! - [`adapter::ReadRng`] to read from a file/stream
 //! - [`adapter::ReseedingRng`] to reseed a PRNG on clone / process fork etc.
@@ -26,8 +26,6 @@
 //! use that to seed its own PRNG; [`OsRng`] provides an interface to this.
 //! [`JitterRng`] is an entropy collector included with Rand that measures
 //! jitter in the CPU execution time, and jitter in memory access time.
-//! [`EntropyRng`] is a wrapper that uses the best entropy source that is
-//! available.
 //!
 //! ## Pseudo-random number generators
 //!
@@ -78,7 +76,7 @@
 //! - [`FromEntropy::from_entropy`]; this is the most convenient way to seed
 //!   with fresh, secure random data.
 //! - [`SeedableRng::from_rng`]; this allows seeding from another PRNG or
-//!   from an entropy source such as [`EntropyRng`].
+//!   from an entropy source such as [`OsRng`].
 //! - [`SeedableRng::from_seed`]; this is mostly useful if you wish to be able
 //!   to reproduce the output sequence by using a fixed seed. (Don't use
 //!   [`StdRng`] or [`SmallRng`] in this case since different algorithms may be
@@ -138,7 +136,6 @@
 //! [`SmallRng`]: rngs::SmallRng
 //! [`StdRng`]: rngs::StdRng
 //! [`ThreadRng`]: rngs::ThreadRng
-//! [`EntropyRng`]: rngs::EntropyRng
 //! [`JitterRng`]: rngs::JitterRng
 //! [`mock::StepRng`]: rngs::mock::StepRng
 //! [`adapter::ReadRng`]: rngs::adapter::ReadRng
@@ -156,6 +153,7 @@ mod std;
 
 
 pub use rand_jitter::{JitterRng, TimerError};
+#[allow(deprecated)]
 #[cfg(feature="std")] pub use self::entropy::EntropyRng;
 
 pub use self::small::SmallRng;