Merge pull request #1857 from RaimoNiskanen/raimo/rand-crypto-xoroshiro928

OTP-14461 - New 'rand' algorithm: Xoroshiro928** also for 'crypto'

Implement a new 'rand' algorithm named 'exro928ss' and a new 'crypto' plugin for 'rand' named 'crypto_aes'.

Both are based on Xoroshiro928** which is derived from Xoroshiro1024** modified to use 58-bit words for performance reasons in the Erlang VM.  Xoroshiro1024** has got the Xoroshiro1024 generator and the StarStar scrambler from the 2018 paper "Scrambled Linear Pseudorandom Number Generators" by David Blackman and Sebastiano Vigna.

This generator and scrambler combination shows no systematic weaknesses in standard statistical tests as TestU01(BigCrush) and PractRand, unlike the previously used * and + scramblers in the 'rand' module that exhibit statistical weaknesses for the lowest bits.

The 'crypto' plugin uses AES-256 as scrambler and the Xoroshiro928 as generator, which gives the same very long period and jump functions as for Xoroshiro928**, but a cryptographically secure scrambler gives absolutely no detectable statistical weaknesses regardless of how the generated numbers are used.

The speed of 'exro928ss' is only about 30-50% slower than the default fast 'rand' algorithm, but the state is roughly the double and it produces about 8 times the garbage per iteration.

The speed of 'crypto_aes' is about half (amortized) that of the default fast 'rand' algorithm which is fast and thanks to doing encryption in batches caching the result.  Hence the state is much larger.

1 files changed, 102 insertions, 8 deletions

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 8c4dc1729a..e9ccd89911 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),
@@ -931,6 +925,34 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
     </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>
       <type>
@@ -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
@@ -989,6 +1017,72 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
     </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>
       <desc>