Home

Comeonin is a password hashing library that aims to make the secure validation of passwords as straightforward as possible.

It also provides extensive documentation to help developers keep their apps secure.

Comeonin supports Argon2, Bcrypt and Pbkdf2 (sha512 and sha256). These are all supported as optional dependencies.

Installation

First, you need to decide which algorithm to use (see the Choosing an algorithm section for more information about each algorithm):

* Argon2 - [argon2_elixir](https://github.com/riverrun/argon2_elixir)
* Bcrypt - [bcrypt_elixir](https://github.com/riverrun/bcrypt_elixir)
* Pbkdf2 - [pbkdf2_elixir](https://github.com/riverrun/pbkdf2_elixir)

If you choose Argon2 or Bcrypt, you will need to have a C compiler installed. Argon2 also requires dirty scheduler support, which is provided by default in Erlang 20. You do not need to have a C compiler installed to use Pbkdf2.

Then add comeonin and the library you choose to the deps section of your mix.exs file, as in the following example.

  defp deps do
    [
      {:comeonin, "~> 4.0-rc"},
      {:argon2_elixir, "~> 1.2"},
    ]
  end

Use

Each module offers the following functions (the first two are new to version 4):

* add_hash - hash a password and return it in a map with the password set to nil
* check_pass - check a password by comparing it with the stored hash, which is in a map
* hashpwsalt - hash a password, using a randomly generated salt
* checkpw - check a password by comparing it with the stored hash
* dummy_checkpw - perform a dummy check to make user enumeration more difficult
* report - print out a report of the hashing algorithm, to help with configuration

For a lower-level API, you could also use the hashing dependency directly, without installing Comeonin.

Problems / build issues

See the requirements page for more information.

Build errors after upgrading Elixir / Erlang

After upgrading the Elixir / Erlang version, you may need to rebuild the Bcrypt shared object file. To do so, run the following command (on Linux or Mac OS X):

(cd deps/comeonin && make clean && make)

References / further information

This page provides more information about research into password hashes, as well as other relevant research.