View Source Bcrypt (bcrypt_elixir v3.1.0)

Elixir wrapper for the Bcrypt password hashing function.

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

Configuration

The following parameter can be set in the config file:

  • :log_rounds - the computational cost as number of log rounds
    • the default is 12 (2^12 rounds)

If you are hashing passwords in your tests, it can be useful to add the following to the config/test.exs file:

# Note: Do not use this value in production
config :bcrypt_elixir, log_rounds: 4

Bcrypt

Bcrypt is a key derivation function for passwords designed by Niels Provos and David Mazières. Bcrypt is an adaptive function, which means that it can be configured to remain slow and resistant to brute-force attacks even as computational power increases.

Bcrypt versions

This bcrypt implementation is based on the latest OpenBSD version, which fixed a small issue that affected some passwords longer than 72 characters. By default, it produces hashes with the prefix $2b$, and it can check hashes with either the $2b$ prefix or the older $2a$ prefix. It is also possible to generate hashes with the $2a$ prefix by running the following command:

Bcrypt.Base.hash_password("hard to guess", Bcrypt.Base.gen_salt(12, true))

This option should only be used if you need to generate hashes that are then checked by older libraries.

The $2y$ prefix is not supported. For advice on how to use hashes with the $2y$ prefix, see this issue. Hash the password with a salt which is randomly generated.

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

Link to this function

hash_pwd_salt(password, opts \\ [])

View Source

Hashes a password with a randomly generated salt.

Option

  • :log_rounds - the computational cost as number of log rounds
    • the default is 12 (2^12 rounds)
    • this can be used to override the value set in the config

Examples

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

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

iex> hash = Bcrypt.hash_pwd_salt("password")
...> Bcrypt.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.

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.

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.