"docs/flash.md" did not exist on "0bbce6f845bcc89c66017bfe53c332f51e2eddc2"
Commit a40d69db authored by Tom Sutcliffe's avatar Tom Sutcliffe Committed by Johny Mattsson
Browse files

Make sodium.random API behave consistently on all build types

By returning result as a signed 32-bit int between INT32_MIN to IN32_MAX
which is represented the same regardless of 64-bit support or
integral-only builds.

Also updated docs, fixed links and clarified behavior of random APIs
when WiFi isn't started.
parent ed85e21a
...@@ -17,7 +17,7 @@ static int l_randombytes_random(lua_State *L) ...@@ -17,7 +17,7 @@ static int l_randombytes_random(lua_State *L)
{ {
check_init(L); check_init(L);
uint32_t ret = randombytes_random(); uint32_t ret = randombytes_random();
lua_pushnumber(L, (lua_Number)ret); lua_pushinteger(L, (int32_t)ret);
return 1; return 1;
} }
...@@ -26,7 +26,7 @@ static int l_randombytes_uniform(lua_State *L) ...@@ -26,7 +26,7 @@ static int l_randombytes_uniform(lua_State *L)
check_init(L); check_init(L);
uint32_t upper_bound = (uint32_t)luaL_checkinteger(L, 1); uint32_t upper_bound = (uint32_t)luaL_checkinteger(L, 1);
uint32_t ret = randombytes_uniform(upper_bound); uint32_t ret = randombytes_uniform(upper_bound);
lua_pushnumber(L, (lua_Number)ret); lua_pushinteger(L, (int32_t)ret);
return 1; return 1;
} }
......
...@@ -9,13 +9,15 @@ In addition to the flag for enabling this module during ROM build, `Component co ...@@ -9,13 +9,15 @@ In addition to the flag for enabling this module during ROM build, `Component co
!!! note !!! note
Almost all functions in this module require a working random number generator. On the ESP32 this means that *WiFi must be started* otherwise ALL OF THE CRYPTOGRAPHY WILL SILENTLY BE COMPROMISED. Make sure to call `wifi.start()` before any of the functions in this module. See the [Espressif documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/system.html#random-number-generation) for more information. The only exception is `sodium.crypto_box.seal_open()` which does not require a random number source to operate. Almost all functions in this module require a working random number generator. On the ESP32 this normally means that *WiFi must be started* otherwise ALL OF THE CRYPTOGRAPHY WILL SILENTLY BE COMPROMISED. Make sure to call `wifi.start()` before any of the functions in this module. See the [Espressif documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html) for more information. The only exception is `sodium.crypto_box.seal_open()` which does not require a random number source to operate. The non-crypto functions in `sodium.random` can be used with WiFi off, providing that pseudo-randomness is acceptable for the purposes they are being used for.
# Random number generation # Random number generation
See also [https://download.libsodium.org/doc/generating_random_data](https://download.libsodium.org/doc/generating_random_data) See also [https://download.libsodium.org/doc/generating_random_data](https://download.libsodium.org/doc/generating_random_data). On the esp32, a custom implementation `esp_random()` is used which (usually) requires WiFi being enabled to be truly random.
## sodium.random.random() ## sodium.random.random()
Returns a random integer between `0` and `0xFFFFFFFF` inclusive. Note that on a build using `LUA_NUMBER_INTEGRAL`, results may appear negative due to integer overflow. Wifi must be started, by calling `wifi.start()`, before calling this function. Returns a random signed 32-bit integer between `INT32_MIN` and `INT32_MAX`. On builds with 64-bit integer support (`5.3-int64-xxx`), you can convert this to an unsigned 32-bit integer with `result % (1 << 32)`, or on builds with only 64-bit double support (`5.1-doublefp`, `5.3-int32-doublefp`), with `result % (2 ^ 32)`.
If WiFi is not started by calling `wifi.start()` before calling this function, then the result will only be pseudo-random, not truly random.
#### Syntax #### Syntax
`sodium.random.random()` `sodium.random.random()`
...@@ -24,22 +26,24 @@ Returns a random integer between `0` and `0xFFFFFFFF` inclusive. Note that on a ...@@ -24,22 +26,24 @@ Returns a random integer between `0` and `0xFFFFFFFF` inclusive. Note that on a
None None
#### Returns #### Returns
A uniformly-distributed random integer between `0` and `0xFFFFFFFF` inclusive. A uniformly-distributed random 32-bit integer.
## sodium.random.uniform() ## sodium.random.uniform()
Returns a random integer `0 <= result < upper_bound`. Unlike `sodium.random.random() % upper_bound`, it guarantees a uniform distribution of the possible output values even when `upper_bound` is not a power of 2. Note that on a build using `LUA_NUMBER_INTEGRAL`, if `upper_bound >= 0x80000000` the result may appear negative due to integer overflow. Wifi must be started, by calling `wifi.start()`, before calling this function. Returns a random integer `0 <= result < upper_bound`. Unlike `sodium.random.random() % upper_bound`, it guarantees a uniform distribution of the possible output values even when `upper_bound` is not a power of 2. Specifying an `upper_bound > 0x7FFFFFFF` is not recommended because the behavior will vary depending on the Lua build configuration.
If WiFi is not started by calling `wifi.start()` before calling this function, then the result will only be pseudo-random, not truly random.
#### Syntax #### Syntax
`sodium.random.uniform(upper_bound)` `sodium.random.uniform(upper_bound)`
#### Parameters #### Parameters
- `upper_bound` must be an integer `<= 0xFFFFFFFF`. - `upper_bound` an integer.
#### Returns #### Returns
An integer `>= 0` and `< upper_bound` An integer `>= 0` and `< upper_bound`
## sodium.random.buf() ## sodium.random.buf()
Generates `n` bytes of random data. Wifi must be started, by calling `wifi.start()`, before calling this function. Generates `n` bytes of random data. If WiFi is not started by calling `wifi.start()` before calling this function, then the result will only be pseudo-random, not truly random.
#### Syntax #### Syntax
`sodium.random.buf(n)` `sodium.random.buf(n)`
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment