Hashes a password, using hash_pwd_salt/2, and returns the password hash in a map.

This is a convenience function that is especially useful when used with Ecto changesets.

Options

In addition to the :hash_key option show below, this function also takes options that are then passed on to the hash_pwd_salt/2 function in this module.

See the documentation for hash_pwd_salt/2 for further details.

• :hash_key - the password hash identifier
  • the default is :password_hash

Example with Ecto

The put_pass_hash function below is an example of how you can use add_hash to add the password hash to the Ecto changeset.

defp put_pass_hash(%Ecto.Changeset{valid?: true, changes:
    %{password: password}} = changeset) do
  change(changeset, add_hash(password))
end

defp put_pass_hash(changeset), do: changeset

This function will return a changeset with %{password_hash: password_hash} added to the changes map.

Checks the password, using verify_pass/2, by comparing the hash with the password hash found in a user struct, or map.

This is a convenience function that takes a user struct, or map, as input and seemlessly handles the cases where no user is found.

Options

• :hash_key - the password hash identifier
  • this does not need to be set if the key is :password_hash or :encrypted_password
• :hide_user - run the no_user_verify/1 function if no user is found
  • the default is true

Example

The following is an example of using this function to verify a user's password:

def verify_user(%{"password" => password} = params) do
  params
  |> Accounts.get_by()
  |> check_pass(password)
end

The Accounts.get_by function in this example takes the user parameters (for example, email and password) as input and returns a user struct or nil.

Generate a salt for use with the Bcrypt.Base.hash_password function.

The :log_rounds parameter determines the computational complexity of the generation of the password hash. Its default is 12, the minimum is 4, and the maximum is 31.

The :legacy option is for generating salts with the old $2a$ prefix. Only use this option if you need to generate hashes that are then checked by older libraries.

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

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.

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.