Comeonin v3.2.0 Comeonin.Bcrypt View Source

Module to handle bcrypt authentication.

To generate a password hash, use the hashpwsalt function:

Comeonin.Bcrypt.hashpwsalt("hard to guess")

To check the password against a password hash, use the checkpw function:

Comeonin.Bcrypt.checkpw("hard to guess", stored_hash)

There is also a dummy_checkpw, which can be used to stop an attacker guessing a username by timing the responses.

See the documentation for each function for more details.

Most users will not need to use any of the other functions in this module.

Bcrypt

Bcrypt is a key derivation function for passwords designed by Niels Provos and David Mazières. Bcrypt is an adaptive function, which means that it can be configured to remain slow and resistant to brute-force attacks even as computational power increases.

The computationally intensive code is run in C, using Erlang NIFs. One concern about NIFs is that they block the Erlang VM, and so it is better to make sure these functions do not run for too long. This bcrypt implementation has been adapted so that each NIF runs for as short a time as possible.

Bcrypt versions

This bcrypt implementation is based on the latest OpenBSD version, which fixed a small issue that affected some passwords longer than 72 characters. By default, it produces hashes with the prefix $2b$, and it can check hashes with either the $2b$ prefix or the older $2a$ prefix.

It is also possible to generate hashes with the $2a$ prefix by running the following command:

Comeonin.Bcrypt.hashpass("hard to guess", Comeonin.Bcrypt.gen_salt(12, true))

This option should only be used if you need to generate hashes that are then checked by older libraries.

Link to this section Summary

Functions

Encrypt and return the hash

The main key expansion function

Initialize the P-box and S-box tables with the digits of Pi, and then start the key expansion process

Check the password

Perform a dummy check for a user that does not exist

Generate a salt for use with the hashpass function

Hash the password using bcrypt

Hash the password with a salt which is randomly generated

Link to this section Functions

Encrypt and return the hash.

Link to this function bf_expand0(state, input, input_len) View Source

The main key expansion function.

Link to this function bf_init(key, key_len, salt) View Source

Initialize the P-box and S-box tables with the digits of Pi, and then start the key expansion process.

Check the password.

The check is performed in constant time to avoid timing attacks.

Perform a dummy check for a user that does not exist.

This always returns false. The reason for implementing this check is in order to make user enumeration by timing responses more difficult.

Link to this function gen_salt(log_rounds, legacy \\ false) View Source

Generate a salt for use with the hashpass function.

The log_rounds parameter determines the computational complexity of the generation of the password hash. Its default is 12, the minimum is 4, and the maximum is 31.

The legacy option is for generating salts with the old $2a$ prefix. Only use this option if you need to generate hashes that are then checked by older libraries.

Link to this function hashpass(password, salt) View Source

Hash the password using bcrypt.

In most cases, you will want to use the hashpwsalt function instead. Use this function if you want more control over the generation of the salt.

Hash the password with a salt which is randomly generated.

To change the complexity (and the time taken) of the password hash calculation, you need to change the value for bcrypt_log_rounds in the config file.