Comeonin v4.0.0-rc.0 Comeonin.Pbkdf2 View Source

Password hashing module using the Pbkdf2 algorithm.

For more information about the Pbkdf2 algorithm, see the Choosing an algorithm section in the Comeonin docs.

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

Link to this section Summary

Functions

Hash a password and return it in a map, with the password set to nil

Check the password by comparing its hash with the password hash found in a user struct, or map

Check the password by comparing it with the stored hash

Run a dummy check, which always returns false, to make user enumeration more difficult

Hash the password with a randomly-generated salt

Print out a report to help you configure the hash function

Link to this section Functions

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

Hash a password and return it in a map, with the password set to nil.

Options

This function uses Pbkdf2.hash_pwd_salt as the hashing function. In addition to the options for hash_pwd_salt, there is also the following option:

  • hash_key - the name of the key for the password hash

    • the default is :password_hash

Examples

In the following example, this function is used with an Ecto changeset:

defp put_pass_hash(%Ecto.Changeset{valid?: true, changes:
    %{password: password}} = changeset) do
  change(changeset, Comeonin.Pbkdf2.add_hash(password))
end
defp put_pass_hash(changeset), do: changeset
Link to this function check_pass(user, password, opts \\ []) View Source

Check the password by comparing its hash with the password hash found in a user struct, or map.

The password hash’s key needs to be either :password_hash or :encrypted_password.

After finding the password hash in the user struct, the password is checked by comparing it with the hash. Then the function returns {:ok, user} or {:error, message}. Note that the error message is meant to be used for logging purposes only; it should not be passed on to the end user.

If the first argument is nil, meaning that there is no user with that name, a dummy verify function is run to make user enumeration, using timing information, more difficult. This can be disabled by adding hide_user: false to the opts.

Examples

The following is a simple example using Phoenix 1.3:

def verify(attrs) do
  MyApp.Accounts.get_by(attrs)
  |> Comeonin.Pbkdf2.check_pass(password)
end

Check the password by comparing it with the stored hash.

For more details, see the documentation for Pbkdf2.verify_pass.

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

Run a dummy check, which always returns false, to make user enumeration more difficult.

For more details, see the documentation for Pbkdf2.no_user_verify.

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

Hash the password with a randomly-generated salt.

For more details, see the documentation for Pbkdf2.hash_pwd_salt and Pbkdf2.Base.hash_password.

Print out a report to help you configure the hash function.

For more details, see the documentation for Pbkdf2.Stats.report.