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


-- | plain-text password and hashed password datatypes and functions
--   
--   A library providing types for working with plain-text and hashed
--   passwords, generally for web applications.
@package password
@version 1.0.0.0


-- | This module provides an easy way for interacting with passwords from
--   Haskell. It provides the types <a>Pass</a> and <a>PassHash</a>, which
--   correspond to plain-text and hashed passwords.
--   
--   It also provides functions for hashing (<a>hashPass</a>) and checking
--   passwords (<a>checkPass</a>).
--   
--   The real benefit of this module is that there is a corresponding
--   <a>password-instances</a> module that provides canonical typeclass
--   instances for <a>Pass</a> and <a>PassHash</a> for many common
--   typeclasses, like <a>FromJSON</a> from <a>aeson</a>,
--   <a>PersistField</a> from <a>persistent</a>, etc.
--   
--   See the <a>password-instances</a> module for more information.
module Data.Password

-- | A plain-text password.
--   
--   This represents a plain-text password that has <i>NOT</i> been hashed.
--   
--   You should be careful with <a>Pass</a>. Make sure not to write it to
--   logs or store it in a database.
--   
--   You can construct a <a>Pass</a> by using the <a>mkPass</a> function or
--   as literal strings together with the OverloadedStrings pragma (or
--   manually, by using <a>fromString</a> on a <a>String</a>).
--   Alternatively, you could also use some of the instances in the
--   <tt>password-instances</tt> library.
data Pass

-- | Construct a <a>Pass</a>
mkPass :: Text -> Pass

-- | A hashed password.
--   
--   This represents a password that has been put through a hashing
--   function. The hashed password can be stored in a database.
newtype PassHash
PassHash :: Text -> PassHash
[unPassHash] :: PassHash -> Text
newtype Salt
Salt :: ByteString -> Salt
[getSalt] :: Salt -> ByteString

-- | Just like <a>hashPassWithSalt</a>, but generate a new <a>Salt</a>
--   everytime with a call to <a>newSalt</a>.
--   
--   <pre>
--   &gt;&gt;&gt; hashPass $ mkPass "foobar"
--   PassHash {unPassHash = "14|8|1|...|..."}
--   </pre>
hashPass :: MonadIO m => Pass -> m PassHash

-- | Hash a password with the given <a>Salt</a>.
--   
--   The resulting <a>PassHash</a> has the parameters used to hash it, as
--   well as the <a>Salt</a> appended to it, separated by <tt>|</tt>.
--   
--   The input <a>Salt</a> and resulting <a>PassHash</a> are both byte-64
--   encoded.
--   
--   <pre>
--   &gt;&gt;&gt; let salt = Salt "abcdefghijklmnopqrstuvwxyz012345"
--   
--   &gt;&gt;&gt; hashPassWithSalt salt (mkPass "foobar")
--   PassHash {unPassHash = "14|8|1|YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU=|nENDaqWBmPKapAqQ3//H0iBImweGjoTqn5SvBS8Mc9FPFbzq6w65maYPZaO+SPamVZRXQjARQ8Y+5rhuDhjIhw=="}
--   </pre>
--   
--   (Note that we use an explicit <a>Salt</a> in the example above. This
--   is so that the example is reproducible, but in general you should use
--   <a>hashPass</a>. <a>hashPass</a> generates a new <a>Salt</a> everytime
--   it is called.)
--   
--   This function uses the hash function from the scrypt package:
--   <a>encryptPass</a>.
hashPassWithSalt :: Salt -> Pass -> PassHash

-- | Generate a random 32-byte salt.
newSalt :: MonadIO m => m Salt

-- | Check a <a>Pass</a> against a <a>PassHash</a>.
--   
--   Returns <a>PassCheckSuccess</a> on success.
--   
--   <pre>
--   &gt;&gt;&gt; let salt = Salt "abcdefghijklmnopqrstuvwxyz012345"
--   
--   &gt;&gt;&gt; let pass = mkPass "foobar"
--   
--   &gt;&gt;&gt; let passHash = hashPassWithSalt salt pass
--   
--   &gt;&gt;&gt; checkPass pass passHash
--   PassCheckSuccess
--   </pre>
--   
--   Returns <a>PassCheckFail</a> If an incorrect <a>Pass</a> or
--   <a>PassHash</a> is used.
--   
--   <pre>
--   &gt;&gt;&gt; let badpass = mkPass "incorrect-password"
--   
--   &gt;&gt;&gt; checkPass badpass passHash
--   PassCheckFail
--   </pre>
--   
--   This should always fail if an incorrect password is given.
--   
--   <pre>
--   \(Blind badpass) -&gt; let correctPassHash = hashPassWithSalt salt "foobar" in checkPass badpass correctPassHash == PassCheckFail
--   </pre>
checkPass :: Pass -> PassHash -> PassCheck

-- | The result of a checking a password against a hashed version. This is
--   returned by <a>checkPass</a>.
data PassCheck

-- | The password check was successful. The plain-text password matches the
--   hashed password.
PassCheckSuccess :: PassCheck

-- | The password check failed. The plain-text password does not match the
--   hashed password.
PassCheckFail :: PassCheck

-- | This is an unsafe function that shows a password in plain-text.
--   
--   <pre>
--   &gt;&gt;&gt; unsafeShowPasswordText $ mkPass "foobar"
--   "foobar"
--   </pre>
--   
--   You should generally not use this function.
unsafeShowPassword :: Pass -> String

-- | This is like <a>unsafeShowPassword</a> but produces a <a>Text</a>
--   instead of a <a>String</a>.
unsafeShowPasswordText :: Pass -> Text
instance GHC.Show.Show Data.Password.PassCheck
instance GHC.Read.Read Data.Password.PassCheck
instance GHC.Classes.Eq Data.Password.PassCheck
instance GHC.Show.Show Data.Password.PassHash
instance GHC.Read.Read Data.Password.PassHash
instance GHC.Classes.Ord Data.Password.PassHash
instance GHC.Classes.Eq Data.Password.PassHash
instance Data.String.IsString Data.Password.Pass
instance GHC.Show.Show Data.Password.Pass