From 29222f06f38e321e5a2ac8dae67ced92b6544bde Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 19 Sep 2017 15:33:53 +0200
Subject: Document crypto rand cache

---
 lib/crypto/doc/src/crypto.xml | 111 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 109 insertions(+), 2 deletions(-)

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index 89ef529c5d..5afab632cd 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -739,9 +739,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>
@@ -763,6 +770,106 @@ _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>
+	<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><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>
+	<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>
+	<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>
 
-- 
cgit v1.2.3