View Source Argon2 (argon2_elixir v4.0.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
Hashes a password with a randomly generated salt.
Runs the password hash function, but always returns false.
Verifies a password by hashing the password and comparing the hashed value with a stored hash.
Functions
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)
falseRuns 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.
Options
This function should be called with the same options as those used by
hash_pwd_salt/2.
Hiding usernames
In addition to keeping passwords secret, hiding the precise username can help make online attacks more difficult. An attacker would then have to guess a username / password combination, rather than just a password, to gain access.
This does not mean that the username should be kept completely secret. Adding a short numerical suffix to a user's name, for example, would be sufficient to increase the attacker's work considerably.
If you are implementing a policy of hiding usernames, it is important to make sure that the username is not revealed by any other part of your application.
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.