From 29222f06f38e321e5a2ac8dae67ced92b6544bde Mon Sep 17 00:00:00 2001 From: Raimo Niskanen 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(-) (limited to 'lib/crypto/doc') 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 @@ random number generation, in order to generate cryptographically strong random numbers (based on OpenSSL's BN_rand_range), - 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 - rand:seed/1. + rand:seed/1 and + rand_seed_s/0. +

+

+ When using the state object from this function the + rand functions using it + may throw exception low_entropy in case the random generator + failed due to lack of secure "randomness".

Example

@@ -763,6 +770,106 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[
See also rand:seed_s/1.

+

+ When using the state object from this function the + rand functions using it + may throw exception low_entropy in case the random generator + failed due to lack of secure "randomness". +

+ +

+ The state returned from this function can not be used + to get a reproducable random sequence as from + the other + rand + functions, + since reproducability does not match cryptographically safe. +

+

+ The only supported usage is to generate one distinct + random sequence from this start state. +

+ + + + + + rand_seed_alg(Alg) -> rand:state() + Strong random number generation plugin state + + Alg = crypto | crypto_cache + + +

+ Creates state object for + random number generation, + in order to generate cryptographically strong random numbers. + See also + rand:seed/1 and + rand_seed_alg_s/1. +

+

+ When using the state object from this function the + rand functions using it + may throw exception low_entropy in case the random generator + failed due to lack of secure "randomness". +

+

Example

+ 
+_ = crypto:rand_seed_alg(crypto_cache),
+_IntegerValue = rand:uniform(42), % [1; 42]
+_FloatValue = rand:uniform().     % [0.0; 1.0[
+ + + + + rand_seed_alg_s(Alg) -> rand:state() + Strong random number generation plugin state + + Alg = crypto | crypto_cache + + +

+ Creates state object for + random number generation, + in order to generate cryptographically strongly random numbers. + See also + rand:seed_s/1. +

+

+ If Alg is crypto this function behaves exactly like + rand_seed_s/0. +

+

+ If Alg is crypto_cache this function + fetches random data with OpenSSL's RAND_bytes + and caches it for speed using an internal word size + of 56 bits that makes calculations fast on 64 bit machines. +

+

+ When using the state object from this function the + rand functions using it + may throw exception low_entropy in case the random generator + failed due to lack of secure "randomness". +

+ +

+ The state returned from this function can not be used + to get a reproducable random sequence as from + the other + rand + functions, + since reproducability does not match cryptographically safe. +

+

+ In fact since random data is cached some numbers may + get reproduced if you try, but this is unpredictable. +

+

+ The only supported usage is to generate one distinct + random sequence from this start state. +

+ -- cgit v1.2.3 From 7710c0d681a4b5f17253945dde0726de0e27cdcf Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Thu, 28 Sep 2017 14:48:44 +0200 Subject: Make cache size configurable --- lib/crypto/doc/src/crypto.xml | 14 ++++++++++++++ lib/crypto/doc/src/crypto_app.xml | 18 ++++++++++++++++++ 2 files changed, 32 insertions(+) (limited to 'lib/crypto/doc') diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 5afab632cd..c32e3430ab 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -800,6 +800,7 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ Alg = crypto | crypto_cache +

Creates state object for random number generation, @@ -814,6 +815,12 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ may throw exception low_entropy in case the random generator failed due to lack of secure "randomness".

+

+ The cache size can be changed from its default value using the + + crypto app's + configuration parameter rand_cache_size. +

Example

 _ = crypto:rand_seed_alg(crypto_cache),
@@ -829,6 +836,7 @@ _FloatValue = rand:uniform().     % [0.0; 1.0[
Alg = crypto | crypto_cache +

Creates state object for random number generation, @@ -852,6 +860,12 @@ _FloatValue = rand:uniform(). % [0.0; 1.0[ may throw exception low_entropy in case the random generator failed due to lack of secure "randomness".

+

+ The cache size can be changed from its default value using the + + crypto app's + configuration parameter rand_cache_size. +

The state returned from this function can not be used 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.

+ rand_cache_size = integer() + +

+ Sets the cache size in bytes to use by + + crypto:rand_seed_alg(crypto_cache) + and + + crypto:rand_seed_alg_s(crypto_cache) + . + 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. +

+ -- cgit v1.2.3