View Source Argon2 (argon2_elixir v4.1.0)

Elixir wrapper for the Argon2 password hashing function.

For a lower-level API, see Argon2.Base.

Configuration

See the documentation for Argon2.Stats for information about configuration.

Argon2

Argon2 is the winner of the Password Hashing Competition (PHC).

Argon2 is a memory-hard password hashing function which can be used to hash passwords for credential storage, key derivation, or other applications.

Argon2 has the following three variants (Argon2id is the default):

  • Argon2d - suitable for applications with no threats from side-channel timing attacks (eg. cryptocurrencies)
  • Argon2i - suitable for password hashing and password-based key derivation
  • Argon2id - a hybrid of Argon2d and Argon2i

Argon2i, Argon2d, and Argon2id 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 parallelism degree, which defines the number of parallel threads

More information can be found in the documentation for the Argon2.Stats module and at the Argon2 reference C implementation repository.

Comparison with Bcrypt / Pbkdf2

Argon2 has better password cracking resistance than Bcrypt and Pbkdf2. Its main advantage is that, as it is a memory-hard function, it is designed to withstand parallel attacks that use GPUs or other dedicated hardware.

Summary

Functions

hash_pwd_salt(password, opts \\ [])

Hashes a password with a randomly generated salt.

no_user_verify(opts \\ [])

Runs the password hash function, but always returns false.

verify_pass(password, stored_hash)

Verifies a password by hashing the password and comparing the hashed value with a stored hash.

Functions

Link to this function

hash_pwd_salt(password, opts \\ [])

View Source

Hashes a password with a randomly generated salt.

Options

In addition to the :salt_len option shown below, this function also takes options that are then passed on to the hash_password function in the Argon2.Base module.

See the documentation for Argon2.Base.hash_password/3 for further details.

  • :salt_len - the length of the random salt
    • the default is 16 (the minimum is 8) bytes

Examples

The following examples show how to hash a password with a randomly-generated salt and then verify a password:

iex> hash = Argon2.hash_pwd_salt("password")
...> Argon2.verify_pass("password", hash)
true

iex> hash = Argon2.hash_pwd_salt("password")
...> Argon2.verify_pass("incorrect", hash)
false
Link to this function

no_user_verify(opts \\ [])

View Source

Runs the password hash function, but always returns false.

This function is intended to make it more difficult for any potential attacker to find valid usernames by using timing attacks. This function is only useful if it is used as part of a policy of hiding usernames.

There are concerns about this function using too many resources (CPU and memory). An alternative approach is to create a function that adds a sleep calculated to make the time spent running the function the same as if the hash function was run.

Options

This function should be called with the same options as those used by hash_pwd_salt/2.

Link to this function

verify_pass(password, stored_hash)

View Source

Verifies a password by hashing the password and comparing the hashed value with a stored hash.

See the documentation for hash_pwd_salt/2 for examples of using this function.