-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Haskell bindings to the bcrypt password hash
--   
--   Haskell bindings to the bcrypt password hash. Unlike other bindings
--   already in existence, this package is designed to allow users to work
--   directly with password hash strings that include information about the
--   hashing algorithm, strength, and salt. This approach allows hashed
--   passwords to be stored in a single field that can also be used by
--   non-Haskell applications, and makes it easy to implement a policy of
--   updating passwords hashed to an old policy next time the plaintext
--   password is available. The OpenWall version of the C source for bcrypt
--   (modified so it will build on all platforms without any assembler
--   code) is included in this package.
@package bcrypt
@version 0.0.4


-- | A module for hashing passwords with bcrypt.
--   
--   <pre>
--   &gt;&gt;&gt; import Crypto.BCrypt
--   
--   &gt;&gt;&gt; let p = Data.ByteString.Char8.pack
--   
--   &gt;&gt;&gt; hashPasswordUsingPolicy slowerBcryptHashingPolicy (p "mypassword")
--   Just "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6"
--   
--   &gt;&gt;&gt; validatePassword (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6") (p "badpass")
--   False
--   
--   &gt;&gt;&gt; validatePassword (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6") (p "mypassword")
--   True
--   
--   &gt;&gt;&gt; hashUsesPolicy slowerBcryptHashingPolicy (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6")
--   True
--   
--   &gt;&gt;&gt; hashUsesPolicy fastBcryptHashingPolicy (p "$2y$14$xBBZdWgTa8fSU1aPFP5IxeVdUKfT7hUDjmusZEAiNBiYaYEGY/Sh6")
--   False
--   </pre>
module Crypto.BCrypt

-- | A hashing policy defines the type of password hashing to use.
data HashingPolicy
HashingPolicy :: Int -> ByteString -> HashingPolicy

-- | 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:
--   
--   <ul>
--   <li>Cost 4: 139 passwords / second</li>
--   <li>Cost 5: 85 passwords / second</li>
--   <li>Cost 6: 44 passwords / second</li>
--   <li>Cost 7: 23 passwords / second</li>
--   <li>Cost 8: 11 passwords / second</li>
--   <li>Cost 9: 5.7 passwords / second</li>
--   <li>Cost 10: 2.8 passwords / second</li>
--   <li>Cost 11: 1.4 passwords / second</li>
--   <li>Cost 12: 0.72 passwords / second</li>
--   </ul>
preferredHashCost :: HashingPolicy -> Int

-- | Preferred algorithm - the preferred hash algorithm. $2y$ for bcrypt.
preferredHashAlgorithm :: HashingPolicy -> ByteString

-- | Hashes a password, using a hashing policy.
hashPasswordUsingPolicy :: HashingPolicy -> ByteString -> IO (Maybe ByteString)

-- | 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.
validatePassword :: ByteString -> ByteString -> Bool

-- | A policy that allows passwords to be hashed reasonably quickly, but
--   for that reason isn't suitable for high security applications.
fastBcryptHashingPolicy :: 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.
slowerBcryptHashingPolicy :: HashingPolicy

-- | Check whether a password hash is consistent with the current policy,
--   or if it should be updated.
hashUsesPolicy :: HashingPolicy -> ByteString -> Bool

-- | 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).
hashPassword :: ByteString -> 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.
genSalt :: ByteString -> Int -> ByteString -> Maybe ByteString

-- | Generates a salt using a policy, sampling from a system-appropriate
--   source.
genSaltUsingPolicy :: HashingPolicy -> IO (Maybe ByteString)