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

Rand plugin for cached strong crypto bytes
OTP-13370

4 files changed, 185 insertions, 7 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>
 
diff --git a/lib/crypto/src/crypto.app.src b/lib/crypto/src/crypto.app.src
index 1d3f35e465..492aa10e51 100644
--- a/lib/crypto/src/crypto.app.src
+++ b/lib/crypto/src/crypto.app.src
@@ -24,7 +24,7 @@
 	       crypto_ec_curves]},
     {registered, []},
     {applications, [kernel, stdlib]},
-    {env, [{fips_mode, false}]},
+    {env, [{fips_mode, false}, {rand_cache_size, 896}]},
     {runtime_dependencies, ["erts-9.0","stdlib-3.4","kernel-5.3"]}]}.
 
 
diff --git a/lib/crypto/src/crypto.erl b/lib/crypto/src/crypto.erl
index f9c4f7b71d..6b4f3a256d 100644
--- a/lib/crypto/src/crypto.erl
+++ b/lib/crypto/src/crypto.erl
@@ -30,11 +30,12 @@
 -export([hmac/3, hmac/4, hmac_init/2, hmac_update/2, hmac_final/1, hmac_final_n/2]).
 -export([cmac/3, cmac/4]).
 -export([exor/2, strong_rand_bytes/1, mod_pow/3]).
--export([rand_seed/0]).
--export([rand_seed_s/0]).
+-export([rand_seed/0, rand_seed_alg/1]).
+-export([rand_seed_s/0, rand_seed_alg_s/1]).
 -export([rand_plugin_next/1]).
 -export([rand_plugin_uniform/1]).
 -export([rand_plugin_uniform/2]).
+-export([rand_cache_plugin_next/1]).
 -export([rand_uniform/2]).
 -export([block_encrypt/3, block_decrypt/3, block_encrypt/4, block_decrypt/4]).
 -export([next_iv/2, next_iv/3]).
@@ -301,9 +302,17 @@ stream_decrypt(State, Data0) ->
 %%
 %% RAND - pseudo random numbers using RN_ and BN_ functions in crypto lib
 %%
+-type rand_cache_seed() ::
+        nonempty_improper_list(non_neg_integer(), binary()).
 -spec strong_rand_bytes(non_neg_integer()) -> binary().
 -spec rand_seed() -> rand:state().
 -spec rand_seed_s() -> rand:state().
+-spec rand_seed_alg(Alg :: atom()) ->
+                           {rand:alg_handler(),
+                            atom() | rand_cache_seed()}.
+-spec rand_seed_alg_s(Alg :: atom()) ->
+                             {rand:alg_handler(),
+                              atom() | rand_cache_seed()}.
 -spec rand_uniform(crypto_integer(), crypto_integer()) ->
 			  crypto_integer().
 
@@ -319,12 +328,36 @@ rand_seed() ->
     rand:seed(rand_seed_s()).
 
 rand_seed_s() ->
+    rand_seed_alg_s(?MODULE).
+
+rand_seed_alg(Alg) ->
+    rand:seed(rand_seed_alg_s(Alg)).
+
+-define(CRYPTO_CACHE_BITS, 56).
+rand_seed_alg_s(?MODULE) ->
     {#{ type => ?MODULE,
         bits => 64,
         next => fun ?MODULE:rand_plugin_next/1,
         uniform => fun ?MODULE:rand_plugin_uniform/1,
         uniform_n => fun ?MODULE:rand_plugin_uniform/2},
-     no_seed}.
+     no_seed};
+rand_seed_alg_s(crypto_cache) ->
+    CacheBits = ?CRYPTO_CACHE_BITS,
+    EnvCacheSize =
+        application:get_env(
+          crypto, rand_cache_size, CacheBits * 16), % Cache 16 * 8 words
+    Bytes = (CacheBits + 7) div 8,
+    CacheSize =
+        case ((EnvCacheSize + (Bytes - 1)) div Bytes) * Bytes of
+            Sz when is_integer(Sz), Bytes =< Sz ->
+                Sz;
+            _ ->
+                Bytes
+        end,
+    {#{ type => crypto_cache,
+        bits => CacheBits,
+        next => fun ?MODULE:rand_cache_plugin_next/1},
+     {CacheBits, CacheSize, <<>>}}.
 
 rand_plugin_next(Seed) ->
     {bytes_to_integer(strong_rand_range(1 bsl 64)), Seed}.
@@ -335,6 +368,12 @@ rand_plugin_uniform(State) ->
 rand_plugin_uniform(Max, State) ->
     {bytes_to_integer(strong_rand_range(Max)) + 1, State}.
 
+rand_cache_plugin_next({CacheBits, CacheSize, <<>>}) ->
+    rand_cache_plugin_next(
+      {CacheBits, CacheSize, strong_rand_bytes(CacheSize)});
+rand_cache_plugin_next({CacheBits, CacheSize, Cache}) ->
+    <<I:CacheBits, NewCache/binary>> = Cache,
+    {I, {CacheBits, CacheSize, NewCache}}.
 
 strong_rand_range(Range) when is_integer(Range), Range > 0 ->
     BinRange = int_to_bin(Range),
@@ -382,7 +421,7 @@ rand_uniform_nif(_From,_To) -> ?nif_stub.
 
 
 -spec rand_seed(binary()) -> ok.
-rand_seed(Seed) ->
+rand_seed(Seed) when is_binary(Seed) ->
     rand_seed_nif(Seed).
 
 rand_seed_nif(_Seed) -> ?nif_stub.