Merge pull request #10 from thibaultcha/refactor/cleanup

Backport lua-argon2 3.0.0's API (argon2_id and fixes)

.travis.yml

@@ -10,10 +10,6 @@ env:
   matrix:
     - LUA="luajit 2.0"
     - LUA="luajit 2.1"
-    - LUA="luajit 2.1"
-      ARGON2_VERSION=20160406
-    - LUA="luajit 2.1"
-      ARGON2_VERSION=20160821
 
 before_install:
   - bash .ci/setup_argon2.sh

CHANGELOG.md

@@ -0,0 +1,54 @@
+## [Unreleased][unrelease]
+
+## [3.0.0] - 2016/12/08
+
+**Note**: This module's version was bumped to `3.0.0` to reflect the
+interoperability of its API with the lua-argon2 implementation. In the future,
+lua-argon2 and lua-argon2-ffi will continue sharing the same version number
+for similar versions.
+
+### Changed
+
+- :warning: This version is only compatible with Argon2
+  [20160406](https://github.com/P-H-C/phc-winner-argon2/releases/tag/20160406)
+  and later.
+- :warning: Renamed the `encrypt()` function to `hash_encoded()`, in order to
+  carry a stronger meaning and to eventually implement a `hash_raw()` function
+  in the future.
+- New `variants` field with supported Argon2 encoding variants (as userdatum).
+  See documentation and the "Added" section of this Changelog.
+- Updated the default hashing options to match those of the Argon2 CLI:
+  `t_cost = 3`, `m_cost = 4096`, `parallelism = 1`, `hash_len = 32`.
+
+### Added
+
+- :stars: Support for Argon2id encoding variant.
+  [#24](https://github.com/thibaultcha/lua-argon2/pull/24)
+- We now automatically compute the length of the retrieved encoded hash from
+  `encrypt()`. [#21](https://github.com/thibaultcha/lua-argon2/pull/21)
+- New option: `hash_len`.
+  [#22](https://github.com/thibaultcha/lua-argon2/pull/22)
+- Return errors from `verify()`. A mismatch now returns `false, nil`, while an
+  error will return `nil, "err string"`.
+  [#23](https://github.com/thibaultcha/lua-argon2/pull/23)
+
+## [1.0.0] - 2016/04/10
+
+### Added
+
+- :stars: Support for Argon2
+  [20160406](https://github.com/P-H-C/phc-winner-argon2/releases/tag/20160406)
+  (and later). The major version of this module has been bumped because the
+  resulting hashes will not be backwards compatible.
+- Performance improvements.
+  [e9e6f9](https://github.com/thibaultcha/lua-argon2-ffi/commit/e9e6f9a609f40f9f26834364e05d701fbc0f9780)
+
+## [0.0.1] - 2016/02/21
+
+Initial release of this module for Argon2
+[20151206](https://github.com/P-H-C/phc-winner-argon2/releases/tag/20151206).
+
+[unreleased]: https://github.com/thibaultcha/lua-argon2-ffi/compare/3.0.0...master
+[3.0.0]: https://github.com/thibaultcha/lua-argon2-ffi/compare/1.0.0...3.0.0
+[1.0.0]: https://github.com/thibaultcha/lua-argon2-ffi/compare/0.0.1...1.0.0
+[0.0.1]: https://github.com/thibaultcha/lua-argon2-ffi/compare/a2f94a08ec34bdd570ff707f5e2bebf87a60ba62...0.0.1

README.md

@@ -1,15 +1,24 @@
 # lua-argon2-ffi
+
 [![Module Version][badge-version-image]][luarocks-argon2-ffi]
 [![Build Status][badge-travis-image]][badge-travis-url]
 [![Coverage Status][badge-coveralls-image]][badge-coveralls-url]
 
-FFI binding of [Argon2] for LuaJIT.
+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].
 
-### Prerequisites
+### Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Example](#example)
+- [License](#license)
+
+### Requirements
 
 The [Argon2] shared library must be compiled and available in your system.
 
@@ -19,11 +28,16 @@ Compatibility:
 - Version `1.x` of this module is compatible with Argon2
   [`20160406`](https://github.com/P-H-C/phc-winner-argon2/releases/tag/20160406)
   and later.
+- Version `3.x` of this module is compatible with Argon2
+  [`20161029`](https://github.com/P-H-C/phc-winner-argon2/releases/tag/20161029)
+  and later.
 
 See the [CI builds][badge-coveralls-url] for the status of the currently
 supported versions.
 
-### Install
+[Back to TOC](#table-of-contents)
+
+### Installation
 
 This binding can be installed via [Luarocks](https://luarocks.org):
 
@@ -33,61 +47,85 @@ $ luarocks install argon2-ffi
 
 Or simply by copying the `src/argon2.lua` file in your `LUA_PATH`.
 
-### Usage
+[Back to TOC](#table-of-contents)
+
+### Documentation
 
 **Note**: lua-argon2-ffi uses the same API as [lua-argon2], to the exception of
 the default settings capabilities of lua-argon2.
 
-Encrypt:
+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](#table-of-contents)
+
+### Example
+
+Hash a password to an encoded string:
 
 ```lua
 local argon2 = require "argon2"
 --- Prototype
--- local hash, err = argon2.encrypt(pwd, salt, opts)
+-- local encoded, err = argon2.hash_encoded(pwd, salt, opts)
 
 --- Argon2i
-local hash = assert(argon2.encrypt("password", "somesalt"))
--- hash is "$argon2i$m=12,t=2,p=1$c29tZXNhbHQ$ltrjNRFqTXmsHj++TFGZxg+zSg8hSrrSJiViCRns1HM"
+local encoded = assert(argon2.hash_encoded("password", "somesalt"))
+-- encoded is "$argon2i$v=19$m=4096,t=3,p=1$c29tZXNhbHQ$iWh06vD8Fy27wf9npn6FXWiCX4K6pW6Ue1Bnzz07Z8A"
 
 --- Argon2d
-local hash = assert(argon2.encrypt("password", "somesalt", {argon2d = true}))
--- hash is "$argon2d$m=12,t=2,p=1$c29tZXNhbHQ$mfklun4fYCbv2Hw0UnZZ56xAqWbjD+XRMSN9h6SfLe4"
+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 hash = assert(argon2.encrypt("password", "somesalt", {
+local encoded = assert(argon2.hash_encoded("password", "somesalt", {
   t_cost = 4,
-  m_cost = 24,
-  parallelism = 2,
-  hash_len = 64
+  m_cost = math.pow(2, 16), -- 65536 KiB
+  parallelism = 2
 }))
--- hash is "$argon2i$v=19$m=24,t=4,p=2$c29tZXNhbHQ$NV3zeCzIhUhosd7jtTuifTEoPOb/aPAtO0oTYdZkWfNBXCglBgxVEiJy+tLG4j011vZRO3pnmG82Vc/C1B6Tzw"
+-- encoded is "$argon2i$v=19$m=65536,t=4,p=2$c29tZXNhbHQ$n6x5DKNWV8BOeKemQJRk7BU3hcaCVomtn9TCyEA0inM"
 ```
 
-Verify:
+Verify a password against an encoded string:
 
 ```lua
 local argon2 = require "argon2"
 --- Prototype
 -- local ok, err = argon2.decrypt(hash, plain)
 
-local hash = assert(argon2.encrypt("password", "somesalt"))
--- hash is an argon2i hash
+local encoded = assert(argon2.hash_encoded("password", "somesalt"))
+-- encoded: argon2i encoded hash
 
-assert(argon2.verify(hash, "password")) -- ok: true
-assert(argon2.verify(hash, "passworld")) -- error: The password did not match
-```
+local ok, err = argon2.verify(encoded, "password")
+if err then
+  error("could not verify: " .. err)
+end
 
-### Documentation
+if not ok then
+  error("The password does not match the supplied hash")
+end
+```
 
-This module's API being the same as [lua-argon2]'s, the detailed documentation
-is available at <http://thibaultcha.github.io/lua-argon2>.
+[Back to TOC](#table-of-contents)
 
 ### License
 
 Work licensed under the MIT License. Please check
-[P-H-C/phc-winner-argon2][Argon2] for license over Argon2 and the reference
+[P-H-C/phc-winner-argon2][Argon2] for the license over Argon2 and the reference
 implementation.
 
+[Back to TOC](#table-of-contents)
+
 [Argon2]: https://github.com/P-H-C/phc-winner-argon2
 [lua-argon2]: https://github.com/thibaultCha/lua-argon2
 [luarocks-argon2-ffi]: http://luarocks.org/modules/thibaultcha/argon2-ffi
@@ -97,6 +135,6 @@ implementation.
 
 [badge-travis-url]: https://travis-ci.org/thibaultcha/lua-argon2-ffi
 [badge-travis-image]: https://travis-ci.org/thibaultcha/lua-argon2-ffi.svg?branch=master
-[badge-version-image]: https://img.shields.io/badge/version-1.0.0-blue.svg?style=flat
+[badge-version-image]: https://img.shields.io/badge/version-3.0.0-blue.svg?style=flat
 [badge-coveralls-url]: https://coveralls.io/github/thibaultcha/lua-argon2-ffi?branch=master
 [badge-coveralls-image]: https://coveralls.io/repos/github/thibaultcha/lua-argon2-ffi/badge.svg?branch=master

argon2-ffi-1.0.0-0.rockspec → argon2-ffi-3.0.0-1.rockspec

@@ -1,12 +1,12 @@
 package = "argon2-ffi"
-version = "1.0.0-0"
+version = "3.0.0-1"
 source = {
-  url = "git://github.com/thibaultCha/lua-argon2-ffi",
-  tag = "1.0.0"
+  url = "git://github.com/thibaultcha/lua-argon2-ffi",
+  tag = "3.0.0"
 }
 description = {
-  summary = "LuaJIT FFI binding for the Argon2 password hashing algorithm",
-  homepage = "https://github.com/thibaultCha/lua-argon2-ffi",
+  summary = "LuaJIT FFI binding for the Argon2 password hashing function",
+  homepage = "https://github.com/thibaultcha/lua-argon2-ffi",
   license = "MIT"
 }
 build = {