Comeonin

A function that provides options to check the strength of a password before hashing it. The password is then hashed only if the password is considered strong enough. For more details about password strength, read the documentation for the Comeonin.Password module.

The default hashing algorithm is bcrypt, but this can be changed by setting the value of crypto_mod to :pbkdf2 in the config file.

Options

There are two options:

• min_length — minimum allowable length of the password
• extra_chars — check for punctuation characters and digits

The default value for min_length is 8 characters if extra_chars is true, but 12 characters is extra_chars is false. extra_chars is true by default.

Examples

The following examples will produce password hashes:

Comeonin.create_hash("longpassword", [extra_chars: false])

Comeonin.create_hash("passwordwithjustletters", [min_length: 16, extra_chars: false])

This example will raise an error because the password is not long enough for a password with no punctuation characters or digits:

iex> Comeonin.create_hash("password", [extra_chars: false])
{:error, "The password should be at least 12 characters long."}

This last example will raise an error because there are no punctuation characters or digits in it:

iex> Comeonin.create_hash("password")
{:error, "The password should contain at least one number and one punctuation character."}

This function takes a map with a password in it, removes the password and adds an entry for the password hash. This can be used after collecting user data and before adding it to the database.

This uses the create_hash function, which can be used to check password strength before hashing it.

When looking for the password, this function looks for a key which is either named “password” (a string) or :password (an atom). If it does not find either key, it will raise an error.

As with the create_hash function, you can decide not to check password strength by setting the second argument to false.

Examples

All of the following will work ok:

%{"name" => "fred", "password" => "&m@ng0es"} |> Comeonin.create_user

%{name: "fred", password: "&m@ng0es"} |> Comeonin.create_user

%{name: "fred", password: "longpassword"} |> Comeonin.create_user([extra_chars: false])

The next example will raise an error because the key “password” or :password could not be found:

iex> %{["name"] => "fred", ["password", "password_admin"] => "&m@ng0es"} |> Comeonin.create_user
{:error, ~s(We could not find the password. The password key should be either :password or "password".)}

This example will raise an error because the password is not long enough:

iex> %{name: "fred", password: "123456"} |> Comeonin.create_user
{:error, "The password should be at least 8 characters long."}

A function to help the developer decide how many log_rounds to use when using bcrypt.

The number of log_rounds can be increased to make the bcrypt hashing function more complex, and slower. The minimum number is 4 and the maximum is 31. The default is 12, but this is not necessarily the recommended number. The ideal number of log_rounds will depend on the nature of your application and the hardware being used.

The bcrypt_log_rounds value can be set in the config file. See the documentation for Comeonin.Config for more details.

A function to help the developer decide how many rounds to use when using pbkdf2.

The number of rounds can be increased to make the pbkdf2 hashing function slower. The maximum number of rounds is 4294967295. The default is 60_000, but this is not necessarily the recommended number. The ideal number of log_rounds will depend on the nature of your application and the hardware being used.

The pbkdf2_rounds value can be set in the config file. See the documentation for Comeonin.Config for more details.