-- 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.
--   
--   Version 1.1.3 of the OpenWall C source for bcrypt is included in this
--   package (<a>http://www.openwall.com/crypt/</a>). The only modification
--   is that the flag which enables the use of assembler has been disabled.
--   Announcements about hs-bcrypt (including security announcements) will
--   be sent to
--   <a>https://groups.google.com/forum/#!forum/hs-bcrypt-announce/join</a>
--   - if you use this library please consider subscribing. This mailing
--   list is moderated and is expected to have a very low volume of mail
--   traffic.
@package bcrypt
@version 0.0.8


-- | 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. The default is
--   $2y$ (compatible with other Openwall-based libraries). The most
--   up-to-date version is $2b$.
[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)