From 4e0ed16d7cce90d61118db52c06c507772177714 Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Wed, 8 Jul 2015 20:59:06 +0100 Subject: Add ldoc based documentation --- .gitignore | 2 ++ Makefile | 3 +++ README | 22 ++++++++++++++++++++++ config.ld | 6 ++++++ luascrypt.c.ldoc | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 87 insertions(+) create mode 100644 README create mode 100644 config.ld create mode 100644 luascrypt.c.ldoc diff --git a/.gitignore b/.gitignore index 005ec35..d1437fe 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ *.so *.a *.o +html/ +*~ diff --git a/Makefile b/Makefile index 070b1b2..7ac8504 100644 --- a/Makefile +++ b/Makefile @@ -109,6 +109,7 @@ all: lua-5.1-try lua-5.2-try clean: $(RM) scrypt-5.1.so scrypt-5.2.so scrypt.so $(RM) luascrypt.o + $(RM) -r html %.o: %.c $(CC) $(CFLAGS) -fPIC $(LUA51_INC) -c $< -o $@ @@ -134,3 +135,5 @@ scrypt-5.2.so: luascrypt.o $(CC) $(CFLAGS) -shared -o $@ $^ $(LUA51_LIB) $(SCRYPT_LIBS) +doc: + @ldoc . diff --git a/README b/README new file mode 100644 index 0000000..9bed714 --- /dev/null +++ b/README @@ -0,0 +1,22 @@ +lua-scrypt +========== + +lua-scrypt is a binding to libscrypt which is a password crypting and +verification library. lua-scrypt uses the [libscrypt][] library and +provides a simple interface for hashing and verifying passwords. + + local scrypt = require "scrypt" + + local hash = scrypt.hash_password("Hello world") + + assert(scrypt.verify_password(hash, "Hello world")) + +Thanks +====== + +Originally, [Rob Kendrick][] wrote `lua-scrypt` back when there wasn't a shared +library for the scrypt algorithm. The returned values were binary and a bit +messy, and as such they are not supported by this version of the library. + +[libscrypt]: https://github.com/technion/libscrypt +[Rob Kendrick]: http://www.rjek.com/ diff --git a/config.ld b/config.ld new file mode 100644 index 0000000..50766d3 --- /dev/null +++ b/config.ld @@ -0,0 +1,6 @@ +file = {"luascrypt.c.ldoc"} +readme = "README" +format = "lua-markdown" +project = "lua-scrypt" +title = "lua-scrypt: Lua binding to libscrypt" +dir = "html" diff --git a/luascrypt.c.ldoc b/luascrypt.c.ldoc new file mode 100644 index 0000000..7e61b18 --- /dev/null +++ b/luascrypt.c.ldoc @@ -0,0 +1,54 @@ +--- +-- lua-scrypt: Bindings for libscrypt for Lua +-- +-- lua-scrypt is a binding to libscrypt which is a password crypting and +-- verification library. lua-scrypt uses the libscrypt library and +-- provides a simple interface for hashing and verifying passwords. +-- +-- @module scrypt +-- + +--- +-- Take a password and return its MCF-encoded scrypted hash +-- @function hash_password +-- @tparam string password The password to be hashed. +-- @tparam[opt] number N The scrypt 'N' parameter +-- @tparam[opt] number r The scrypt 'r' parameter +-- @tparam[opt] number p The scrypt 'p' parameter +-- @treturn string The hashed password +-- @raise If there is anything wrong with `N` `r` or `p` or various internal +-- errors within libscrypt, then this function will raise an error. +-- +-- This function takes the given password and uses the `scrypt` algorithm +-- to hash it. This algorithm is designed to cause difficulty in hardware +-- accelerating cracking by chaining operations to prevent parallelism and +-- using a non-trivial amount of RAM to make performing many separate tests +-- too expensive to do simultanously. To tune this, the three number +-- parameters can be used. `N` must be a power of two less than 65536 and +-- is used as a general "cost" factor. `r` is the block size factor and larger +-- values of `r` result in more memory being used. `p` is the parallelism +-- factor and larger numbers simply cause the algorithm to be run more than +-- once. +-- +-- If omitted, `N`, `r` and `p` default to 16384, 8 and 16 respectively. These +-- values mean that hashing (or verifying) a password will need 16 megabytes +-- of memory and will run at 16 iterations. This will take around 650ms to +-- hash a password on an i7 running around 4GHz (at the time of writing). +-- +-- **NOTE**: Despite the function description, if you want to supply any of +-- `N` `r` or `p` then you must provide them all. + + +--- +-- Take a password hash, and a password, and verify if they match. +-- @function verify_password +-- @tparam string crypted The hashed password (from `crypt.hash_password`) +-- @tparam string password The password to check against the hash. +-- @treturn boolean True if they match, otherwise false. +-- @raise If the hash is malformed then an error will be raised. +-- +-- This function takes the given hash and password and checks them against +-- one another. The `N` `r` and `p` parameters to the hashing are included +-- in the hashed password and have the same effect on verification as they did +-- on creation. + -- cgit v1.2.1