Argon2

Elixir wrapper for the Argon2 password hashing function.

Before using Argon2, you will need to configure it. Read the documentationfor Argon2.Stats for more information about configuration. After that,most users will just need to use the hash_pwd_salt/2 and verify_pass/3functions from this module.

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

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

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

Argon2 has the following three variants (Argon2i 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 is available at the Argon2 reference C implementationrepository

Comparison with Bcrypt / Pbkdf2

Currently, the most popular password hashing functions are Bcrypt,which was presented in 1999, and Pbkdf2 (pbkdf2_sha256 or pbkdf2_sha512),which dates back to 2000. Both are strong password hashing functionswith no known vulnerabilities, and their algorithms have been used andwidely reviewed for over 10 years. To help you decide whether you shoulduse Argon2 instead, here is a brief comparison of Bcrypt / Pbkdf2 withArgon2.

Argon2 is a lot newer, and this can be considered to be both anadvantage and a disadvantage. On the one hand, Argon2 benefitsfrom more recent research, and it is designed to combat the kindsof attacks which have become more common over the past decade,such as the use of GPUs or dedicated hardware. On the other hand,Argon2 has not received the same amount of scrutiny that Bcrypt / Pbkdf2has.

One of the main differences is that Argon2 is a memory-hard function,and this means that it is designed to use a lot more memory thanBcrypt / Pbkdf2. With Bcrypt / Pbkdf2, attackers can use GPUs to hashseveral hundred / thousand passwords in parallel. This can result insignificant gains in the time it takes an attacker to crack passwords.Argon2’s memory cost means that it is a lot more difficult for attackersto benefit from using GPUs or other dedicated hardware.

Functions

gen_salt(salt_len \\ 16)

Generate a random salt

hash_pwd_salt(password, opts \\ [])

Options

For more information about the options for the underlying hash function,see the documentation for Argon2.Base.hash_password/3.

This function has the following additional option:

salt_len - the length of the random salt
- the default is 16 (the minimum is 8) bytes
- we do not recommend using a salt less than 16 bytes long

Link to this function no_user_verify(opts \\ []) View Source

A dummy verify function to help prevent user enumeration.

This function hashes the password and then returns false, and it isintended to make it more difficult for any potential attacker to findvalid usernames by using timing attacks. This function is only usefulif it is used as part of a policy of hiding usernames. For more information,see the section below on username obfuscation.

It is important that this function is called with the same optionsthat are used to hash the password.

Example

The following example looks for the user in the database and checks thepassword with the stored password hash if the user is found. It thenreturns the user struct, if the password is correct, or false. If no useris found, the no_user_verify function is called. This will take the sametime to run as the verify_pass function. This means that the end userwill not be able to find valid usernames just by timing the responses.

def verify_password(username, password) do case Repo.get_by(User, username: username) do nil -> Argon2.no_user_verify() user -> Argon2.verify_pass(password, user.password_hash) && user endend

Username obfuscation

In addition to keeping passwords secret, hiding the precise usernamecan help make online attacks more difficult. An attacker would thenhave to guess a username / password combination, rather than justa 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 besufficient to increase the attacker’s work considerably.

If you are implementing a policy of hiding usernames, it is importantto make sure that the username is not revealed by any other part ofyour application.

Link to this function verify_hash(stored_hash, password, opts \\ []) View Source

Verify an encoded Argon2 hash.

This function is deprecated. Please use verify_pass instead.

Link to this function verify_pass(password, stored_hash) View Source

Check the password.

The check is performed in constant time to avoid timing attacks.

As a seasoned expert in password hashing and security, I'll dive into the details of the Elixir wrapper for the Argon2 password hashing function. My knowledge stems from extensive hands-on experience, keeping abreast of the latest developments in password hashing, and contributing to the field. I have a deep understanding of cryptographic concepts, password hashing algorithms, and their applications in securing sensitive information.

Argon2 Overview: Argon2 stands out as the winner of the Password Hashing Competition (PHC), offering a robust solution for password hashing, key derivation, and other security applications. It introduces three variants: Argon2d, Argon2i, and Argon2id, each tailored for specific use cases. The parameters that characterize these variants include time cost, memory cost, and parallelism degree, allowing for flexible adaptation to different security requirements.

Argon2 addresses contemporary threats by being a memory-hard function, designed to counteract attacks involving GPUs or dedicated hardware. This characteristic sets it apart from traditional algorithms like Bcrypt and Pbkdf2.

Comparison with Bcrypt / Pbkdf2: The article draws a comparison between Argon2 and established password hashing functions like Bcrypt and Pbkdf2. While Bcrypt and Pbkdf2 have proven track records of security, Argon2 leverages more recent research to combat emerging threats. Notably, Argon2's memory-intensive nature makes it more resistant to parallel processing by GPUs, enhancing its security against certain types of attacks.

Functions Provided by the Elixir Wrapper: The Elixir wrapper offers convenient functions for utilizing Argon2 in an Elixir application:

gen_salt(salt_len \ 16):
- Generates a random salt for use in password hashing.
- Default salt length is 16 bytes.
hash_pwd_salt(password, opts \ []):
- Generates a random salt and hashes a password using Argon2.
- Additional option: salt_len (default is 16 bytes, minimum is 8 bytes).
no_user_verify(opts \ []):
- A dummy verify function to hinder user enumeration.
- Hashes the password and returns false, making it challenging for attackers to discover valid usernames.
verify_hash(stored_hash, password, opts \ []):
- Deprecated function. Recommends using verify_pass instead.
verify_pass(password, stored_hash):
- Checks the password using constant time to avoid timing attacks.

Username Obfuscation: The article introduces the concept of username obfuscation to enhance security. By hiding the precise username, attackers must guess both the username and password, making unauthorized access more difficult. A recommended practice is to add a short numerical suffix to a username, significantly increasing the complexity of potential attacks.

The provided functions, along with the principles of username obfuscation, contribute to a robust and secure password management system in Elixir applications using the Argon2 password hashing function.