Home

Awesome

lua-argon2-ffi

Module Version Build Status Coverage Status

LuaJIT FFI binding for the Argon2 password hashing function.

While lua-argon2 provides a PUC Lua binding through the Lua C API, this module is a binding for the LuaJIT FFI, especially fit for use in ngx_lua/OpenResty.

Table of Contents

Requirements

The Argon2 shared library must be compiled and available in your system.

Compatibility:

See the CI builds for the status of the currently supported versions.

Back to TOC

Installation

This binding can be installed via Luarocks:

$ luarocks install argon2-ffi

Or via opm:

$ opm get thibaultcha/lua-argon2-ffi

Or simply by copying the src/argon2.lua file in your LUA_PATH.

Back to TOC

Documentation

Note: lua-argon2-ffi uses the same API as lua-argon2, to the exception of the default settings capabilities of lua-argon2.

This binding's documentation is available at http://thibaultcha.github.io/lua-argon2/.

The Argon2 password hashing function documentation is available at https://github.com/P-H-C/phc-winner-argon2.

Back to TOC

Example

Hash a password to an encoded string:

local argon2 = require "argon2"
--- Prototype
-- local encoded, err = argon2.hash_encoded(pwd, salt, opts)

--- Argon2i
local encoded = assert(argon2.hash_encoded("password", "somesalt"))
-- encoded is "$argon2i$v=19$m=4096,t=3,p=1$c29tZXNhbHQ$iWh06vD8Fy27wf9npn6FXWiCX4K6pW6Ue1Bnzz07Z8A"

--- Argon2d
local encoded = assert(argon2.hash_encoded("password", "somesalt", {
  variant = argon2.variants.argon2_d
}))
-- encoded is "$argon2d$v=19$m=4096,t=3,p=1$c29tZXNhbHQ$2+JCoQtY/2x5F0VB9pEVP3xBNguWP1T25Ui0PtZuk8o"

--- Argon2id
local encoded = assert(argon2.hash_encoded("password", "somesalt", {
  variant = argon2.variants.argon2_id
}))
-- encoded is "$argon2id$v=19$m=4096,t=3,p=1$c29tZXNhbHQ$qLml5cbqFAO6YxVHhrSBHP0UWdxrIxkNcM8aMX3blzU"

-- Hashing options
local encoded = assert(argon2.hash_encoded("password", "somesalt", {
  t_cost = 4,
  m_cost = math.pow(2, 16), -- 65536 KiB
  parallelism = 2
}))
-- encoded is "$argon2i$v=19$m=65536,t=4,p=2$c29tZXNhbHQ$n6x5DKNWV8BOeKemQJRk7BU3hcaCVomtn9TCyEA0inM"

Verify a password against an encoded string:

local argon2 = require "argon2"
--- Prototype
-- local ok, err = argon2.decrypt(hash, plain)

local encoded = assert(argon2.hash_encoded("password", "somesalt"))
-- encoded: argon2i encoded hash

local ok, err = argon2.verify(encoded, "password")
if err then
  error("could not verify: " .. err)
end

if not ok then
  error("The password does not match the supplied hash")
end

Back to TOC

License

Work licensed under the MIT License. Please check P-H-C/phc-winner-argon2 for the license over Argon2 and the reference implementation.

Back to TOC