From 0f79e3f3d95fd8f04e3893e50c9f27b9e04c2c7e Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 13 Sep 2018 15:26:24 +0200
Subject: Use long period counter for crypto_aes

Conflicts:
	lib/crypto/doc/src/crypto.xml
	lib/crypto/src/crypto.erl
---
 lib/crypto/doc/src/crypto.xml | 110 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 102 insertions(+), 8 deletions(-)

(limited to 'lib/crypto/doc')

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 3fd99be5b6..c21aec50fe 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
@@ -905,7 +904,8 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
 	<p>
           Creates state object for
 	  <seealso marker="stdlib:rand">random number generation</seealso>,
-          in order to generate cryptographically strong random numbers.
+          in order to generate cryptographically strong random numbers,
+          and saves it in the process dictionary before returning it as well.
           See also
 	  <seealso marker="stdlib:rand#seed-1">rand:seed/1</seealso> and
 	  <seealso marker="#rand_seed_alg_s-1">rand_seed_alg_s/1</seealso>.
@@ -916,12 +916,6 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
 	  may raise exception <c>error:low_entropy</c> in case the random generator
 	  failed due to lack of secure "randomness".
 	</p>
-	<p>
-	  The cache size can be changed from its default value using the
-	  <seealso marker="crypto_app">
-	    crypto app's
-	  </seealso> configuration parameter <c>rand_cache_size</c>.
-	</p>
         <p><em>Example</em></p>
         <pre>
 _ = crypto:rand_seed_alg(crypto_cache),
@@ -930,6 +924,34 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
       </desc>
     </func>
 
+    <func>
+      <name>rand_seed_alg(Alg, Seed) -> rand:state()</name>
+      <fsummary>Strong random number generation plugin state</fsummary>
+      <type>
+        <v>Alg = crypto_aes</v>
+      </type>
+      <desc>
+	<marker id="rand_seed_alg-2" />
+	<p>
+          Creates a state object for
+	  <seealso marker="stdlib:rand">random number generation</seealso>,
+          in order to generate cryptographically unpredictable random numbers,
+          and saves it in the process dictionary before returning it as well.
+          See also
+	  <seealso marker="#rand_seed_alg_s-2">rand_seed_alg_s/2</seealso>.
+	</p>
+        <p><em>Example</em></p>
+        <pre>
+_ = crypto:rand_seed_alg(crypto_aes, "my seed"),
+IntegerValue = rand:uniform(42), % [1; 42]
+FloatValue = rand:uniform(),     % [0.0; 1.0[
+_ = crypto:rand_seed_alg(crypto_aes, "my seed"),
+IntegerValue = rand:uniform(42), % Same values
+FloatValue = rand:uniform().     % again
+	</pre>
+      </desc>
+    </func>
+
     <func>
       <name>rand_seed_alg_s(Alg) -> rand:state()</name>
       <fsummary>Strong random number generation plugin state</fsummary>
@@ -967,6 +989,12 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
 	    crypto app's
 	  </seealso> configuration parameter <c>rand_cache_size</c>.
 	</p>
+	<p>
+	  When using the state object from this function the
+	  <seealso marker="stdlib:rand">rand</seealso> functions using it
+	  may throw exception <c>low_entropy</c> in case the random generator
+	  failed due to lack of secure "randomness".
+	</p>
 	<note>
 	  <p>
 	    The state returned from this function cannot be used
@@ -988,6 +1016,72 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
       </desc>
     </func>
 
+    <func>
+      <name>rand_seed_alg_s(Alg, Seed) -> rand:state()</name>
+      <fsummary>Strong random number generation plugin state</fsummary>
+      <type>
+        <v>Alg = crypto_aes</v>
+      </type>
+      <desc>
+	<marker id="rand_seed_alg_s-2" />
+	<p>
+          Creates a state object for
+	  <seealso marker="stdlib:rand">random number generation</seealso>,
+          in order to generate cryptographically unpredictable random numbers.
+          See also
+	  <seealso marker="#rand_seed_alg-1">rand_seed_alg/1</seealso>.
+	</p>
+	<p>
+	  To get a long period the Xoroshiro928 generator from the
+	  <seealso marker="stdlib:rand">rand</seealso>
+	  module is used as a counter (with period 2^928 - 1)
+	  and the generator states are scrambled through AES
+	  to create 58-bit pseudo random values.
+	</p>
+	<p>
+	  The result should be statistically completely unpredictable
+	  random values, since the scrambling is cryptographically strong
+	  and the period is ridiculously long.  But the generated numbers
+	  are not to be regarded as cryptographically strong since
+	  there is no re-keying schedule.
+	</p>
+	<list type="bulleted">
+	  <item>
+	    <p>
+	      If you need cryptographically strong random numbers use
+	      <seealso marker="#rand_seed_alg_s-1">rand_seed_alg_s/1</seealso>
+	      with <c>Alg =:= crypto</c> or <c>Alg =:= crypto_cache</c>.
+	    </p>
+	  </item>
+	  <item>
+	    <p>
+	      If you need to be able to repeat the sequence use this function.
+	    </p>
+	  </item>
+	  <item>
+	    <p>
+	      If you do not need the statistical quality of this function,
+	      there are faster algorithms in the
+	      <seealso marker="stdlib:rand">rand</seealso>
+	      module.
+	    </p>
+	  </item>
+	</list>
+	<p>
+	  Thanks to the used generator the state object supports the
+	  <seealso marker="stdlib:rand#jump-0"><c>rand:jump/0,1</c></seealso>
+	  function with distance 2^512.
+	</p>
+	<p>
+	  Numbers are generated in batches and cached for speed reasons.
+	  The cache size can be changed from its default value using the
+	  <seealso marker="crypto_app">
+	    crypto app's
+	  </seealso> configuration parameter <c>rand_cache_size</c>.
+	</p>
+      </desc>
+    </func>
+
     <func>
       <name name="stream_init" arity="2"/>
       <fsummary></fsummary>
-- 
cgit v1.2.3