initial commit

.gitignore

@@ -0,0 +1,5 @@
+*.o
+*.so
+*.dll
+*.lib
+.vscode

LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 luau-project [https://github.com/luau-project/lua-uuid](https://github.com/luau-project/lua-cryptorandom)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile.macosx

@@ -0,0 +1,24 @@
+OBJ_EXTENSION = o
+LIB_EXTENSION = so
+CFLAGS_EXTRA = -DLUA_CRYPTORANDOM_BUILD_SHARED -DLUA_CRYPTORANDOM_USE_APPLE
+LIBFLAG_EXTRA = -framework Security
+
+LUA_DIR = /usr/local
+LUA_INCDIR = $(LUA_DIR)/include
+
+LUA_VERSION = 5.1
+INSTALL_PREFIX = /usr/local
+INSTALL_LIBDIR = $(INSTALL_PREFIX)/lib/lua/$(LUA_VERSION)
+
+all: src/lua-cryptorandom.$(LIB_EXTENSION)
+
+src/lua-cryptorandom.$(LIB_EXTENSION): src/lua-cryptorandom.$(OBJ_EXTENSION)
+	$(CC) $(LIBFLAG_EXTRA) $(LIBFLAG) -o $@ $<
+
+src/lua-cryptorandom.$(OBJ_EXTENSION): src/lua-cryptorandom.c
+	$(CC) -c $(CFLAGS_EXTRA) $(CFLAGS) -I$(LUA_INCDIR) $< -o $@
+
+install: src/lua-cryptorandom.$(LIB_EXTENSION)
+	cp $< $(INSTALL_LIBDIR)
+
+.PHONY: all install

README.md

@@ -0,0 +1,166 @@
+# lua-cryptorandom
+
+[![CI](https://github.com/luau-project/lua-cryptorandom/actions/workflows/ci.yml/badge.svg)](./.github/workflows/ci.yml) [![LuaRocks](https://img.shields.io/luarocks/v/luau-project/lua-cryptorandom?label=LuaRocks&color=2c3e67)](https://luarocks.org/modules/luau-project/lua-cryptorandom)
+
+## Overview
+
+**lua-cryptorandom** is a lightweight, native library for Lua aimed to generate cryptographically-secure pseudo-random bytes and numbers, using trusted sources of randomness provided by the operating system.
+
+* On Unix-like distributions, it uses the ```OpenSSL``` library to generate random bytes and numbers;
+* On Windows, it uses the WINAPI ```bcrypt``` library;
+* On macOS / iOS, it uses the ```Security``` framework.
+
+> [!NOTE]
+> 
+> ```lua-cryptorandom``` is implemented in C, and also compiles as C++.
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Methods](#methods)
+    * [bytes](#bytes)
+    * [integer](#integer)
+    * [number](#number)
+    * [seed](#seed)
+* [Change log](#change-log)
+* [Future works](#future-works)
+
+## Installation
+
+> [!IMPORTANT]
+> 
+> On Unix-like operating systems (e.g.: Linux, BSD),  ```lua-cryptorandom``` depends on the ```OpenSSL``` library:
+>  * On Debian-based (e.g.: Ubuntu) distributions:
+> 
+>      ```bash
+>      sudo apt install -y libssl-dev
+>      ```
+> 
+>  * On RedHat-based (e.g.: Fedora) distributions:
+> 
+>      ```bash
+>      sudo dnf install openssl-devel
+>      ```
+> 
+>  * On BSD-based (e.g.: FreeBSD) distributions:
+> 
+>      ```bash
+>      pkg install openssl-devel
+>      ```
+
+Assuming that [LuaRocks](https://luarocks.org) is properly installed and configured on your system, execute the following command:
+
+```bash
+luarocks install lua-cryptorandom
+```
+
+## Methods
+
+> [!IMPORTANT]
+> 
+> For each method below, always check whether the first returned value is ```nil``` or not. When the first value is ```nil```, there was an underlying error generating random values. It can fail because no trusted random source is available or the trusted source temporarily fail to provide sufficient randomness material.
+
+### bytes
+
+* *Description*: Generates a sequence of random bytes
+* *Signature*: ```bytes(n)```
+    * *Parameters*:
+        * *n*: the number of bytes to generate
+    * *Return*: ```table | nil``` as first value, and ```nil | number``` as the second.
+        1. ```table | nil```: a table containing ```n``` bytes on success, or ```nil``` when an error occurred;
+        2. ```nil | integer```: an error code that is set to ```nil``` on success, or an ```integer``` representing the code used by the underlying library (```OpenSSL``` on Unix, ```bcrypt``` on Windows and ```Security``` framework on macOS / iOS).
+* *Remark*: Here, a byte is meant as an integer in the range 0 - 255.
+* *Usage*:
+
+    ```lua
+    local random = require("lua-cryptorandom")
+
+    -- number of bytes to generate
+    local n = 10
+
+    local bytes, err = random.bytes(n)
+
+    if (bytes == nil) then
+        print(("error code: %d"):format(err))
+    else
+        assert(n == #bytes, "Unexpected number of bytes")
+
+        -- print each byte
+        for i, b in ipairs(bytes) do
+            print(i, b)
+        end
+    end
+    ```
+
+### integer
+
+* *Description*: Generates a random integer
+* *Signature*: ```integer()```
+    * *Return*: ```integer | nil``` as first value, and ```nil | integer``` as the second.
+        1. ```integer | nil```: the generated integer on success, or ```nil``` when an error occurred;
+        2. ```nil | integer```: an error code that is set to ```nil``` on success, or an ```integer``` representing the code used by the underlying library (```OpenSSL``` on Unix, ```bcrypt``` on Windows and ```Security``` framework on macOS / iOS).
+* *Remark*: The generated integer can be any valid Lua integer, and such integer can span up to 64 bits. Use this function when you need a potentially large integer. For smaller integers, see [seed](#seed).
+* *Usage*:
+
+    ```lua
+    local random = require("lua-cryptorandom")
+
+    local integer, err = random.integer()
+
+    if (integer == nil) then
+        print(("error code: %d"):format(err))
+    else
+        print(("integer: %d"):format(integer))
+    end
+    ```
+
+### number
+
+* *Description*: Generates a random float number
+* *Signature*: ```number()```
+    * *Return*: ```number | nil``` as first value, and ```nil | integer``` as the second.
+        1. ```number | nil```: the generated float number on success, or ```nil``` when an error occurred;
+        2. ```nil | integer```: an error code that is set to ```nil``` on success, or an ```integer``` representing the code used by the underlying library (```OpenSSL``` on Unix, ```bcrypt``` on Windows and ```Security``` framework on macOS / iOS).
+* *Usage*:
+
+    ```lua
+    local random = require("lua-cryptorandom")
+
+    local number, err = random.number()
+
+    if (number == nil) then
+        print(("error code: %d"):format(err))
+    else
+        print(("number: %.14g"):format(number))
+    end
+    ```
+
+### seed
+
+* *Description*: Generates a random seed integer
+* *Signature*: ```seed()```
+    * *Return*: ```integer | nil``` as first value, and ```nil | integer``` as the second.
+        1. ```integer | nil```: the generated integer on success, or ```nil``` when an error occurred;
+        2. ```nil | integer```: an error code that is set to ```nil``` on success, or an ```integer``` representing the code used by the underlying library (```OpenSSL``` on Unix, ```bcrypt``` on Windows and ```Security``` framework on macOS / iOS).
+* *Remark*: The generated integer has, at least, 16 bits in size, but it is usually a 32 bits integer in these-day-computers. The returned integer has the ```int``` data type in C. To generate potentially large integers, see [integer](#integer).
+* *Usage*:
+
+    ```lua
+    local random = require("lua-cryptorandom")
+
+    local seed, err = random.seed()
+
+    if (seed == nil) then
+        print(("error code: %d"):format(err))
+    else
+        print(("seed: %d"):format(seed))
+    end
+    ```
+
+## Change log
+
+v0.0.1: Initial release.
+
+## Future works
+
+* Add CMake as a build system.

lua-cryptorandom.def

@@ -0,0 +1,2 @@
+EXPORTS
+    luaopen_cryptorandom

rockspecs/lua-cryptorandom-0.0.1-1.rockspec

@@ -0,0 +1,97 @@
+package = "lua-cryptorandom"
+version = "0.0.1-1"
+
+source = {
+   url = "git+https://github.com/luau-project/lua-cryptorandom",
+   tag = "v0.0.1"
+}
+
+description = {
+   homepage = "https://github.com/luau-project/lua-cryptorandom",
+   summary = [[Generate cryptographically-secure pseudo-random bytes and numbers for Lua]],
+   detailed = [=[
+lua-cryptorandom is a lightweight, native library for Lua aimed to generate cryptographically-secure pseudo-random bytes and numbers, using trusted sources of randomness provided by the operating system.
+
+Visit the repository for more information.]=],
+   license = "MIT"
+}
+
+dependencies = {
+    "lua >= 5.1"
+}
+
+external_dependencies = {
+    platforms = {
+        unix = {
+            ["CRYPTO"] = {
+                header = "openssl/rand.h"
+            }
+        },
+        macos = {
+            ["SECURITY"] = {
+                header = "Security/Security.h"
+            }
+        }
+    }
+}
+
+local function build_plat(plat)
+    if (plat == "macosx") then
+        return {
+            type = "make",
+            makefile = "Makefile.macosx",
+            build_variables = {                                                                               
+                CFLAGS = "$(CFLAGS)",                                                                         
+                LIBFLAG = "$(LIBFLAG)",
+                CFLAGS_EXTRA = "-DLUA_CRYPTORANDOM_BUILD_SHARED -DLUA_CRYPTORANDOM_USE_APPLE",
+                LIBFLAG_EXTRA = "-framework Security",
+                LUA_INCDIR = "$(LUA_INCDIR)",
+                OBJ_EXTENSION = "$(OBJ_EXTENSION)",
+                LIB_EXTENSION = "$(LIB_EXTENSION)"
+            },
+            install_variables = {
+                INSTALL_PREFIX = "$(PREFIX)",
+                INSTALL_LIBDIR = "$(LIBDIR)",
+                LUA_VERSION = "$(LUA_VERSION)",
+                LIB_EXTENSION = "$(LIB_EXTENSION)"
+            }
+        }
+    elseif (plat == "windows" or plat == "cygwin") then
+        return {
+            type = "builtin",
+            modules = {
+                ["lua-cryptorandom"] = {
+                    sources = { "src/lua-cryptorandom.c" },
+                    libraries = { "bcrypt" },
+                    defines = { "LUA_CRYPTORANDOM_BUILD_SHARED", "LUA_CRYPTORANDOM_USE_WIN32" },
+                    incdirs = { "src" },
+                    libdirs = { }
+                }
+            }
+        }
+    elseif (plat == "unix") then
+        return {
+            type = "builtin",
+            modules = {
+                ["lua-cryptorandom"] = {
+                    sources = { "src/lua-cryptorandom.c" },
+                    libraries = { "crypto" },
+                    defines = { "LUA_CRYPTORANDOM_BUILD_SHARED", "LUA_CRYPTORANDOM_USE_OPENSSL" },
+                    incdirs = { "src", "$(CRYPTO_INCDIR)" },
+                    libdirs = { "$(CRYPTO_LIBDIR)" }
+                }
+            }
+        }
+    else
+        error("Unknown platform", 2)
+    end
+end
+
+build = {
+    platforms = {
+        macosx = build_plat("macosx"),
+        windows = build_plat("windows"),
+        cygwin = build_plat("cygwin"),
+        unix = build_plat("unix")
+    }
+}