12.13 crypt.bcrypt - Password hashing

Module: crypt.bcrypt ¶

This module implements a password hashing algorithm using blowfish, and compatible to OpenBSD’s bcrypt algorithm (version 2a, 2b).

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 password hashed-string)
  ⇒ hashed-string

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

Function: bcrypt-hashpw password :optional setting ¶

{crypt.bcrypt} 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 ¶

{crypt.bcrypt} 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 argument 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.