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


-- | Secure password storage.
--   
--   To store passwords securely, they should be salted, then hashed with a
--   slow hash function. This library uses PBKDF1-SHA256, and handles all
--   the details. It uses the cryptohash package for speed; if you need a
--   pure Haskell library, pwstore-purehaskell has the exact same API, but
--   uses only pure Haskell. It is about 25 times slower than this package,
--   but still quite usable.
@package pwstore-fast
@version 2.3


-- | Securely store hashed, salted passwords. If you need to store and
--   verify passwords, there are many wrong ways to do it, most of them all
--   too common. Some people store users' passwords in plain text. Then,
--   when an attacker manages to get their hands on this file, they have
--   the passwords for every user's account. One step up, but still wrong,
--   is to simply hash all passwords with SHA1 or something. This is
--   vulnerable to rainbow table and dictionary attacks. One step up from
--   that is to hash the password along with a unique salt value. This is
--   vulnerable to dictionary attacks, since guessing a password is very
--   fast. The right thing to do is to use a slow hash function, to add
--   some small but significant delay, that will be negligible for
--   legitimate users but prohibitively expensive for someone trying to
--   guess passwords by brute force. That is what this library does. It
--   iterates a SHA256 hash, with a random salt, a few thousand times. This
--   scheme is known as PBKDF1, and is generally considered secure; there
--   is nothing innovative happening here.
--   
--   The API here is very simple. What you store are called <i>password
--   hashes</i>. They are strings (technically, ByteStrings) that look like
--   this:
--   
--   <pre>
--   "sha256|12|Ge9pg8a/r4JW356Uux2JHg==|Fdv4jchzDlRAs6WFNUarxLngaittknbaHFFc0k8hAy0="
--   </pre>
--   
--   Each password hash shows the algorithm, the strength (more on that
--   later), the salt, and the hashed-and-salted password. You store these
--   on your server, in a database, for when you need to verify a password.
--   You make a password hash with the <a>makePassword</a> function. Here's
--   an example:
--   
--   <pre>
--   &gt;&gt;&gt; makePassword "hunter2" 12
--   "sha256|12|lMzlNz0XK9eiPIYPY96QCQ==|1ZJ/R3qLEF0oCBVNtvNKLwZLpXPM7bLEy/Nc6QBxWro="
--   </pre>
--   
--   This will hash the password <tt>"hunter2"</tt>, with strength 12,
--   which is a good default value. The strength here determines how long
--   the hashing will take. When doing the hashing, we iterate the SHA256
--   hash function <tt>2^strength</tt> times, so increasing the strength by
--   1 makes the hashing take twice as long. When computers get faster, you
--   can bump up the strength a little bit to compensate. You can
--   strengthen existing password hashes with the <a>strengthenPassword</a>
--   function. Note that <a>makePassword</a> needs to generate random
--   numbers, so its return type is <a>IO</a> <a>ByteString</a>. If you
--   want to avoid the <a>IO</a> monad, you can generate your own salt and
--   pass it to <a>makePasswordSalt</a>.
--   
--   Your strength value should not be less than 10, and 12 is a good
--   default value at the time of this writing, in 2011.
--   
--   Once you've got your password hashes, the second big thing you need to
--   do with them is verify passwords against them. When a user gives you a
--   password, you compare it with a password hash using the
--   <a>verifyPassword</a> function:
--   
--   <pre>
--   &gt;&gt;&gt; verifyPassword "wrong guess" passwordHash
--   False
--   &gt;&gt;&gt; verifyPassword "hunter2" passwordHash
--   True
--   </pre>
--   
--   These two functions are really all you need. If you want to make
--   existing password hashes stronger, you can use
--   <a>strengthenPassword</a>. Just pass it an existing password hash and
--   a new strength value, and it will return a new password hash with that
--   strength value, which will match the same password as the old password
--   hash.
module Crypto.PasswordStore

-- | Hash a password with a given strength (12 is a good default). The
--   output of this function can be written directly to a password file or
--   database. Generates a salt using high-quality randomness from
--   <tt>/dev/urandom</tt> or (if that is not available, for example on
--   Windows) <a>Random</a>, which is included in the hashed output.
makePassword :: ByteString -> Int -> IO ByteString

-- | Hash a password with a given strength (12 is a good default), using a
--   given salt. The output of this function can be written directly to a
--   password file or database. Example:
--   
--   <pre>
--   &gt;&gt;&gt; makePasswordSalt "hunter2" "72cd18b5ebfe6e96" 12
--   "sha256|12|72cd18b5ebfe6e96|Xkki10Vus/a2SN/LgCVLTT5R30lvHSCCxH6QboV+U3E="
--   </pre>
makePasswordSalt :: ByteString -> Salt -> Int -> ByteString

-- | <tt>verifyPassword userInput pwHash</tt> verifies the password
--   <tt>userInput</tt> given by the user against the stored password hash
--   <tt>pwHash</tt>. Returns <a>True</a> if the given password is correct,
--   and <a>False</a> if it is not.
verifyPassword :: ByteString -> ByteString -> Bool

-- | Try to strengthen a password hash, by hashing it some more times.
--   <tt><a>strengthenPassword</a> pwHash new_strength</tt> will return a
--   new password hash with strength at least <tt>new_strength</tt>. If the
--   password hash already has strength greater than or equal to
--   <tt>new_strength</tt>, then it is returned unmodified. If the password
--   hash is invalid and does not parse, it will be returned without
--   comment.
--   
--   This function can be used to periodically update your password
--   database when computers get faster, in order to keep up with Moore's
--   law. This isn't hugely important, but it's a good idea.
strengthenPassword :: ByteString -> Int -> ByteString

-- | Return the strength of a password hash.
passwordStrength :: ByteString -> Int

-- | A salt is a unique random value which is stored as part of the
--   password hash. You can generate a salt with <a>genSaltIO</a> or
--   <a>genSaltRandom</a>, or if you really know what you're doing, you can
--   create them from your own ByteString values with <a>makeSalt</a>.
data Salt

-- | Is the format of a password hash valid? Attempts to parse a given
--   password hash. Returns <a>True</a> if it parses correctly, and
--   <a>False</a> otherwise.
isPasswordFormatValid :: ByteString -> Bool

-- | Generate a <a>Salt</a> from 128 bits of data from
--   <tt>/dev/urandom</tt>, with the system RNG as a fallback. This is the
--   function used to generate salts by <a>makePassword</a>.
genSaltIO :: IO Salt

-- | Generate a <a>Salt</a> with 128 bits of data taken from a given random
--   number generator. Returns the salt and the updated random number
--   generator. This is meant to be used with <a>makePasswordSalt</a> by
--   people who would prefer to either use their own random number
--   generator or avoid the <a>IO</a> monad.
genSaltRandom :: RandomGen b => b -> (Salt, b)

-- | Create a <a>Salt</a> from a <a>ByteString</a>. The input must be at
--   least 8 characters, and can contain arbitrary bytes. Most users will
--   not need to use this function.
makeSalt :: ByteString -> Salt

-- | Convert a <a>Salt</a> into a <a>ByteString</a>. The resulting
--   <a>ByteString</a> will be base64-encoded. Most users will not need to
--   use this function.
exportSalt :: Salt -> ByteString
instance Show Salt
instance Eq Salt
instance Ord Salt
