Merge pull request #353 from pitdicker/doc-fixes

Documentation improvements to ChaCha and ISAAC

Author: pitdicker

src/prng/chacha.rs

@@ -37,11 +37,13 @@ const STATE_WORDS: usize = 16;
 /// and security, 8 rounds are considered the minimum to be secure. A different
 /// number of rounds can be set using [`set_rounds`].
 ///
-/// We deviate slightly from the ChaCha specification regarding the nonce, which
-/// is used to extend the counter to 128 bits. This is provably as strong as the
-/// original cipher, though, since any distinguishing attack on our variant also
-/// works against ChaCha with a chosen-nonce. See the XSalsa20 [3] security
-/// proof for a more involved example of this.
+/// We deviate slightly from the ChaCha specification regarding the nonce and
+/// the counter. Instead of a 64-bit nonce and 64-bit counter (or a 96-bit nonce
+/// and 32-bit counter in the IETF variant [3]), we use a 128-bit counter. This
+/// is because a nonce does not give a meaningful advantage for ChaCha when used
+/// as an RNG. The modification is provably as strong as the original cipher,
+/// though, since any distinguishing attack on our variant also works against
+/// ChaCha with a chosen nonce.
 ///
 /// The modified word layout is:
 ///
@@ -58,8 +60,8 @@ const STATE_WORDS: usize = 16;
 /// [2]: [eSTREAM: the ECRYPT Stream Cipher Project](
 ///      http://www.ecrypt.eu.org/stream/)
 ///
-/// [3]: Daniel J. Bernstein. [*Extending the Salsa20 nonce.*](
-///      http://cr.yp.to/papers.html#xsalsa)
+/// [3]: [ChaCha20 and Poly1305 for IETF Protocols](
+///       https://tools.ietf.org/html/rfc7539)
 ///
 /// [`set_rounds`]: #method.set_counter
 #[derive(Clone, Debug)]

src/prng/isaac.rs

@@ -28,20 +28,19 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// series of array based random number generator designed by Robert Jenkins
 /// in 1996[1][2].
 ///
-/// Although ISAAC is designed to be cryptographically secure, its design is not
-/// founded in cryptographic theory. Therefore it is _not recommended for_
-/// cryptographic purposes. It is however one of the strongest non-cryptograpic
-/// RNGs, and that while still being reasonably fast.
+/// ISAAC is notably fast and produces excellent quality random numbers for
+/// non-cryptographic applications.
 ///
-/// Where fast random numbers are needed which should still be secure, but where
-/// speed is more important than absolute (cryptographic) security (e.g. to
-/// initialise hashes in the std library), a generator like ISAAC may be a good
-/// choice.
+/// In spite of being designed with cryptographic security in mind, ISAAC hasn't
+/// been stringently cryptanalyzed and thus cryptographers do not not
+/// consensually trust it to be secure. When looking for a secure RNG, prefer
+/// [`Hc128Rng`] instead, which, like ISAAC, is an array-based RNG and one of
+/// the stream-ciphers selected the by eSTREAM contest.
 ///
 /// In 2006 an improvement to ISAAC was suggested by Jean-Philippe Aumasson,
-/// named ISAAC+[3]. But because the specification is not complete, there is no
-/// good implementation, and because the suggested bias may not exist, it is not
-/// implemented here.
+/// named ISAAC+[3]. But because the specification is not complete, because
+/// there is no good implementation, and because the suggested bias may not
+/// exist, it is not implemented here.
 ///
 /// ## Overview of the ISAAC algorithm:
 /// (in pseudo-code)
@@ -84,6 +83,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 ///
 /// [3]: Jean-Philippe Aumasson, [*On the pseudo-random generator ISAAC*](
 ///      https://eprint.iacr.org/2006/438)
+///
+/// [`Hc128Rng`]: prng/hc128/struct.Hc128Rng.html
 #[cfg_attr(feature="serde-1", derive(Serialize,Deserialize))]
 pub struct IsaacRng {
     #[cfg_attr(feature="serde-1",serde(with="super::isaac_serde::rand_size_serde"))]

src/prng/isaac64.rs

@@ -29,16 +29,20 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// series of array based random number generator designed by Robert Jenkins
 /// in 1996[1].
 ///
-/// Although ISAAC is designed to be cryptographically secure, its design is not
-/// founded in cryptographic theory. Therefore it is _not recommended for_
-/// cryptographic purposes. It is however one of the strongest non-cryptograpic
-/// RNGs, and that while still being reasonably fast.
-///
 /// ISAAC-64 is mostly similar to ISAAC. Because it operates on 64-bit integers
 /// instead of 32-bit, it uses twice as much memory to hold its state and
 /// results. Also it uses different constants for shifts and indirect indexing,
 /// optimized to give good results for 64bit arithmetic.
 ///
+/// ISAAC-64 is notably fast and produces excellent quality random numbers for
+/// non-cryptographic applications.
+///
+/// In spite of being designed with cryptographic security in mind, ISAAC hasn't
+/// been stringently cryptanalyzed and thus cryptographers do not not
+/// consensually trust it to be secure. When looking for a secure RNG, prefer
+/// [`Hc128Rng`] instead, which, like ISAAC, is an array-based RNG and one of
+/// the stream-ciphers selected the by eSTREAM contest.
+///
 /// ## Overview of the ISAAC-64 algorithm:
 /// (in pseudo-code)
 ///
@@ -68,7 +72,9 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 ///
 /// [1]: Bob Jenkins, [*ISAAC and RC4*](
 ///      http://burtleburtle.net/bob/rand/isaac.html)
+///
 /// [`IsaacRng`]: prng/isaac/struct.IsaacRng.html
+/// [`Hc128Rng`]: prng/hc128/struct.Hc128Rng.html
 #[cfg_attr(feature="serde-1", derive(Serialize,Deserialize))]
 pub struct Isaac64Rng {
     #[cfg_attr(feature="serde-1",serde(with="super::isaac_serde::rand_size_serde"))]