Crypto.BCrypt

A module for hashing passwords with bcrypt.

>>> import Crypto.BCrypt
>>> let p = Data.ByteString.Char8.pack
>>> hashPasswordUsingPolicy slowerBcryptHashingPolicy (p "mypassword")
Just "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6"
>>> validatePassword (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6") (p "badpass")
False
>>> validatePassword (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6") (p "mypassword")
True
>>> hashUsesPolicy slowerBcryptHashingPolicy (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6")
True
>>> hashUsesPolicy fastBcryptHashingPolicy (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6")
False

Documentation

data HashingPolicy

A hashing policy defines the type of password hashing to use.

Constructors

HashingPolicy

Fields

preferredHashCost :: Int

Preferred cost - how strong new passwords should be. This is a trade-off between making hasing / checking passwords faster in your system, and making brute forcing passwords harder for an adversary. The intention is that this can be increased as computers get faster. To give a rough indication of the scale of preferredCost, on a 2.6 GHz AMD Athlon machine (64 bit kernel), using a single core:

• Cost 4: 139 passwords / second

  • Cost 5: 85 passwords / second
  • Cost 6: 44 passwords / second
  • Cost 7: 23 passwords / second
  • Cost 8: 11 passwords / second
  • Cost 9: 5.7 passwords / second
  • Cost 10: 2.8 passwords / second
  • Cost 11: 1.4 passwords / second
  • Cost 12: 0.72 passwords / second

preferredHashAlgorithm :: ByteString

Preferred algorithm - the preferred hash algorithm. The default is $2y$ (compatible with other Openwall-based libraries). The most up-to-date version is $2b$.

hashPasswordUsingPolicy :: HashingPolicy -> ByteString -> IO (Maybe ByteString)

Hashes a password, using a hashing policy.

validatePassword :: ByteString -> ByteString -> Bool

Validates a password. The first argument is the hashed password, the second is the password attempt. Note: If a password validates successfully, it is a good idea to check if the password is up to the current policy using hashUsesPolicy, and re-hashing it if not.

fastBcryptHashingPolicy :: HashingPolicy

A policy that allows passwords to be hashed reasonably quickly, but for that reason isn't suitable for high security applications.

slowerBcryptHashingPolicy :: HashingPolicy

A policy which makes password hashing substantially slower than fastBcryptHashingPolicy, and so makes it more difficult for an adversary to decrypt passwords. In a high security environment, this policy should be regularly reviewed against hardware developments.

hashUsesPolicy :: HashingPolicy -> ByteString -> Bool

Check whether a password hash is consistent with the current policy, or if it should be updated.

hashPassword :: ByteString -> ByteString -> Maybe ByteString

Hashes a password (first argument) using the settings specified in second argument. The settings describe the hashing variant and salt to use; because the settings are prepended to password hashes, passing in an existing password hash will cause the same settings to be used again. You can create a hash using genSalt. Result: Just hash on success, Nothing on failure (invalid settings).

genSalt :: ByteString -> Int -> ByteString -> Maybe ByteString

Prepares a settings string and salt suitable for use with hashPassword. Takes a prefix specifying the type of hash, an integer specifying the computational cost of hashing (4-32, or 0 for a low default), and a string of random entropy.

genSaltUsingPolicy :: HashingPolicy -> IO (Maybe ByteString)

Generates a salt using a policy, sampling from a system-appropriate source.