# Comeonin

Password authorization (bcrypt, pbkdf2_sha512) library for Elixir.

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

At the moment, Comeonin only supports `bcrypt`, but in the near future
it will also support `pbkdf2_sha512`.


* Comeonin uses the most secure, up-to-date hashing schemes.
* It is easy to use.
    * There are several convenience functions to make authorizing users easier.
    * Salts are generated by default.
    * Each function has sensible, secure defaults.
* It provides good documentation.


1. Add comeonin to your `mix.exs` dependencies

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

2. List `:comeonin` as an application dependency

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

3. Run `mix do deps.get, compile`

## Usage

There are functions to generate a salt `Comeonin.Bcrypt.gen_salt`
and then use that salt to hash a password `Comeonin.Bcrypt.hashpw`, but there are
also the following three convenience functions (with examples):

* hashpwsalt -- generate a salt and then use that salt to hash a password

  hash = Comeonin.hashpwsalt("hard2guess")

* checkpw -- check the password against the stored hash

  Comeonin.checkpw("hard2guess", stored_hash)

* dummy_checkpw -- calculate a hash and return false


This last function is to be used when the username cannot be found.
It is to prevent a potential attacker enumerating the users by timing
the responses.

## Documentation

## Status

The bcrypt implementation is based on the latest OpenBSD version, which
fixed a small issue that affected some passwords longer than 72 characters.
It has been thoroughly tested in a development environment, but it has
not had much testing in production. In addition, it has only been tested
on Linux.

## License

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