lua-argon2

Contents

• Functions
• Tables

Modules

• argon2

Examples

• usage.lua

Module argon2

Lua C binding for the Argon2 password hashing function.

Compatible with Lua 5.x and LuaJIT. See the Argon2 documentation for in-depth instructions and details about Argon2.

This module's version is compatible with Argon2 20161029 and later.

Note: this document is also valid for the lua-argon2-ffi module: an FFI implementation of this binding for LuaJIT which uses the same API as this original implementaiton.

Info:

• Release: 3.0.1
• License: MIT
• Author: Thibault Charbonnier

Functions

hash_encoded (plain, salt, options)	Hashes a password with Argon2i, Argon2d, or Argon2id, producing an encoded hash.
verify (encoded, password)	Verifies a password against an encoded string.

Tables

variants	Argon2 hashing variants.
options	Argon2 hashing options.

Functions

hash_encoded (plain, salt, options)

Hashes a password with Argon2i, Argon2d, or Argon2id, producing an encoded hash.

Parameters:

• plain string Plain string to hash_encoded.
• salt string Salt to use to hash the plain string.
• options table Options with which to hash the plain string. See options. This parameter is optional, if values are omitted the default ones will be used.

Returns:

1. string encoded: Encoded hash computed by Argon2, or nil if an error occurred.
2. string err: nil, or a string describing the error if any.

Usage:

local hash, err = argon2.hash_encoded("password", "somesalt")
if err then
  error("could not hash_encoded: " .. err)
end

-- with options and variant
local hash, err = argon2.hash_encoded("password", "somesalt", {
  t_cost = 4,
  m_cost = math.pow(2, 16), -- 65536 KiB
  variant = argon2.variants.argon2_d
})

verify (encoded, password)

Verifies a password against an encoded string.

Parameters:

• encoded string Encoded string to verify the plain password against.
• password string Plain password to verify.

Returns:

1. boolean ok: true if the password matches, false if it is a mismatch. If an error occurs during the verification, will be nil.
2. string err: nil, or a string describing the error if any. A password mismatch will not return an error, but will return ok = false instead.

Usage:

local ok, err = argon2.verify(argon2i_hash, "password")
if err then
  -- failure to verify (*not* a password mismatch)
  error("could not verify: " .. err)
end

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

-- with a argon2d hash
local ok, err = argon2.verify(argon2d_hash, "password")

Tables

variants

Argon2 hashing variants. Those fields are userdatums, read-only values that can be fed to the module's configuration or the hash_encoded function. See the Argon2 documentation for a description of those variants.

Fields:

• argon2_i
• argon2_d
• argon2_id

options

Argon2 hashing options. Those options can be given to hash_encoded as a table. If values are omitted, the default values of this module will be used. Default values of this module can be overriden with m_cost(), t_cost(), parallelism(), hash_len(), and variant().

Fields:

• t_cost

  Number of iterations (number, default: 3).

  argon2.hash_encoded("password", "salt", { t_cost = 4 })
  

  Can be set to a new default in lua-argon2 (C binding only) by calling:

  argon2.t_cost(4)
  

• m_cost

  Sets memory usage as KiB (number, default: 4096).

  argon2.hash_encoded("password", "salt", {
    m_cost = math.pow(2, 16) -- 2^16 aka 65536 KiB
  })
  

  Can be set to a new default in lua-argon2 (C binding only) by calling:

  argon2.m_cost(16)
  

• parallelism

  Number of threads and compute lanes (number, default: 1).

  argon2.hash_encoded("password", "salt", { parallelism = 2 })
  

  Can be set to a new default in lua-argon2 (C binding only) by calling:

  argon2.parallelism(2)
  

• hash_len

  Length of the hash output length (number, default: 32).

  argon2.hash_encoded("password", "salt", { hash_len = 64 })
  

  Can be set to a new default in lua-argon2 (C binding only) by calling:

  argon2.hash_len(64)
  

• variant

  Choose the Argon2 variant to use (Argon2i, Argon2d, Argon2id) from the variants table. (userdata, default: argon2.variants.argon2_i).

  argon2.hash_encoded("password", "salt", { variant = argon2.variants.argon2_d })
  

  Can be set to a new default in lua-argon2 (C binding only) by calling:

  argon2.variant(argon2.variants.argon2_i)
  argon2.variant(argon2.variants.argon2_d)
  argon2.variant(argon2.variants.argon2_id)