1# Argon2 2 3[](https://travis-ci.org/P-H-C/phc-winner-argon2) 4[](https://ci.appveyor.com/project/P-H-C/phc-winner-argon2) 5[](https://codecov.io/github/P-H-C/phc-winner-argon2?branch=master) 6 7This is the reference C implementation of Argon2, the password-hashing 8function that won the [Password Hashing Competition 9(PHC)](https://password-hashing.net). 10 11Argon2 is a password-hashing function that summarizes the state of the 12art in the design of memory-hard functions and can be used to hash 13passwords for credential storage, key derivation, or other applications. 14 15It has a simple design aimed at the highest memory filling rate and 16effective use of multiple computing units, while still providing defense 17against tradeoff attacks (by exploiting the cache and memory organization 18of the recent processors). 19 20Argon2 has three variants: Argon2i, Argon2d, and Argon2id. Argon2d is faster 21and uses data-depending memory access, which makes it highly resistant 22against GPU cracking attacks and suitable for applications with no threats 23from side-channel timing attacks (eg. cryptocurrencies). Argon2i instead 24uses data-independent memory access, which is preferred for password 25hashing and password-based key derivation, but it is slower as it makes 26more passes over the memory to protect from tradeoff attacks. Argon2id is a 27hybrid of Argon2i and Argon2d, using a combination of data-depending and 28data-independent memory accesses, which gives some of Argon2i's resistance to 29side-channel cache timing attacks and much of Argon2d's resistance to GPU 30cracking attacks. 31 32Argon2i, Argon2d, and Argon2id are parametrized by: 33 34* A **time** cost, which defines the amount of computation realized and 35 therefore the execution time, given in number of iterations 36* A **memory** cost, which defines the memory usage, given in kibibytes 37* A **parallelism** degree, which defines the number of parallel threads 38 39The [Argon2 document](argon2-specs.pdf) gives detailed specs and design 40rationale. 41 42Please report bugs as issues on this repository. 43 44## Usage 45 46`make` builds the executable `argon2`, the static library `libargon2.a`, 47and the shared library `libargon2.so` (or `libargon2.dylib` on OSX). 48Make sure to run `make test` to verify that your build produces valid 49results. `make install PREFIX=/usr` installs it to your system. 50 51### Command-line utility 52 53`argon2` is a command-line utility to test specific Argon2 instances 54on your system. To show usage instructions, run 55`./argon2 -h` as 56``` 57Usage: ./argon2 [-h] salt [-i|-d|-id] [-t iterations] [-m memory] [-p parallelism] [-l hash length] [-e|-r] [-v (10|13)] 58 Password is read from stdin 59Parameters: 60 salt The salt to use, at least 8 characters 61 -i Use Argon2i (this is the default) 62 -d Use Argon2d instead of Argon2i 63 -id Use Argon2id instead of Argon2i 64 -t N Sets the number of iterations to N (default = 3) 65 -m N Sets the memory usage of 2^N KiB (default 12) 66 -p N Sets parallelism to N threads (default 1) 67 -l N Sets hash output length to N bytes (default 32) 68 -e Output only encoded hash 69 -r Output only the raw bytes of the hash 70 -v (10|13) Argon2 version (defaults to the most recent version, currently 13) 71 -h Print argon2 usage 72``` 73For example, to hash "password" using "somesalt" as a salt and doing 2 74iterations, consuming 64 MiB, using four parallel threads and an output hash 75of 24 bytes 76``` 77$ echo -n "password" | ./argon2 somesalt -t 2 -m 16 -p 4 -l 24 78Type: Argon2i 79Iterations: 2 80Memory: 65536 KiB 81Parallelism: 4 82Hash: 45d7ac72e76f242b20b77b9bf9bf9d5915894e669a24e6c6 83Encoded: $argon2i$v=19$m=65536,t=2,p=4$c29tZXNhbHQ$RdescudvJCsgt3ub+b+dWRWJTmaaJObG 840.188 seconds 85Verification ok 86``` 87 88### Library 89 90`libargon2` provides an API to both low-level and high-level functions 91for using Argon2. 92 93The example program below hashes the string "password" with Argon2i 94using the high-level API and then using the low-level API. While the 95high-level API takes the three cost parameters (time, memory, and 96parallelism), the password input buffer, the salt input buffer, and the 97output buffers, the low-level API takes in these and additional parameters 98, as defined in [`include/argon2.h`](include/argon2.h). 99 100There are many additional parameters, but we will highlight three of them here. 101 1021. The `secret` parameter, which is used for [keyed hashing]( 103 https://en.wikipedia.org/wiki/Hash-based_message_authentication_code). 104 This allows a secret key to be input at hashing time (from some external 105 location) and be folded into the value of the hash. This means that even if 106 your salts and hashes are compromized, an attacker cannot brute-force to find 107 the password without the key. 108 1092. The `ad` parameter, which is used to fold any additional data into the hash 110 value. Functionally, this behaves almost exactly like the `secret` or `salt` 111 parameters; the `ad` parameter is folding into the value of the hash. 112 However, this parameter is used for different data. The `salt` should be a 113 random string stored alongside your password. The `secret` should be a random 114 key only usable at hashing time. The `ad` is for any other data. 115 1163. The `flags` parameter, which determines which memory should be securely 117 erased. This is useful if you want to securly delete the `pwd` or `secret` 118 fields right after they are used. To do this set `flags` to either 119 `ARGON2_FLAG_CLEAR_PASSWORD` or `ARGON2_FLAG_CLEAR_SECRET`. To change how 120 internal memory is cleared, change the global flag 121 `FLAG_clear_internal_memory` (defaults to clearing internal memory). 122 123Here the time cost `t_cost` is set to 2 iterations, the 124memory cost `m_cost` is set to 2<sup>16</sup> kibibytes (64 mebibytes), 125and parallelism is set to 1 (single-thread). 126 127Compile for example as `gcc test.c libargon2.a -Isrc -o test`, if the program 128below is named `test.c` and placed in the project's root directory. 129 130```c 131#include "argon2.h" 132#include <stdio.h> 133#include <string.h> 134#include <stdlib.h> 135 136#define HASHLEN 32 137#define SALTLEN 16 138#define PWD "password" 139 140int main(void) 141{ 142 uint8_t hash1[HASHLEN]; 143 uint8_t hash2[HASHLEN]; 144 145 uint8_t salt[SALTLEN]; 146 memset( salt, 0x00, SALTLEN ); 147 148 uint8_t *pwd = (uint8_t *)strdup(PWD); 149 uint32_t pwdlen = strlen((char *)pwd); 150 151 uint32_t t_cost = 2; // 1-pass computation 152 uint32_t m_cost = (1<<16); // 64 mebibytes memory usage 153 uint32_t parallelism = 1; // number of threads and lanes 154 155 // high-level API 156 argon2i_hash_raw(t_cost, m_cost, parallelism, pwd, pwdlen, salt, SALTLEN, hash1, HASHLEN); 157 158 // low-level API 159 argon2_context context = { 160 hash2, /* output array, at least HASHLEN in size */ 161 HASHLEN, /* digest length */ 162 pwd, /* password array */ 163 pwdlen, /* password length */ 164 salt, /* salt array */ 165 SALTLEN, /* salt length */ 166 NULL, 0, /* optional secret data */ 167 NULL, 0, /* optional associated data */ 168 t_cost, m_cost, parallelism, parallelism, 169 ARGON2_VERSION_13, /* algorithm version */ 170 NULL, NULL, /* custom memory allocation / deallocation functions */ 171 /* by default only internal memory is cleared (pwd is not wiped) */ 172 ARGON2_DEFAULT_FLAGS 173 }; 174 175 int rc = argon2i_ctx( &context ); 176 if(ARGON2_OK != rc) { 177 printf("Error: %s\n", argon2_error_message(rc)); 178 exit(1); 179 } 180 free(pwd); 181 182 for( int i=0; i<HASHLEN; ++i ) printf( "%02x", hash1[i] ); printf( "\n" ); 183 if (memcmp(hash1, hash2, HASHLEN)) { 184 for( int i=0; i<HASHLEN; ++i ) { 185 printf( "%02x", hash2[i] ); 186 } 187 printf("\nfail\n"); 188 } 189 else printf("ok\n"); 190 return 0; 191} 192``` 193 194To use Argon2d instead of Argon2i call `argon2d_hash_raw` instead of 195`argon2i_hash_raw` using the high-level API, and `argon2d` instead of 196`argon2i` using the low-level API. Similarly for Argon2id, call `argon2id_hash_raw` 197and `argon2id`. 198 199To produce the crypt-like encoding rather than the raw hash, call 200`argon2i_hash_encoded` for Argon2i, `argon2d_hash_encoded` for Argon2d, and 201`argon2id_hash_encoded` for Argon2id 202 203See [`include/argon2.h`](include/argon2.h) for API details. 204 205*Note: in this example the salt is set to the all-`0x00` string for the 206sake of simplicity, but in your application you should use a random salt.* 207 208 209### Benchmarks 210 211`make bench` creates the executable `bench`, which measures the execution 212time of various Argon2 instances: 213 214``` 215$ ./bench 216Argon2d 1 iterations 1 MiB 1 threads: 5.91 cpb 5.91 Mcycles 217Argon2i 1 iterations 1 MiB 1 threads: 4.64 cpb 4.64 Mcycles 2180.0041 seconds 219 220Argon2d 1 iterations 1 MiB 2 threads: 2.76 cpb 2.76 Mcycles 221Argon2i 1 iterations 1 MiB 2 threads: 2.87 cpb 2.87 Mcycles 2220.0038 seconds 223 224Argon2d 1 iterations 1 MiB 4 threads: 3.25 cpb 3.25 Mcycles 225Argon2i 1 iterations 1 MiB 4 threads: 3.57 cpb 3.57 Mcycles 2260.0048 seconds 227 228(...) 229 230Argon2d 1 iterations 4096 MiB 2 threads: 2.15 cpb 8788.08 Mcycles 231Argon2i 1 iterations 4096 MiB 2 threads: 2.15 cpb 8821.59 Mcycles 23213.0112 seconds 233 234Argon2d 1 iterations 4096 MiB 4 threads: 1.79 cpb 7343.72 Mcycles 235Argon2i 1 iterations 4096 MiB 4 threads: 2.72 cpb 11124.86 Mcycles 23619.3974 seconds 237 238(...) 239``` 240 241## Bindings 242 243Bindings are available for the following languages (make sure to read 244their documentation): 245 246* [Elixir](https://github.com/riverrun/argon2_elixir) by [@riverrun](https://github.com/riverrun) 247* [Erlang](https://github.com/ergenius/eargon2) by [@ergenius](https://github.com/ergenius) 248* [Go](https://github.com/tvdburgt/go-argon2) by [@tvdburgt](https://github.com/tvdburgt) 249* [Haskell](https://hackage.haskell.org/package/argon2) by [@hvr](https://github.com/hvr) 250* [JavaScript (native)](https://github.com/ranisalt/node-argon2), by [@ranisalt](https://github.com/ranisalt) 251* [JavaScript (native)](https://github.com/jdconley/argon2themax), by [@jdconley](https://github.com/jdconley) 252* [JavaScript (ffi)](https://github.com/cjlarose/argon2-ffi), by [@cjlarose](https://github.com/cjlarose) 253* [JavaScript (browser)](https://github.com/antelle/argon2-browser), by [@antelle](https://github.com/antelle) 254* [JVM](https://github.com/phxql/argon2-jvm) by [@phXql](https://github.com/phxql) 255* [JVM (with keyed hashing)](https://github.com/kosprov/jargon2-api) by [@kosprov](https://github.com/kosprov) 256* [Lua (native)](https://github.com/thibaultCha/lua-argon2) by [@thibaultCha](https://github.com/thibaultCha) 257* [Lua (ffi)](https://github.com/thibaultCha/lua-argon2-ffi) by [@thibaultCha](https://github.com/thibaultCha) 258* [OCaml](https://github.com/Khady/ocaml-argon2) by [@Khady](https://github.com/Khady) 259* [Python (native)](https://pypi.python.org/pypi/argon2), by [@flamewow](https://github.com/flamewow) 260* [Python (ffi)](https://pypi.python.org/pypi/argon2_cffi), by [@hynek](https://github.com/hynek) 261* [Python (ffi, with keyed hashing)](https://github.com/thusoy/porridge), by [@thusoy](https://github.com/thusoy) 262* [R](https://cran.r-project.org/package=argon2) by [@wrathematics](https://github.com/wrathematics) 263* [Ruby](https://github.com/technion/ruby-argon2) by [@technion](https://github.com/technion) 264* [Rust](https://github.com/quininer/argon2-rs) by [@quininer](https://github.com/quininer) 265* [Rust](https://docs.rs/argonautica/) by [@bcmyers](https://github.com/bcmyers/) 266* [C#/.NET CoreCLR](https://github.com/kmaragon/Konscious.Security.Cryptography) by [@kmaragon](https://github.com/kmaragon) 267* [Perl](https://github.com/Leont/crypt-argon2) by [@leont](https://github.com/Leont) 268* [mruby](https://github.com/Asmod4n/mruby-argon2) by [@Asmod4n](https://github.com/Asmod4n) 269* [Swift](https://github.com/ImKcat/CatCrypto) by [@ImKcat](https://github.com/ImKcat) 270 271 272## Test suite 273 274There are two sets of test suites. One is a low level test for the hash 275function, the other tests the higher level API. Both of these are built and 276executed by running: 277 278`make test` 279 280## Intellectual property 281 282Except for the components listed below, the Argon2 code in this 283repository is copyright (c) 2015 Daniel Dinu, Dmitry Khovratovich (main 284authors), Jean-Philippe Aumasson and Samuel Neves, and dual licensed under the 285[CC0 License](https://creativecommons.org/about/cc0) and the 286[Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0). For more info 287see the LICENSE file. 288 289The string encoding routines in [`src/encoding.c`](src/encoding.c) are 290copyright (c) 2015 Thomas Pornin, and under 291[CC0 License](https://creativecommons.org/about/cc0). 292 293The BLAKE2 code in [`src/blake2/`](src/blake2) is copyright (c) Samuel 294Neves, 2013-2015, and under 295[CC0 License](https://creativecommons.org/about/cc0). 296 297All licenses are therefore GPL-compatible. 298
){kind=link}
){kind=link}