Add ldoc based documentation

1 files changed, 54 insertions, 0 deletions

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.
+