Module uuid.rng

Random number generator utilities with different properties and uses.

Build in rng functions getting random numbers from different sources

luasystem () Returns an rng that implements LuaSystem's system.random() function.
math_random () Returns an rng that implementats the default Lua math.random() function.
urandom () Returns an rng that reads from /dev/urandom, which is a good source of randomness but only available on Posix systems.
win_ffi () Returns an rng that implements Windows' RtlGenRandom function which is a good source of randomness on all modern versions of Windows.

Functions to improve Lua's seeding

generate_seed ([inputdata]) Returns a binary string, sha1-like (40 bytes).
math_randomseed (seed, seed2) Improved math.randomseed function.
seed ([inputdata]) Seeds the Lua random generator, relies on generate_seed.


Build in rng functions getting random numbers from different sources

luasystem ()
Returns an rng that implements LuaSystem's system.random() function. which is a good source of randomness (for both Windows and Posix). Ensure that LuaSystem is installed and available. Since it uses LuaSystem there is no need to seed Lua's random number generator before using this function.

Returns:

    function A function that returns n random bytes, signature: byte_string, err = func(n)

Usage:

    local uuid = require "uuid"
uuid.set_rng(uuid.rng.luasystem())
math_random ()
Returns an rng that implementats the default Lua math.random() function. In Lua 5.1 to 5.3 this relies on the C rand() function, which is low quality and predictable, so essentially a bad source of randomness. In Lua 5.4 this is improved because it includes its own (way better, but not crypto-grade) rng.

Important: ensure to use a good random seed set via rng.math_randomseed, and do this only once, since it is an application responsibility, not a library one. Check out rng.seed and rng.generate_seed for better seeding.

Returns:

    function A function that returns n random bytes, signature: byte_string, err = func(n)

Usage:

    local uuid = require "uuid"
uuid.rng.math_randomseed(some_really_good_seed)
uuid.set_rng(uuid.rng.math_random())
urandom ()
Returns an rng that reads from /dev/urandom, which is a good source of randomness but only available on Posix systems. Since it uses /dev/urandom there is no need to seed Lua's random number generator before using this function.

Returns:

    function A function that returns n random bytes, signature: byte_string, err = func(n)

Usage:

    local uuid = require "uuid"
uuid.set_rng(uuid.rng.urandom())
win_ffi ()
Returns an rng that implements Windows' RtlGenRandom function which is a good source of randomness on all modern versions of Windows. Requires LuaJIT or cffi-lua.

Returns:

    function A function that returns n random bytes, signature: byte_string, err = func(n)

Usage:

    local uuid = require "uuid"
uuid.set_rng(uuid.rng.win_ffi())

Functions to improve Lua's seeding

generate_seed ([inputdata])
Returns a binary string, sha1-like (40 bytes). Generates crypto level randomness if luasystem, /dev/urandom, or win_ffi is available. If neither is available it returns a sha1 hash of a combination of string values:

  • a unique table id (relying on ASLR)

  • the inputdata string if provided

  • 10 bytes generated using math.random for which the quality depends on the Lua version in use

  • the current time in seconds with microsecond precision (using OpenResty or LuaSocket), or otherwise falls back to os.time with second precision

  • the current worker's pid and id (OpenResty only)

Important: ensure you understand what this does. Otherwise just use LuaSystem!!

Parameters:

  • inputdata string additional entropy input to be used in the seed generation in case of a sha1 fallback (optional)

Returns:

    string a 40 bytes long binary string
math_randomseed (seed, seed2)
Improved math.randomseed function. Lua 5.4 takes 2 args 64bit, it uses an internal rng. Both seed values should range from math.mininteger to math.maxinteger (64bit signed integers). If they are not, Lua will throw an error. Hence this function does not modify the seed values in the Lua 5.4 case.

Lua 5.1 to 5.3 use the C function srand which takes an unsigned Int. The range should be from 0 to 2^32. If the seed is outside this range, it will be silently truncated to fit within the range. This can lead to the same sequence of random numbers being generated each time the application is run.

This function ensures that the seed is within the proper range by dropping the most significant bits if it exceeds the integer range. And any negative values are made positive first. It can be used as a drop-in replacement for math.randomseed().

Important: the random seed is a global piece of data. Hence setting it is an application level responsibility, libraries should never set it!

Parameters:

  • seed integer the random seed to set 0 to 2^32-1 for Lua 5.1-5.3, mininteger to maxinteger for Lua 5.4+
  • seed2 integer second part of the seed, only for Lua 5.4+, mininteger to maxinteger

Returns:

    integer the seed(s) used (potentially modified inputs)

Usage:

    -- patch Lua's version
_G.math.randomseed = require("uuid").rng.math_randomseed
seed ([inputdata])
Seeds the Lua random generator, relies on generate_seed.

Important: ensure you understand what generate_seed does!!

A seed will be generated by generate_seed (40 byte string) and after conversion in the proper format, it will be used to seed the Lua random number generator by calling math_randomseed.

For Lua 5.1 to 5.3 it will use the first 4 bytes of the generated seed to create a 32 bit integer seed. For Lua 5.4+ it will unpack the first 16 bytes in 2 64bit integers used as seeds.

Important: the random seed is a global piece of data. Hence setting it is an application level responsibility, libraries should never set it!

Parameters:

Returns:

    the results from rng.math_randomseed
generated by LDoc 1.5.0 Last updated 2024-10-13 00:59:03