diff options
Diffstat (limited to 'luascrypt.c.ldoc')
-rw-r--r-- | luascrypt.c.ldoc | 54 |
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. + |