Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/p0pr0ck5/lua-resty-urandom
Buffered wrapper for Linux/BSD kernel space CSPRNG
https://github.com/p0pr0ck5/lua-resty-urandom
Last synced: 10 days ago
JSON representation
Buffered wrapper for Linux/BSD kernel space CSPRNG
- Host: GitHub
- URL: https://github.com/p0pr0ck5/lua-resty-urandom
- Owner: p0pr0ck5
- License: gpl-3.0
- Created: 2016-04-04T21:53:38.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2017-05-21T22:06:51.000Z (over 7 years ago)
- Last Synced: 2024-02-14T13:33:00.707Z (9 months ago)
- Language: Perl
- Homepage:
- Size: 25.4 KB
- Stars: 9
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-resty - lua-resty-urandom
README
## Name
lua-resty-urandom - Buffered wrapper for Linux/BSD kernel space CSPRNG
## Status
This library is in active development and is production ready.
## Description
lua-resty-urandom seeks to provide efficient access to the `/dev/urandom` device. Background reads fill a per-worker buffer with psuedorandom data, retrievable as a string or table of strings.
## Installation
Install via Luarocks or OPM:
```bash
$ luarocks install lua-resty-urandom
$ opm install p0pr0ck5/lua-resty-urandom # assume lua_system_constants >= 0.1.2 is installed
```
## Synopsis
```lua
init_worker_by_lua_block {
local urandom = require "resty.urandom"
urandom.init({
max_size = 1024 * 1024,
chunk_size = 128,
rate = .1
})
}
[...snip...]
server {
location /random {
content_by_lua_block {
local urandom = require "resty.urandom"
local gargs = ngx.req.get_uri_args()
local length = gargs.length or 128
local data, len, err = urandom.get_string(tonumber(length))
if (err) then
ngx.log(ngx.WARN, err)
else
ngx.say(data)
end
}
}
location /random-t {
content_by_lua_block {
local urandom = require "resty.urandom"
local gargs = ngx.req.get_uri_args()
local num = gargs.num or 1
local data, len, err = urandom.get_chunks(tonumber(num))
if (err) then
ngx.log(ngx.WARN, err)
else
for i in ipairs(data) do
ngx.say(data[i])
end
end
}
}
}
```
## Usage
### urandom.init(opts)
Initialize the buffer geometry and fill rate with a table of options.
* **max_size**: The total amount of psuedorandom data to store, given in bytes.
* **chunk_size**: The amount of data to store in a given "chunk", given in bytes.
* **rate**: The rate at which to fill a portion of the buffer with data from `/dev/urandom`, given in seconds. This call is passed directly to `ngx.timer.at` (so fractions of seconds are available as well).
* **read_size**: The number of bytes to read from urandom at one time.
* **max_fill**: The total number of bytes to read per invocation of the background buffer fill function. If this value is less than `read_size`, the thread will yeild before attempting to read again to meet this value.
* **lock_timeout**: Amount of time, in seconds, to wait on the worker semaphore.
The total number of chunks is calculated as floor(max_size / chunk_size), so if chunk_size is not an even divisor, the total size of the buffer will be less than the given max_size. so do your math right :p
### urandom.get_string(length)
Get a string of psuedorandom data. If `length` is greater than `chunk_size`, more than one chunk will be used to satisfy the request. If `length` is not an even divisor of `chunk_size`, a portion of an additional chunk will be used to satisfy the request, with the leftover data in the chunk discarded.
If more data is requested than is currently available in the buffer, the response will be truncated to the length of available data in the buffer.
### urandom.get_chunks(n)
Get a table of `n` number of values, each of `chunk_length` size. If more chunks are requested than are currently available in the buffer, the response will be truncated to the number of chunks available in the buffer.
## License
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/
## Bugs
Please report bugs by creating a ticket with the GitHub issue tracker.