dbhobbs/comeonin

Password hashing library (bcrypt, pbkdf2_sha512 and one-time passwords) for the Elixir programming language

Comeonin

Password hashing (bcrypt, pbkdf2_sha512 and one-time passwords) 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 bcrypt and pbkdf2_sha512.

Argon2, the winner of the 2015 Password Hashing Competition, is maintained as a separate package. See the Argon2 page in the wiki for more details about Argon2.

Comeonin also supports one-time passwords, for use in two-factor authentication.

Features

• Comeonin uses the most secure, well-tested, and up-to-date hashing schemes.
  • Bcrypt and Pbkdf2 have no known vulnerabilities and have been widely tested for over 10 years
  • Argon2 is maintained as a separate package.
• It uses the latest version of bcrypt, supporting the $2b$ prefix.
• It is easy to use.
  • Salts are generated by default.
  • Each function has sensible, secure defaults.
• It provides excellent documentation.
  • Clear instructions are given on how to use Comeonin.
  • Several recommendations are also given to help developers keep their apps secure.

Requirements and build errors

See the Requirements page in the wiki for details.

Installation

1. Add comeonin to your mix.exs dependencies

defp deps do
  [ {:comeonin, "~> 3.0"} ]
end

2. List :comeonin as an application dependency

def application do
  [applications: [:logger, :comeonin]]
end

3. Run mix do deps.get, compile

4. Optional: during tests (and tests only), you may want to reduce the number of bcrypt, or pbkdf2, 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 :comeonin, :bcrypt_log_rounds, 4
config :comeonin, :pbkdf2_rounds, 1

NB: do not use the above values in production.

Usage

Either import or alias the algorithm you want to use -- either Comeonin.Bcrypt or Comeonin.Pbkdf2.

Both algorithms have the hashpwsalt function, which is a convenience function that automatically generates a salt and then hashes the password.

To hash a password with the default options:

hash = hashpwsalt("difficult2guess")

See each module's documentation for more information about all the available options.

To check a password against the stored hash, use the checkpw function. This takes two arguments: the plaintext password and the stored hash:

checkpw(password, stored_hash)

There is also a dummy_checkpw function, which takes no arguments and is to be used when the username cannot be found. It performs a hash, but then returns false. This can be used to make user enumeration more difficult.

Documentation

http://hexdocs.pm/comeonin

License

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