-- 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.4.4


-- | 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|17|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" 17
--   "sha256|12|lMzlNz0XK9eiPIYPY96QCQ==|1ZJ/R3qLEF0oCBVNtvNKLwZLpXPM7bLEy/Nc6QBxWro="
--   </pre>
--   
--   This will hash the password <tt>"hunter2"</tt>, with strength 17,
--   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 16, and 17 is a good
--   default value at the time of this writing, in 2014. OWASP suggests
--   adding 1 to the strength every two years.
--   
--   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.
--   
--   Note that, as of version 2.4, you can also use PBKDF2, and specify the
--   exact iteration count. This does not have a significant effect on
--   security, but can be handy for compatibility with other code.
module Crypto.PasswordStore

-- | PBKDF1 key-derivation function. Takes a password, a <a>Salt</a>, and a
--   number of iterations. The number of iterations should be at least
--   1000, and probably more. 5000 is a reasonable number, computing almost
--   instantaneously. This will give a 32-byte <a>ByteString</a> as output.
--   Both the salt and this 32-byte key should be stored in the password
--   file. When a user wishes to authenticate a password, just pass it and
--   the salt to this function, and see if the output matches.
pbkdf1 :: ByteString -> Salt -> Int -> ByteString

-- | PBKDF2 key-derivation function. For details see
--   <tt><a>http://tools.ietf.org/html/rfc2898</a></tt>. <tt>32</tt> is the
--   most common digest size for <tt>SHA256</tt>, and is what the algorithm
--   internally uses. <tt>HMAC+SHA256</tt> is used as <tt>PRF</tt>, because
--   <tt>HMAC+SHA1</tt> is considered too weak.
pbkdf2 :: ByteString -> Salt -> Int -> ByteString

-- | Hash a password with a given strength (17 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

-- | A generic version of <a>makePassword</a>, which allow the user to
--   choose the algorithm to use.
--   
--   <pre>
--   &gt;&gt;&gt; makePasswordWith pbkdf1 "password" 17
--   </pre>
makePasswordWith :: (ByteString -> Salt -> Int -> ByteString) -> ByteString -> Int -> IO ByteString

-- | Hash a password with a given strength (17 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" (makeSalt "72cd18b5ebfe6e96") 17
--   "sha256|17|NzJjZDE4YjVlYmZlNmU5Ng==|i5VbJNJ3I6SPnxdK5pL0dHw4FoqnHYpSUXp70coXjOI="
--   </pre>
makePasswordSalt :: ByteString -> Salt -> Int -> ByteString

-- | A generic version of <a>makePasswordSalt</a>, meant to give the user
--   the maximum control over the generation parameters. Note that, unlike
--   <a>makePasswordWith</a>, this function takes the <tt>raw</tt> number
--   of iterations. This means the user will need to specify a sensible
--   value, typically <tt>10000</tt> or <tt>20000</tt>.
makePasswordSaltWith :: (ByteString -> Salt -> Int -> ByteString) -> (Int -> Int) -> ByteString -> Salt -> Int -> ByteString

-- | Like <a>verifyPasswordWith</a>, but uses <a>pbkdf1</a> as algorithm.
verifyPassword :: ByteString -> ByteString -> Bool

-- | <a>verifyPasswordWith</a> <tt>algorithm userInput pwHash</tt> verifies
--   the password <tt>userInput</tt> given by the user against the stored
--   password hash <tt>pwHash</tt>, with the hashing algorithm
--   <tt>algorithm</tt>. Returns <a>True</a> if the given password is
--   correct, and <a>False</a> if it is not. This function allows the
--   programmer to specify the algorithm to use, e.g. <a>pbkdf1</a> or
--   <a>pbkdf2</a>. Note: If you want to verify a password previously
--   generated with <a>makePasswordSaltWith</a>, but without modifying the
--   number of iterations, you can do:
--   
--   <pre>
--   &gt;&gt;&gt; verifyPasswordWith pbkdf2 id "hunter2" "sha256..."
--   True
--   </pre>
verifyPasswordWith :: (ByteString -> Salt -> Int -> ByteString) -> (Int -> Int) -> 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

-- | Convert a raw <a>ByteString</a> into a <a>Salt</a>. Use this function
--   with caution, since using a weak salt will result in a weak password.
importSalt :: ByteString -> Salt
instance GHC.Classes.Ord Crypto.PasswordStore.Salt
instance GHC.Classes.Eq Crypto.PasswordStore.Salt
instance GHC.Show.Show Crypto.PasswordStore.Salt
instance Data.Byteable.Byteable [GHC.Types.Char]
