Comeonin

Password hashing library for Elixir.

This library is intended to make it very straightforward for developers to check users' passwords in as secure a manner as possible.

Comeonin supports Argon2, Bcrypt and Pbkdf2 (sha512 and sha256).

Features

• Comeonin supports the most secure, well-tested, and up-to-date password hashing schemes.
  • Argon2 is the winner of the 2015 Password Hashing Competition.
  • Bcrypt and Pbkdf2 have no known vulnerabilities and have been widely tested for over 15 years.
• It is easy to use.
  • Random salts are generated by default.
  • Each function has sensible, secure defaults.
• It provides excellent documentation.
  • Clear instructions are given on how to use Comeonin.
  • Relevant research is summarized in the documentation and wiki.
    • References are also provided in this section of the wiki.

Changes in version 4

There were several changes in version 4. These are summarized below:

• Added support for Argon2 (as an optional dependency -- argon2_elixir)
• Added higher-level helper functions -- add_hash and check_pass
• Improved the statistics function in each module -- report
• Made all the hashing algorithms optional dependencies
• Moved the configuration to the separate dependency libraries
• Removed support for one-time passwords
  • This is now a separate library - OneTimePassEcto

When upgrading to version 4, you will need to make the following changes:

• Add the algorithm you want to use - Argon2, Bcrypt or Pbkdf2 - to the deps in your mix.exs file (see 2 in Installation below).
• Change any entries in the config to now use the dependency (see 3 in Installation below).

For more information about these changes, see this page.

Installation

1. Decide which algorithm to use (see Choosing an algorithm for more information):

• Argon2 - argon2_elixir
• Bcrypt - bcrypt_elixir
• Pbkdf2 - pbkdf2_elixir

If you choose Argon2 or Bcrypt, you will need to have a C compiler installed.

Argon2 and Bcrypt version 1.0 also require dirty scheduler support, which is provided by default in Erlang 20. Bcrypt version 0.12 can be used with older versions of Erlang.

You do not need to have a C compiler installed to use Pbkdf2.

1. Add comeonin and the library (algorithm) you choose to the deps section of your mix.exs file, as in the following example.

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

1. Optional: during tests (and tests only), you may want to reduce the number of rounds so it does not slow down your test suite. If you have a config/test.exs, you should add (depending on which algorithm you are using):

config :argon2_elixir,
  t_cost: 2,
  m_cost: 12
config :bcrypt_elixir, log_rounds: 4
config :pbkdf2_elixir, rounds: 1

NB: do not use the above values in production.

Problems / build errors

If you have any problems building Comeonin, see the Comeonin wiki.

Use

Each module (Comeonin.Argon2, Comeonin.Bcrypt and Comeonin.Pbkdf2) 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.

Deployment

See the deployment guide.

Documentation

http://hexdocs.pm/comeonin

License

BSD. For full details, please read the LICENSE file.