okabsd / randbytes

Tiny module for accessing random bytes

randbytes

Tiny module for reading random bytes, and simple number generation, on Unix-like platforms.

Dependencies

• Unix-like platform (BSD, Linux, macOS)

• Lua >= 5.1

Install

With luarocks.

$ luarocks install randbytes

Or grab the source.

Documentation

Usage

Requiring the module will return the interface, so assign it to a variable.

local randbytes = require 'randbytes'

Defaults

All methods can be called without arguments, in which case they use the defaults:

• bytes defaults to 4

• mask defaults to 256

• file defaults 'urandom'

• filetable defaults to { 'random', 'urandom' }

Defaults can be modified with :setdefault.

Metacall

The interface can be invoked directly.

randbytes (n) → string|nil

Reads n bytes from the default: file

Methods

:read (bytes) → string|nil

Reads N bytes from /dev/random

:uread (bytes) → string|nil

Reads N bytes from /dev/urandom

:random (bytes, mask) → number|nil

Reads N bytes from /dev/random, and returns a number augmented by mask, using simple number generation

:urandom (bytes, mask) → number|nil

Same as :random, reading from /dev/urandom instead

:open (…​files) → self

Opens files (this is called internally when the module initializes)

:close (…​files) → self

Closes files

Both :open & :close take a variable number of string parameters, indicating which files to use. Passing no arguments will populate these strings from the default: filetable.

:setdefault (key, value) → defaults[key]

Sets default values, (key, value) pairs are as follows:

• 'bytes', number

• 'mask', number

• 'file', 'random' or 'urandom'

• 'filetable', table<string> containing any of: 'random', 'urandom'

Notes

When files are closed, calls to :read and :random style methods will return nil.

License

MIT, just like Lua.