BlockRng: template over element type; add doc

Author: dhardy

rand-core/src/impls.rs

@@ -167,30 +167,30 @@ pub fn next_u64_via_fill<R: RngCore + ?Sized>(rng: &mut R) -> u64 {
 /// Wrapper around PRNGs that implement [`BlockRngCore`] to keep a results
 /// buffer and offer the methods from [`RngCore`].
 ///
-/// `BlockRng` has optimized methods to read from the output array that the
-/// algorithm of many cryptograpic RNGs generates natively. Also they handle the
-/// bookkeeping when to generate a new batch of values.
-///
-/// `next_u32` simply indexes the array. `next_u64` tries to read two `u32`
-/// values at a time if possible, and handles edge cases like when only one
-/// value is left. `try_fill_bytes` is optimized use the [`BlockRngCore`]
-/// implementation to write the results directly to the destination slice.
+/// `BlockRng` has heavily optimized implementations of the [`RngCore`] methods
+/// reading values from the results buffer, as well as
+/// calling `BlockRngCore::generate` directly on the output array when
+/// `fill_bytes` / `try_fill_bytes` is called on a large array. These methods
+/// also handle the bookkeeping of when to generate a new batch of values.
 /// No generated values are ever thown away.
 ///
+/// Currently `BlockRng` only implements `RngCore` for buffers which are slices
+/// of `u32` elements; this may be extended to other types in the future.
+///
 /// For easy initialization `BlockRng` also implements [`SeedableRng`].
 ///
 /// [`BlockRngCore`]: ../BlockRngCore.t.html
 /// [`RngCore`]: ../RngCore.t.html
 /// [`SeedableRng`]: ../SeedableRng.t.html
 #[derive(Clone)]
-pub struct BlockRng<R: BlockRngCore<u32>> {
+pub struct BlockRng<T, R: BlockRngCore<T>> {
     pub core: R,
     pub results: R::Results,
     pub index: usize,
 }
 
 // Custom Debug implementation that does not expose the contents of `results`.
-impl<R: BlockRngCore<u32>+fmt::Debug> fmt::Debug for BlockRng<R> {
+impl<T, R: BlockRngCore<T> + fmt::Debug> fmt::Debug for BlockRng<T, R> {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
         fmt.debug_struct("BlockRng")
            .field("core", &self.core)
@@ -200,7 +200,7 @@ impl<R: BlockRngCore<u32>+fmt::Debug> fmt::Debug for BlockRng<R> {
     }
 }
 
-impl<R: BlockRngCore<u32>> RngCore for BlockRng<R> {
+impl<R: BlockRngCore<u32>> RngCore for BlockRng<u32, R> {
     #[inline(always)]
     fn next_u32(&mut self) -> u32 {
         if self.index >= self.results.as_ref().len() {
@@ -308,7 +308,7 @@ impl<R: BlockRngCore<u32>> RngCore for BlockRng<R> {
     }
 }
 
-impl<R: BlockRngCore<u32> + SeedableRng> SeedableRng for BlockRng<R> {
+impl<R: BlockRngCore<u32> + SeedableRng> SeedableRng for BlockRng<u32, R> {
     type Seed = R::Seed;
 
     fn from_seed(seed: Self::Seed) -> Self {
@@ -330,6 +330,6 @@ impl<R: BlockRngCore<u32> + SeedableRng> SeedableRng for BlockRng<R> {
     }
 }
 
-impl<R: BlockRngCore<u32>+CryptoRng> CryptoRng for BlockRng<R> {}
+impl<T, R: BlockRngCore<T> + CryptoRng> CryptoRng for BlockRng<T, R> {}
 
 // TODO: implement tests for the above

rand-core/src/lib.rs

@@ -162,9 +162,44 @@ pub trait RngCore {
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>;
 }
 
-/// Trait for RNGs that do not generate random numbers one at a time, but in
-/// blocks. Especially for cryptographic RNG's it is common to generate 16 or
-/// more results at a time.
+/// A trait for RNGs which do not generate random numbers individually, but in
+/// blocks (typically `[u32; N]`). This technique is commonly used by
+/// cryptographic RNGs to improve performance.
+/// 
+/// Usage of this trait is optional, but provides two advantages:
+/// implementations only need to concern themselves with generation of the
+/// block, not the various `RngCore` methods (especially `fill_bytes`, where the
+/// optimal implementations are not trivial), and this allows `ReseedingRng` to
+/// perform periodic reseeding with very low overhead.
+/// 
+/// # Example
+/// 
+/// ```norun
+/// use rand_core::BlockRngCore;
+/// use rand_core::impls::BlockRng;
+/// 
+/// struct MyRngCore;
+/// 
+/// impl BlockRngCore for MyRngCore {
+///     type Results = [u32; 16];
+///     
+///     fn generate(&mut self, results: &mut Self::Results) {
+///         unimplemented!()
+///     }
+/// }
+/// 
+/// impl SeedableRng for MyRngCore {
+///     type Seed = unimplemented!();
+///     fn from_seed(seed: Self::Seed) -> Self {
+///         unimplemented!()
+///     }
+/// }
+/// 
+/// // optionally, also implement CryptoRng for MyRngCore
+/// 
+/// // Final RNG.
+/// type MyRng = BlockRng<u32, MyRngCore>;
+/// ```
 pub trait BlockRngCore<T>: Sized {
     /// Results type. This is the 'block' an RNG implementing `BlockRngCore`
     /// generates, which will usually be an array like `[u32; 16]`.
@@ -174,8 +209,8 @@ pub trait BlockRngCore<T>: Sized {
     fn generate(&mut self, results: &mut Self::Results);
 }
 
-/// A marker trait for an `Rng` which may be considered for use in
-/// cryptography.
+/// A marker trait used to indicate that an `RngCore` or `BlockRngCore`
+/// implementation is supposed to be cryptographically secure.
 /// 
 /// *Cryptographically secure generators*, also known as *CSPRNGs*, should
 /// satisfy an additional properties over other generators: given the first

src/prng/chacha.rs

@@ -63,7 +63,7 @@ const STATE_WORDS: usize = 16;
 ///
 /// [`set_rounds`]: #method.set_counter
 #[derive(Clone, Debug)]
-pub struct ChaChaRng(BlockRng<ChaChaCore>);
+pub struct ChaChaRng(BlockRng<u32, ChaChaCore>);
 
 impl RngCore for ChaChaRng {
     #[inline]
@@ -91,11 +91,11 @@ impl SeedableRng for ChaChaRng {
     type Seed = <ChaChaCore as SeedableRng>::Seed;
 
     fn from_seed(seed: Self::Seed) -> Self {
-        ChaChaRng(BlockRng::<ChaChaCore>::from_seed(seed))
+        ChaChaRng(BlockRng::<u32, ChaChaCore>::from_seed(seed))
     }
 
     fn from_rng<R: RngCore>(rng: &mut R) -> Result<Self, Error> {
-        BlockRng::<ChaChaCore>::from_rng(rng).map(|rng| ChaChaRng(rng))
+        BlockRng::<u32, ChaChaCore>::from_rng(rng).map(|rng| ChaChaRng(rng))
     }
 }
 

src/prng/hc128.rs

@@ -62,7 +62,7 @@ const SEED_WORDS: usize = 8; // 128 bit key followed by 128 bit iv
 /// [5]: Internet Engineering Task Force (Februari 2015),
 ///      ["Prohibiting RC4 Cipher Suites"](https://tools.ietf.org/html/rfc7465).
 #[derive(Clone, Debug)]
-pub struct Hc128Rng(BlockRng<Hc128Core>);
+pub struct Hc128Rng(BlockRng<u32, Hc128Core>);
 
 impl RngCore for Hc128Rng {
     #[inline(always)]
@@ -88,16 +88,17 @@ impl SeedableRng for Hc128Rng {
     type Seed = <Hc128Core as SeedableRng>::Seed;
 
     fn from_seed(seed: Self::Seed) -> Self {
-        Hc128Rng(BlockRng::<Hc128Core>::from_seed(seed))
+        Hc128Rng(BlockRng::<u32, Hc128Core>::from_seed(seed))
     }
 
     fn from_rng<R: RngCore>(rng: &mut R) -> Result<Self, Error> {
-        BlockRng::<Hc128Core>::from_rng(rng).map(|rng| Hc128Rng(rng))
+        BlockRng::<u32, Hc128Core>::from_rng(rng).map(|rng| Hc128Rng(rng))
     }
 }
 
 impl CryptoRng for Hc128Rng {}
 
+/// The core of `Hc128Rng`, used with `BlockRng`.
 #[derive(Clone)]
 pub struct Hc128Core {
     t: [u32; 1024],

src/reseeding.rs

@@ -11,6 +11,9 @@
 //! A wrapper around another PRNG that reseeds it after it
 //! generates a certain number of random bytes.
 
+use core::marker::PhantomData;
+use core::mem::size_of;
+
 use rand_core::{RngCore, BlockRngCore, CryptoRng, SeedableRng, Error, ErrorKind};
 use rand_core::impls::BlockRng;
 
@@ -51,12 +54,12 @@ use rand_core::impls::BlockRng;
 /// If handling the source error fails `ReseedingRng` will continue generating
 /// data from the wrapped PRNG without reseeding.
 #[derive(Debug)]
-pub struct ReseedingRng<R, Rsdr>(BlockRng<ReseedingCore<R, Rsdr>>)
-where R: BlockRngCore<u32> + SeedableRng,
+pub struct ReseedingRng<T, R, Rsdr>(BlockRng<T, ReseedingCore<T, R, Rsdr>>)
+where R: BlockRngCore<T> + SeedableRng,
       Rsdr: RngCore;
 
-impl<R, Rsdr> ReseedingRng<R, Rsdr>
-where R: BlockRngCore<u32> + SeedableRng,
+impl<T, R, Rsdr> ReseedingRng<T, R, Rsdr>
+where R: BlockRngCore<T> + SeedableRng,
       Rsdr: RngCore
 {
     /// Create a new `ReseedingRng` with the given parameters.
@@ -67,13 +70,14 @@ where R: BlockRngCore<u32> + SeedableRng,
     /// * `threshold`: the number of generated bytes after which to reseed the RNG.
     /// * `reseeder`: the RNG to use for reseeding.
     pub fn new(rng: R, threshold: u64, reseeder: Rsdr)
-        -> ReseedingRng<R, Rsdr>
+        -> ReseedingRng<T, R, Rsdr>
     {
         assert!(threshold <= ::core::i64::MAX as u64);
         let results_empty = R::Results::default();
         ReseedingRng(
             BlockRng {
                 core: ReseedingCore {
+                    phantom: PhantomData,
                     inner: rng,
                     reseeder: reseeder,
                     threshold: threshold as i64,
@@ -91,7 +95,11 @@ where R: BlockRngCore<u32> + SeedableRng,
     }
 }
 
-impl<R: BlockRngCore<u32> + SeedableRng, Rsdr: RngCore> RngCore for ReseedingRng<R, Rsdr> {
+// TODO: this should be implemented for any type where the inner type
+// implements RngCore, but we can't specify that because ReseedingCore is private
+impl<R, Rsdr: RngCore> RngCore for ReseedingRng<u32, R, Rsdr>
+where R: BlockRngCore<u32> + SeedableRng
+{
     #[inline(always)]
     fn next_u32(&mut self) -> u32 {
         self.0.next_u32()
@@ -111,23 +119,24 @@ impl<R: BlockRngCore<u32> + SeedableRng, Rsdr: RngCore> RngCore for ReseedingRng
     }
 }
 
-impl<R, Rsdr> CryptoRng for ReseedingRng<R, Rsdr>
-where R: BlockRngCore<u32> + SeedableRng + CryptoRng,
+impl<T, R, Rsdr> CryptoRng for ReseedingRng<T, R, Rsdr>
+where R: BlockRngCore<T> + SeedableRng + CryptoRng,
       Rsdr: RngCore + CryptoRng {}
 
 #[derive(Debug)]
-struct ReseedingCore<R, Rsdr> {
+struct ReseedingCore<T, R, Rsdr> {
+    phantom: PhantomData<T>, // associated with R, but not a parameter; used below
     inner: R,
     reseeder: Rsdr,
     threshold: i64,
     bytes_until_reseed: i64,
 }
 
-impl<R, Rsdr> BlockRngCore<u32> for ReseedingCore<R, Rsdr>
-where R: BlockRngCore<u32> + SeedableRng,
+impl<T, R, Rsdr> BlockRngCore<T> for ReseedingCore<T, R, Rsdr>
+where R: BlockRngCore<T> + SeedableRng,
       Rsdr: RngCore
 {
-    type Results = <R as BlockRngCore<u32>>::Results;
+    type Results = <R as BlockRngCore<T>>::Results;
 
     fn generate(&mut self, results: &mut Self::Results) {
         if self.bytes_until_reseed <= 0 {
@@ -136,13 +145,14 @@ where R: BlockRngCore<u32> + SeedableRng,
             // returning from a non-inlined function.
             return self.reseed_and_generate(results);
         }
-        self.bytes_until_reseed -= results.as_ref().len() as i64 * 4;
+        let num_bytes = results.as_ref().len() * size_of::<T>();
+        self.bytes_until_reseed -= num_bytes as i64;
         self.inner.generate(results);
     }
 }
 
-impl<R, Rsdr> ReseedingCore<R, Rsdr>
-where R: BlockRngCore<u32> + SeedableRng,
+impl<T, R, Rsdr> ReseedingCore<T, R, Rsdr>
+where R: BlockRngCore<T> + SeedableRng,
       Rsdr: RngCore
 {
     /// Reseed the internal PRNG.
@@ -153,39 +163,33 @@ where R: BlockRngCore<u32> + SeedableRng,
         })
     }
 
-    /// Reseed the internal PRNG.
-    ///
-    /// If reseeding fails, this will try to work around errors intelligently
-    /// by adjusting the delay until automatic reseeding next occurs.
-    fn auto_reseed(&mut self) {
+    #[inline(never)]
+    fn reseed_and_generate(&mut self,
+                           results: &mut <Self as BlockRngCore<T>>::Results)
+    {
         trace!("Reseeding RNG after {} generated bytes",
                self.threshold - self.bytes_until_reseed);
-        if let Err(e) = self.reseed()  {
+        let threshold = if let Err(e) = self.reseed()  {
             let delay = match e.kind {
                 ErrorKind::Transient => 0,
                 kind @ _ if kind.should_retry() => self.threshold >> 8,
                 _ => self.threshold,
             };
             warn!("Reseeding RNG delayed reseeding by {} bytes due to \
                     error from source: {}", delay, e);
-            self.bytes_until_reseed = delay;
+            delay
         } else {
-            self.bytes_until_reseed = self.threshold;
-        }
-    }
-
-    #[inline(never)]
-    fn reseed_and_generate(&mut self,
-                           results: &mut <Self as BlockRngCore<u32>>::Results)
-    {
-        self.auto_reseed();
-        self.bytes_until_reseed -= results.as_ref().len() as i64 * 4;
+            self.threshold
+        };
+        
+        let num_bytes = results.as_ref().len() * size_of::<T>();
+        self.bytes_until_reseed = threshold - num_bytes as i64;
         self.inner.generate(results);
     }
 }
 
-impl<R, Rsdr> CryptoRng for ReseedingCore<R, Rsdr>
-where R: BlockRngCore<u32> + SeedableRng + CryptoRng,
+impl<T, R, Rsdr> CryptoRng for ReseedingCore<T, R, Rsdr>
+where R: BlockRngCore<T> + SeedableRng + CryptoRng,
       Rsdr: RngCore + CryptoRng {}
 
 #[cfg(test)]

src/thread_rng.rs

@@ -32,11 +32,11 @@ const THREAD_RNG_RESEED_THRESHOLD: u64 = 32*1024*1024; // 32 MiB
 /// [`thread_rng`]: fn.thread_rng.html
 #[derive(Clone, Debug)]
 pub struct ThreadRng {
-    rng: Rc<RefCell<ReseedingRng<Hc128Core, EntropyRng>>>,
+    rng: Rc<RefCell<ReseedingRng<u32, Hc128Core, EntropyRng>>>,
 }
 
 thread_local!(
-    static THREAD_RNG_KEY: Rc<RefCell<ReseedingRng<Hc128Core, EntropyRng>>> = {
+    static THREAD_RNG_KEY: Rc<RefCell<ReseedingRng<u32, Hc128Core, EntropyRng>>> = {
         let mut entropy_source = EntropyRng::new();
         let r = Hc128Core::from_rng(&mut entropy_source).unwrap_or_else(|err|
                 panic!("could not initialize thread_rng: {}", err));