12.6 crypt.bcrypt - Password hashing

Don’t use version “2a” for new code. It’s vulnerable.
Use version “2b”.

The typical usage of this module is simple enough.
To get a new password hash value (e.g. for a new user), pass the
password string to bcrypt-hashpw as the only argument:

(bcrypt-hashpw password)
⇒ hashed-string

The routine automatically adds a salt value. The returned hash
string can be stored in the user database. To check if the given
password matches the stored one, pass the
hashed string as the second argument of bcrypt-hashpw to
check the password.

(bcrypt-hashpw passwordhashed-string)
⇒ hashed-string

If the given password is correct, the returned value should
exactly matches hash-string.

Function: bcrypt-hashpwpassword :optional setting

Calculates a hash value of password, using the salt value
and parameters included in setting. If setting is
omitted, a suitable default settings and random salt value is
chosen automatically.

The returned hash value contains the salt value and parameters,
and can be used as setting. So, to check the password
against existing hash value, just pass the hash value to
setting; if the password is correct, the returned hash value
should match the one you passed in.

The bcrypt algorithm supports up to 72 octets for the password.

To tweak parameters when you calculate a new hash value,
use bcrypt-gensalt below to get the initial setting
value.

Function: bcrypt-gensalt:key prefix count entropy-source

Returns a string that contains given parameters and suitable to
pass to the setting argument of bcrypt-hashpw.

The prefix argument specifies the version/scheme of
password hashing. Currently $2a$ and $2b$ are supported,
which means the blowfish algorithm compatible to bcrypt.
But $2a$ is vulnerable. Use $2b$ for new code.
If you omit prefix, use $2b$ for default value.

The count arugment specifies the amount of iterations;
the larger the value is, the more time is required to calculate
the hash value. Note that for the password hashing, taking more
time is actually a good thing, for it works against the dictionary attack.
For normal password checking you need to run the hash routine only
once per login, so it doesn’t matter if the calculation takes a fraction
of second.
The bcrypt algorithm iterates (expt 2 count) times.

The entropy-source argument is a u8vector to feed
a random bytes. For bcrypt algorithm it must be at least 16 octet long.