Release v0.0.1

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 luau-project [https://github.com/luau-project/lua-uuid](https://github.com/luau-project/lua-cryptorandom)
+Copyright (c) 2025 luau-project [https://github.com/luau-project/lua-cryptorandom](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

README.md

@@ -4,24 +4,35 @@
 
 ## 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.
+**lua-cryptorandom** is a lightweight, native library for Lua aimed to generate cryptographically secure pseudo random 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 Unix-like distributions, it uses the ```OpenSSL``` library to generate random 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++.
 
+## Use cases
+
+Many security operations rely on the high-quality of randomization services to avoid reproducibility and remain resistant to reverse engineering:
+
+* randomized password generation;
+* nonces (numbers used once) generation;
+* initialization vectors;
+* salts in passwords before hashing;
+* tokenization (*token generation*) to represent sensitive data;
+* secure random sampling in statistical analysis.
+
 ## Table of Contents
 
 * [Installation](#installation)
 * [Methods](#methods)
     * [bytes](#bytes)
     * [integer](#integer)
     * [number](#number)
-    * [seed](#seed)
+    * [take](#take)
 * [Change log](#change-log)
 * [Future works](#future-works)
 
@@ -58,7 +69,7 @@ luarocks install lua-cryptorandom
 
 > [!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.
+> 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 entropy source temporarily fail to provide sufficient randomness material.
 
 ### bytes
 
@@ -67,8 +78,8 @@ luarocks install lua-cryptorandom
     * *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).
+        * ```table | nil```: a table containing ```n``` bytes on success, or ```nil``` when an error occurred;
+        * ```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*:
 
@@ -97,9 +108,9 @@ luarocks install lua-cryptorandom
 * *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).
+        * ```integer | nil```: the generated integer on success, or ```nil``` when an error occurred;
+        * ```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 [take](#take).
 * *Usage*:
 
     ```lua
@@ -119,8 +130,8 @@ luarocks install lua-cryptorandom
 * *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).
+        * ```number | nil```: the generated float number on success, or ```nil``` when an error occurred;
+        * ```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
@@ -135,25 +146,25 @@ luarocks install lua-cryptorandom
     end
     ```
 
-### seed
+### take
 
-* *Description*: Generates a random seed integer
-* *Signature*: ```seed()```
+* *Description*: Generates a random integer that spans at least 16 bits in size, but usually 32 bits in these-days-computers.
+* *Signature*: ```take()```
     * *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).
+        * ```integer | nil```: the generated integer on success, or ```nil``` when an error occurred;
+        * ```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()
+    local take, err = random.take()
 
-    if (seed == nil) then
+    if (take == nil) then
         print("error code: ", err)
     else
-        print("seed: ", seed)
+        print("take: ", take)
     end
     ```
 

rockspecs/lua-cryptorandom-0.0.1-1.rockspec

@@ -8,9 +8,9 @@ source = {
 
 description = {
    homepage = "https://github.com/luau-project/lua-cryptorandom",
-   summary = [[Generate cryptographically-secure pseudo-random bytes and numbers for Lua]],
+   summary = [[Generate cryptographically secure pseudo random 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.
+lua-cryptorandom is a lightweight, native library for Lua aimed to generate cryptographically secure pseudo random numbers, using trusted sources of randomness provided by the operating system.
 
 Visit the repository for more information.]=],
    license = "MIT"

rockspecs/lua-cryptorandom-dev-1.rockspec

@@ -7,9 +7,9 @@ source = {
 
 description = {
    homepage = "https://github.com/luau-project/lua-cryptorandom",
-   summary = [[Generate cryptographically-secure pseudo-random bytes and numbers for Lua]],
+   summary = [[Generate cryptographically-secure pseudo-random 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.
+lua-cryptorandom is a lightweight, native library for Lua aimed to generate cryptographically-secure pseudo-random numbers, using trusted sources of randomness provided by the operating system.
 
 Visit the repository for more information.]=],
    license = "MIT"

samples/readonly.lua

@@ -1,11 +1,13 @@
 local random = require("lua-cryptorandom")
 
+-- all the fields of this library are read-only
+
 if (not pcall(function() random.bytes = 0 end)) then
     print("Not allowed to change bytes function")
 end
 
-if (not pcall(function() random.seed = 0 end)) then
-    print("Not allowed to change seed function")
+if (not pcall(function() random.take = 0 end)) then
+    print("Not allowed to change take function")
 end
 
 if (not pcall(function() random.integer = 0 end)) then

samples/seed.lua → samples/take.lua

@@ -1,9 +1,9 @@
 local random = require("lua-cryptorandom")
 
-local seed, err = random.seed()
+local take, err = random.take()
 
-if (seed == nil) then
+if (take == nil) then
     print("error code: ", err)
 else
-    print("seed: ", seed)
+    print("take: ", take)
 end

src/lua-cryptorandom.c

@@ -90,7 +90,7 @@ static int lua_cryptorandom_bytes(lua_State *L)
     return 2;
 }
 
-static int lua_cryptorandom_seed(lua_State *L)
+static int lua_cryptorandom_take(lua_State *L)
 {
     unsigned char buffer[sizeof(int)];
 
@@ -102,8 +102,8 @@ static int lua_cryptorandom_seed(lua_State *L)
     }
     else
     {
-        int *seed_ptr = (int *)buffer;
-        lua_pushinteger(L, *seed_ptr);
+        int *take_ptr = (int *)buffer;
+        lua_pushinteger(L, *take_ptr);
         lua_pushnil(L);
     }
 
@@ -122,8 +122,8 @@ static int lua_cryptorandom_integer(lua_State *L)
     }
     else
     {
-        lua_Integer *seed_ptr = (lua_Integer *)buffer;
-        lua_pushinteger(L, *seed_ptr);
+        lua_Integer *take_ptr = (lua_Integer *)buffer;
+        lua_pushinteger(L, *take_ptr);
         lua_pushnil(L);
     }
 
@@ -142,8 +142,8 @@ static int lua_cryptorandom_number(lua_State *L)
     }
     else
     {
-        lua_Number *seed_ptr = (lua_Number *)buffer;
-        lua_pushnumber(L, *seed_ptr);
+        lua_Number *take_ptr = (lua_Number *)buffer;
+        lua_pushnumber(L, *take_ptr);
         lua_pushnil(L);
     }
 
@@ -158,7 +158,7 @@ static int lua_cryptorandom_new_index(lua_State *L)
 
 static const luaL_Reg lua_cryptorandom_public_functions[] = {
     {"bytes", lua_cryptorandom_bytes},
-    {"seed", lua_cryptorandom_seed},
+    {"take", lua_cryptorandom_take},
     {"integer", lua_cryptorandom_integer},
     {"number", lua_cryptorandom_number},
     {NULL, NULL}