From 39666314679d8967b74d520aecf06946e15dfda1 Mon Sep 17 00:00:00 2001
From: Diggory Hardy <git@dhardy.name>
Date: Tue, 27 Feb 2018 17:44:32 +0000
Subject: [PATCH] Add CryptoRng marker trait

---
 src/jitter.rs      |  4 +++-
 src/lib.rs         | 22 ++++++++++++++++++++++
 src/prng/chacha.rs |  4 +++-
 src/prng/hc128.rs  |  4 +++-
 4 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/src/jitter.rs b/src/jitter.rs
index 2a5e5015c24..fb5dec521e5 100644
--- a/src/jitter.rs
+++ b/src/jitter.rs
@@ -16,7 +16,7 @@
 
 //! Non-physical true random number generator based on timing jitter.
 
-use {RngCore, Error, ErrorKind, impls};
+use {RngCore, CryptoRng, Error, ErrorKind, impls};
 
 use core::{fmt, mem, ptr};
 #[cfg(feature="std")]
@@ -776,5 +776,7 @@ impl RngCore for JitterRng {
     }
 }
 
+impl CryptoRng for JitterRng {}
+
 // There are no tests included because (1) this is an "external" RNG, so output
 // is not reproducible and (2) `test_timer` *will* fail on some platforms.
diff --git a/src/lib.rs b/src/lib.rs
index 138893fe333..ad7612118e1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -446,6 +446,28 @@ pub trait RngCore {
     }
 }
 
+/// A marker trait for an `Rng` which may be considered for use in
+/// cryptography.
+/// 
+/// *Cryptographically secure generators*, also known as *CSPRNGs*, should
+/// satisfy an additional properties over other generators: given the first
+/// *k* bits of an algorithm's output
+/// sequence, it should not be possible using polynomial-time algorithms to
+/// predict the next bit with probability significantly greater than 50%.
+/// 
+/// Some generators may satisfy an additional property, however this is not
+/// required: if the CSPRNG's state is revealed, it should not be
+/// computationally-feasible to reconstruct output prior to this. Some other
+/// generators allow backwards-computation and are consided *reversible*.
+/// 
+/// Note that this trait is provided for guidance only and cannot guarantee
+/// suitability for cryptographic applications. In general it should only be
+/// implemented for well-reviewed code implementing well-regarded algorithms.
+/// 
+/// Note also that use of a `CryptoRng` does not protect against other
+/// weaknesses such as seeding from a weak entropy source or leaking state.
+pub trait CryptoRng: RngCore {}
+
 /// An automatically-implemented extension trait on [`RngCore`] providing high-level
 /// generic methods for sampling values and other convenience methods.
 /// 
diff --git a/src/prng/chacha.rs b/src/prng/chacha.rs
index 12311382469..93ea639a206 100644
--- a/src/prng/chacha.rs
+++ b/src/prng/chacha.rs
@@ -11,7 +11,7 @@
 //! The ChaCha random number generator.
 
 use core::fmt;
-use {RngCore, SeedableRng};
+use {RngCore, CryptoRng, SeedableRng};
 use {impls, le};
 
 const SEED_WORDS: usize = 8; // 8 words for the 256-bit key
@@ -253,6 +253,8 @@ impl RngCore for ChaChaRng {
     }
 }
 
+impl CryptoRng for ChaChaRng {}
+
 impl SeedableRng for ChaChaRng {
     type Seed = [u8; SEED_WORDS*4];
     fn from_seed(seed: Self::Seed) -> Self {
diff --git a/src/prng/hc128.rs b/src/prng/hc128.rs
index d60f31cd54a..a587fbcecc3 100644
--- a/src/prng/hc128.rs
+++ b/src/prng/hc128.rs
@@ -11,7 +11,7 @@
 //! The HC-128 random number generator.
 
 use core::fmt;
-use {RngCore, SeedableRng};
+use {RngCore, CryptoRng, SeedableRng};
 use {impls, le};
 
 const SEED_WORDS: usize = 8; // 128 bit key followed by 128 bit iv
@@ -394,6 +394,8 @@ impl RngCore for Hc128Rng {
     }
 }
 
+impl CryptoRng for Hc128Rng {}
+
 impl SeedableRng for Hc128Rng {
     type Seed = [u8; SEED_WORDS*4];