mmzeeman / bcrypt

Erlang wrapper for OpenBSD's Blowfish password hashing code

bcrypt

erlang-bcrypt is a wrapper around the OpenBSD Blowfish password hashing algorithm, as described in A Future-Adaptable Password Scheme by Niels Provos and David Mazieres.

This bcrypt repository at erlangpack is in active maintainance and used as the basis of the Hex package.

OTP Compatibility

erlang-bcrypt is compatible with OTP 21.3 to 23.

Use version 1.0.3 on OTP versions before 21.3

In version 1.1.0 support for OTP 21.2 and earlier is removed due to the removal of erl_interface in OTP 23.

Rebar.config

erlang-bcrypt is on Hex:

{deps, [
    {bcrypt, "1.1.3"}
]}.

To use the master branch:

{deps, [
    {bcrypt, {git, ".*", {git, "https://github.com/erlangpack/bcrypt.git", {branch, "master"}}}
]}.

Basic build instructions

1. Build it (project uses rebar3, a Makefile is included):

   make

2. Run it (simple way, starting sasl, crypto and bcrypt):

   $ ./rebar3 shell
   ===> Verifying dependencies...
   ===> Compiling bcrypt
   make: Nothing to be done for `all'.
   Erlang/OTP 23 [erts-11.0] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [hipe]
   
   Eshell V11.0  (abort with ^G)
   1> application:ensure_all_started(bcrypt).
   {ok,[bcrypt]}
   2>     

Basic usage instructions

Hash a password using a salt with the default number of rounds:

1> {ok, Salt} = bcrypt:gen_salt().
{ok,"$2a$12$sSS8Eg.ovVzaHzi1nUHYK."}
2> {ok, Hash} = bcrypt:hashpw("foo", Salt).
{ok,"$2a$12$sSS8Eg.ovVzaHzi1nUHYK.HbUIOdlQI0iS22Q5rd5z.JVVYH6sfm6"}

Verify the password:

3> {ok, Hash} =:= bcrypt:hashpw("foo", Hash).
true
4> {ok, Hash} =:= bcrypt:hashpw("bar", Hash).
false

Configuration

The bcrypt application is configured by changing values in the application's environment:

default_log_rounds Sets the default number of rounds which define the complexity of the hash function. Defaults to 12.

mechanism Specifies whether to use the NIF implementation ('nif') or a pool of port programs ('port'). Defaults to 'nif'.

Note: the NIF implementation no longer blocks the Erlang VM scheduler threads

pool_size Specifies the size of the port program pool. Defaults to 4.

nif_pool_size Specifies the size of the nif program pool. Defaults to 4.

nif_pool_max_overflow Specifies the max workers to overflow of the nif program pool. Defaults to 10.

Run tests

To run the eunit and proper tests use:

make tests

To test all exported function of a module use:

$ ./rebar3 as test shell
===> Verifying dependencies...
===> Compiling bcrypt
make: Nothing to be done for all.
Erlang/OTP 23 [erts-11.0] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [hipe]

Eshell V11.0  (abort with ^G)
1> application:ensure_all_started(bcrypt).
{ok,[bcrypt]}
2>proper:check_specs(bcrypt).            
Testing bcrypt:gen_salt/0
....................................................................................................
OK: Passed 100 test(s).
    
Testing bcrypt:hashpw/2
....................................................................................................
OK: Passed 100 test(s).
    
Testing bcrypt:gen_salt/1
....................................................................................................
OK: Passed 100 test(s).
    
Testing bcrypt:mechanism/0
....................................................................................................
OK: Passed 100 test(s).
    
[]
4> 

Documentation generation

Edoc

Generate public API

rebar3 edoc

Generate private API

rebar3 as edoc_private edoc

ExDoc

rebar3 ex_doc --output edoc

Both the port and the NIF version of bcrypt are tested. All tests should pass.

Original authors

Hunter Morris & Mrinal Wadhwa.