Merge pull request #1573 from RaimoNiskanen/raimo/crypto/rand-cached

Rand plugin for cached strong crypto bytes
OTP-13370

2 files changed, 141 insertions, 2 deletions

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 5b2c46a004..8c30d3d50c 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -753,9 +753,16 @@
 	  <seealso marker="stdlib:rand">random number generation</seealso>,
           in order to generate cryptographically strong random numbers
           (based on OpenSSL's <c>BN_rand_range</c>),
-          and saves it on process dictionary before returning it as well.
+          and saves it in the process dictionary before returning it as well.
           See also
-	  <seealso marker="stdlib:rand#seed-1">rand:seed/1</seealso>.
+	  <seealso marker="stdlib:rand#seed-1">rand:seed/1</seealso> and
+	  <seealso marker="#rand_seed_s-0">rand_seed_s/0</seealso>.
+	</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>
         <p><em>Example</em></p>
         <pre>
@@ -777,6 +784,120 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
           See also
 	  <seealso marker="stdlib:rand#seed_s-1">rand:seed_s/1</seealso>.
 	</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 can not be used
+	    to get a reproducable random sequence as from
+	    the other 
+	    <seealso marker="stdlib:rand">rand</seealso>
+	    functions,
+	    since reproducability does not match cryptographically safe.
+	  </p>
+	  <p>
+	    The only supported usage is to generate one distinct
+	    random sequence from this start state.
+	  </p>
+	</note>
+      </desc>
+    </func>
+
+    <func>
+      <name>rand_seed_alg(Alg) -> rand:state()</name>
+      <fsummary>Strong random number generation plugin state</fsummary>
+      <type>
+        <v>Alg = crypto | crypto_cache</v>
+      </type>
+      <desc>
+	<marker id="rand_seed_alg-1" />
+	<p>
+          Creates state object for
+	  <seealso marker="stdlib:rand">random number generation</seealso>,
+          in order to generate cryptographically strong random numbers.
+          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>.
+	</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>
+	<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),
+_IntegerValue = rand:uniform(42), % [1; 42]
+_FloatValue = rand:uniform().     % [0.0; 1.0[</pre>
+      </desc>
+    </func>
+
+    <func>
+      <name>rand_seed_alg_s(Alg) -> rand:state()</name>
+      <fsummary>Strong random number generation plugin state</fsummary>
+      <type>
+        <v>Alg = crypto | crypto_cache</v>
+      </type>
+      <desc>
+	<marker id="rand_seed_alg_s-1" />
+	<p>
+          Creates state object for
+	  <seealso marker="stdlib:rand">random number generation</seealso>,
+          in order to generate cryptographically strongly random numbers.
+          See also
+	  <seealso marker="stdlib:rand#seed_s-1">rand:seed_s/1</seealso>.
+	</p>
+	<p>
+	  If <c>Alg</c> is <c>crypto</c> this function behaves exactly like
+	  <seealso marker="#rand_seed_s-0">rand_seed_s/0</seealso>.
+	</p>
+	<p>
+	  If <c>Alg</c> is <c>crypto_cache</c> this function
+	  fetches random data with OpenSSL's <c>RAND_bytes</c>
+	  and caches it for speed using an internal word size
+	  of 56 bits that makes calculations fast on 64 bit machines.
+	</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>
+	<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>
+	<note>
+	  <p>
+	    The state returned from this function can not be used
+	    to get a reproducable random sequence as from
+	    the other 
+	    <seealso marker="stdlib:rand">rand</seealso>
+	    functions,
+	    since reproducability does not match cryptographically safe.
+	  </p>
+	  <p>
+	    In fact since random data is cached some numbers may
+	    get reproduced if you try, but this is unpredictable.
+	  </p>
+	  <p>
+	    The only supported usage is to generate one distinct
+	    random sequence from this start state.
+	  </p>
+	</note>
       </desc>
     </func>
 
diff --git a/lib/crypto/doc/src/crypto_app.xml b/lib/crypto/doc/src/crypto_app.xml
index ba22557480..8296b1bc77 100644
--- a/lib/crypto/doc/src/crypto_app.xml
+++ b/lib/crypto/doc/src/crypto_app.xml
@@ -68,6 +68,24 @@
         thus the crypto module will fail to load. This mechanism
         prevents the accidental use of non-validated algorithms.</p>
       </item>
+      <tag><c>rand_cache_size = integer()</c></tag>
+      <item>
+        <p>
+	  Sets the cache size in bytes to use by
+	  <seealso marker="crypto#rand_seed_alg-1">
+	    <c>crypto:rand_seed_alg(crypto_cache)</c>
+	  </seealso> and
+	  <seealso marker="crypto#rand_seed_alg_s-1">
+	    <c>crypto:rand_seed_alg_s(crypto_cache)</c>
+	  </seealso>.
+	  This parameter is read when a seed function is called,
+	  and then kept in generators state object.  It has a rather
+	  small default value that causes reads of strong random bytes
+	  about once per hundred calls for a random value.
+	  The set value is rounded up to an integral number of words
+	  of the size these seed functions use.
+	</p>
+      </item>
     </taglist>
   </section>