crypto.random
Cryptographically secure random generator, use it for secrets: session tokens, keys, nonces, salts.
Output comes from ChaCha20 with fast key erasure (the key is replaced after every refill), so a leaked state does not reveal earlier output.
The key is seeded from the best available source, see crypto.random.source:
"os"- the operating system generator (RtlGenRandomon Windows,/dev/urandomelsewhere), needsffi, the generator is reseeded from it on every refill."jitter"- withoutffithe seed is SHA-256 of high-resolution timer jitter, memory addresses and clocks, and timer samples from every tick keep being mixed in. Strong in practice, but not provable, feed extra entropy withcrypto.random.mixwhen you have some.
Roughly 10 (FFI) to 30 (pure Lua) times slower than math.random per integer, keep math.random for gameplay and identifiers.
Fields
| Name | Type | Description |
|---|---|---|
source | "os" | "jitter" | The source the generator is seeded from. |
Functions
crypto.random.bytes | Returns the given number of cryptographically secure random bytes. |
crypto.random.float | Returns a cryptographically secure random float in the range [0, 1) with full 53-bit precision. |
crypto.random.integer | Returns a cryptographically secure random integer in the range [min, max], without modulo bias. |
crypto.random.mix | Mixes extra entropy into the generator, it can only make the output stronger. |
#crypto.random.bytes
function crypto.random.bytes(length: integer): stringReturns the given number of cryptographically secure random bytes.
local session_key = crypto.random.bytes( 32 )
local token = base16.encode( crypto.random.bytes( 16 ) ) -- 32 hex digits, 128 bits| Name | Type | Description |
|---|---|---|
length | integer | The number of bytes, a non-negative integer. |
| Type | Name | Description |
|---|---|---|
string | bytes | The random bytes. |
#crypto.random.float
function crypto.random.float(): numberReturns a cryptographically secure random float in the range [0, 1) with full 53-bit precision.
| Type | Name | Description |
|---|---|---|
number | value | The random float. |
#crypto.random.integer
function crypto.random.integer(min: integer, max: integer): integerReturns a cryptographically secure random integer in the range [min, max], without modulo bias.
crypto.random.integer( 0, 9 ) -- one digit of a PIN
crypto.random.integer( 1, 2 ^ 48 ) -- largest supported range| Name | Type | Description |
|---|---|---|
min | integer | The smallest value. |
max | integer | The largest value, at most 2^48 above min. |
| Type | Name | Description |
|---|---|---|
integer | value | The random integer. |
#crypto.random.mix
function crypto.random.mix(data: string | number)Mixes extra entropy into the generator, it can only make the output stronger.
Good inputs are things an attacker cannot see: timings of player input, arrival times of net messages, secrets from a config file.
| Name | Type | Description |
|---|---|---|
data | string | number | The entropy to mix in. |