README.md in argon2-1.0.0

- old
+ new

@@ -1,23 +1,36 @@
 # Argon2
 
+[![Build Status](https://travis-ci.org/P-H-C/phc-winner-argon2.svg?branch=master)](https://travis-ci.org/P-H-C/phc-winner-argon2)
+[![codecov.io](https://codecov.io/github/P-H-C/phc-winner-argon2/coverage.svg?branch=master)](https://codecov.io/github/P-H-C/phc-winner-argon2?branch=master)
+
 This is the reference C implementation of Argon2, the password-hashing
 function that won the [Password Hashing Competition
-(PHC)](https://password-hashing.net). 
+(PHC)](https://password-hashing.net).
 
-You should use Argon2 whenever you need to hash passwords for credential
-storage, key derivation, or other applications.
+Argon2 is a password-hashing function that summarizes the state of the
+art in the design of memory-hard functions and can be used to hash
+passwords for credential storage, key derivation, or other applications.
 
-There are two main versions of Argon2, **Argon2i** and **Argon2d**. Argon2i
-is the safest against side-channel attacks, while Argon2d provides the
-highest resistance against GPU cracking attacks.
+It has a simple design aimed at the highest memory filling rate and
+effective use of multiple computing units, while still providing defense
+against tradeoff attacks (by exploiting the cache and memory organization
+of the recent processors).
 
-Argon2i and Argon2d are parametrized by
+Argon2 has two variants: Argon2d and Argon2i. Argon2d is faster and
+uses data-depending memory access, which makes it highly resistant
+against GPU cracking attacks and suitable for applications with no threats
+from side-channel timing attacks (eg. cryptocurrencies). Argon2i instead
+uses data-independent memory access, which is preferred for password
+hashing and password-based key derivation, but it is slower as it makes
+more passes over the memory to protect from tradeoff attacks.
 
+Argon2i and Argon2d are parametrized by:
+
 * A **time** cost, which defines the amount of computation realized and
   therefore the execution time, given in number of iterations
-* A **memory** cost, which defines the memory usage, given in kibibytes 
+* A **memory** cost, which defines the memory usage, given in kibibytes
 * A **parallelism** degree, which defines the number of parallel threads
 
 The [Argon2 document](argon2-specs.pdf) gives detailed specs and design
 rationale.
 
@@ -37,27 +50,29 @@
 `./argon2` without arguments as
 ```
 Usage:  ./argon2 salt [-d] [-t iterations] [-m memory] [-p parallelism]
         Password is read from stdin
 Parameters:
-        salt            The salt to use, at most 16 characters
+        salt            The salt to use, at least 8 characters 
         -d              Use Argon2d instead of Argon2i (which is the default)
         -t N            Sets the number of iterations to N (default = 3)
         -m N            Sets the memory usage of 2^N KiB (default 12)
         -p N            Sets parallelism to N threads (default 1)
+        -h N            Sets hash output length to N bytes (default 32)
 ```
 For example, to hash "password" using "somesalt" as a salt and doing 2
-iterations, consuming 64 MiB, and using four parallel threads:
+iterations, consuming 64 MiB, using four parallel threads and an output hash
+of 24 bytes
 ```
-$ echo -n "password" | ./argon2 somesalt -t 2 -m 16 -p 4
+$ echo -n "password" | ./argon2 somesalt -t 2 -m 16 -p 4 -h 24
 Type:           Argon2i
 Iterations:     2
 Memory:         65536 KiB
 Parallelism:    4
-Hash:           4162f32384d8f4790bd994cb73c83a4a29f076165ec18af3cfdcf10a8d1b9066
-Encoded:        $argon2i$m=65536,t=2,p=4$c29tZXNhbHQAAAAAAAAAAA$QWLzI4TY9HkL2ZTLc8g6SinwdhZewYrzz9zxCo0bkGY
-0.271 seconds
+Hash:           5a028f1a99c9eae671ee448ab80057b78510430865abe57f
+Encoded:        $argon2i$m=65536,t=2,p=4$c29tZXNhbHQ$WgKPGpnJ6uZx7kSKuABXt4UQQwhlq+V/
+0.188 seconds
 Verification ok
 ```
 
 ### Library
 
@@ -66,11 +81,11 @@
 
 The example program below hashes the string "password" with Argon2i
 using the high-level API and then using the low-level API. While the
 high-level API only takes input/output buffers and the two cost
 parameters, the low-level API additionally takes parallelism parameters
-and several others, as defined in [`src/argon2.h`](src/argon2.h).
+and several others, as defined in [`include/argon2.h`](include/argon2.h).
 
 
 Here the time cost `t_cost` is set to 2 iterations, the
 memory cost `m_cost` is set to 2<sup>16</sup> kibibytes (64 mebibytes),
 and parallelism is set to 1 (single-thread).
@@ -108,16 +123,16 @@
 
     // low-level API
     uint32_t lanes = parallelism;
     uint32_t threads = parallelism;
     argon2_context context = {
-        hash2, HASHLEN, 
-        pwd, pwdlen, 
+        hash2, HASHLEN,
+        pwd, pwdlen,
         salt, SALTLEN,
         NULL, 0, /* secret data */
         NULL, 0, /* associated data */
-        t_cost, m_cost, parallelism, parallelism, 
+        t_cost, m_cost, parallelism, parallelism,
         NULL, NULL, /* custom memory allocation / deallocation functions */
         ARGON2_DEFAULT_FLAGS /* by default the password is zeroed on exit */
     };
     argon2i( &context );
     free(pwd);
@@ -138,11 +153,11 @@
 `argon2i` using the low-level API.
 
 To produce the crypt-like encoding rather than the raw hash, call
 `argon2i_hash_encoded` for Argon2i and `argon2d_hash_encoded` for Argon2d.
 
-See [`src/argon2.h`](src/argon2.h) for API detais.
+See [`include/argon2.h`](include/argon2.h) for API details.
 
 *Note: in this example the salt is set to the all-`0x00` string for the
 sake of simplicity, but in your application you should use a random salt.*
 
 
@@ -181,13 +196,27 @@
 ## Bindings
 
 Bindings are available for the following languages (make sure to read
 their documentation):
 
+* [Go](https://github.com/tvdburgt/go-argon2) by [@tvdburgt](https://github.com/tvdburgt)
+* [Haskell](https://hackage.haskell.org/package/argon2-1.0.0/docs/Crypto-Argon2.html) by [@ocharles](https://github.com/ocharles)
 * [Javascript](https://github.com/ranisalt/node-argon2), by [@ranisalt](https://github.com/ranisalt)
+* [JVM](https://github.com/phxql/argon2-jvm) by [@phXql](https://github.com/phxql)
+* [Lua](https://github.com/thibaultCha/lua-argon2) by [@thibaultCha](https://github.com/thibaultCha)
+* [OCaml](https://github.com/Khady/ocaml-argon2) by [@Khady](https://github.com/Khady)
 * [Python](https://pypi.python.org/pypi/argon2), by [@flamewow](https://github.com/flamewow)
+* [Python](https://pypi.python.org/pypi/argon2_cffi), by [@hynek](https://github.com/hynek)
 * [Ruby](https://github.com/technion/ruby-argon2) by [@technion](https://github.com/technion)
+* [Rust](https://github.com/quininer/argon2-rs) by [@quininer](https://github.com/quininer)
 
+## Test Suite
+
+There are two sets of test suites. One is a low level test for the hash
+function, the other tests the higher level API. Both of these are built and
+executed by running:
+
+`make test`
 
 ## Intellectual property
 
 Except for the components listed below, the Argon2 code in this
 repository is copyright (c) 2015 Daniel Dinu, Dmitry Khovratovich (main