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