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


-- | Haskell bindings to libargon2 - the reference implementation of the Argon2 password-hashing function
--   
--   Haskell bindings to libargon2 - the reference implementation of the
--   Argon2 password-hashing function
@package argon2
@version 1.2.0

module Crypto.Argon2.FFI
argon2i_hash_encoded :: (Word32) -> (Word32) -> (Word32) -> Ptr a -> CSize -> Ptr b -> CSize -> CSize -> CString -> CSize -> IO (Int32)
argon2i_hash_raw :: (Word32) -> (Word32) -> (Word32) -> Ptr a -> CSize -> Ptr b -> CSize -> Ptr c -> CSize -> IO (Int32)
argon2d_hash_encoded :: (Word32) -> (Word32) -> (Word32) -> Ptr a -> CSize -> Ptr b -> CSize -> CSize -> CString -> CSize -> IO (Int32)
argon2d_hash_raw :: (Word32) -> (Word32) -> (Word32) -> Ptr a -> CSize -> Ptr b -> CSize -> Ptr c -> CSize -> IO (Int32)
argon2i_verify :: CString -> Ptr a -> CSize -> IO (Int32)
argon2d_verify :: CString -> Ptr a -> CSize -> IO (Int32)
argon2_encodedlen :: (Word32) -> (Word32) -> (Word32) -> (Word32) -> (Word32) -> IO CSize


-- | <a>Crypto.Argon2</a> provides bindings to the <a>reference
--   implementation</a> of Argon2, the password-hashing function that won
--   the <a>Password Hashing Competition (PHC)</a>.
--   
--   The main entry points to this module are <a>hashEncoded</a>, which
--   produces a crypt-like ASCII output; and <a>hash</a> which produces a
--   <a>ByteString</a> (a stream of bytes). Argon2 is a configurable hash
--   function, and can be configured by supplying a particular set of
--   <a>HashOptions</a> - <a>defaultHashOptions</a> should provide a good
--   starting point. See <a>HashOptions</a> for more documentation on the
--   particular parameters that can be adjusted.
--   
--   For access directly to the C interface, see <a>Crypto.Argon2.FFI</a>.
module Crypto.Argon2

-- | Encode a password with a given salt and <a>HashOptions</a> and produce
--   a textual encoding of the result.
hashEncoded :: HashOptions -> ByteString -> ByteString -> Text

-- | Encode a password with a given salt and <a>HashOptions</a> and produce
--   a stream of bytes.
hash :: HashOptions -> ByteString -> ByteString -> ByteString

-- | Verify that a given password could result in a given hash output.
--   Automatically determines the correct <a>HashOptions</a> based on the
--   encoded hash (as produced by <a>hashEncoded</a>).
verify :: Text -> ByteString -> Bool

-- | Parameters that can be adjusted to change the runtime performance of
--   the hashing.
data HashOptions
HashOptions :: !Word32 -> !Word32 -> !Word32 -> !Argon2Variant -> HashOptions

-- | The time cost, which defines the amount of computation realized and
--   therefore the execution time, given in number of iterations.
--   
--   <a>ARGON2_MIN_TIME</a> &lt;= <a>hashIterations</a> &lt;=
--   <a>ARGON2_MAX_TIME</a>
[hashIterations] :: HashOptions -> !Word32

-- | The memory cost, which defines the memory usage, given in kibibytes.
--   
--   max <a>ARGON2_MIN_MEMORY</a> (8 * <a>hashParallelism</a>) &lt;=
--   <a>hashMemory</a> &lt;= <a>ARGON2_MAX_MEMORY</a>
[hashMemory] :: HashOptions -> !Word32

-- | A parallelism degree, which defines the number of parallel threads.
--   
--   <a>ARGON2_MIN_LANES</a> &lt;= <a>hashParallelism</a> &lt;=
--   <a>ARGON2_MAX_LANES</a> &amp;&amp; <a>ARGON_MIN_THREADS</a> &lt;=
--   <a>hashParallelism</a> &lt;= <a>ARGON2_MAX_THREADS</a>
[hashParallelism] :: HashOptions -> !Word32

-- | Which version of Argon2 to use.
[hashVariant] :: HashOptions -> !Argon2Variant

-- | Which variant of Argon2 to use. You should choose the variant that is
--   most applicable to your intention to hash inputs.
data Argon2Variant

-- | Argon2i uses data-independent memory access, which is preferred for
--   password hashing and password-based key derivation. Argon2i is slower
--   as it makes more passes over the memory to protect from tradeoff
--   attacks.
Argon2i :: Argon2Variant

-- | Argon2d is faster and uses data-depending memory access, which makes
--   it suitable for cryptocurrencies and applications with no threats from
--   side-channel timing attacks.
Argon2d :: Argon2Variant

-- | A set of default <a>HashOptions</a>, taken from the <tt>argon2</tt>
--   executable.
--   
--   <pre>
--   <a>defaultHashOptions</a> :: <a>HashOptions</a>
--   <a>defaultHashOptions</a> =
--     <a>HashOptions</a> {<a>hashIterations</a> = 1
--                 ,<a>hashMemory</a> = 2 ^ 17
--                 ,<a>hashParallelism</a> = 4
--                 ,<a>hashVariant</a> = <a>Argon2i</a>}
--   </pre>
defaultHashOptions :: HashOptions

-- | Not all <a>HashOptions</a> can necessarily be used to compute hashes.
--   If you supply invalid <a>HashOptions</a> (or hashing otherwise fails)
--   a <a>Argon2Exception</a> will be throw.
data Argon2Exception

-- | The length of the supplied password is outside the range supported by
--   <tt>libargon2</tt>.
Argon2PasswordLengthOutOfRange :: !CSize -> Argon2Exception

-- | The length of the supplied salt is outside the range supported by
--   <tt>libargon2</tt>.
Argon2SaltLengthOutOfRange :: !CSize -> Argon2Exception

-- | Either too much or too little memory was requested via
--   <a>hashMemory</a>.
Argon2MemoryUseOutOfRange :: !Word32 -> Argon2Exception

-- | Either too few or too many iterations were requested via
--   <a>hashIterations</a>.
Argon2IterationCountOutOfRange :: !Word32 -> Argon2Exception

-- | Either too much or too little parallelism was requested via
--   <tt>hasParallelism</tt>.
Argon2ParallelismOutOfRange :: !Word32 -> Argon2Exception

-- | An unexpected exception was throw. Please <a>report this as a bug</a>!
Argon2Exception :: !Int32 -> Argon2Exception
instance GHC.Show.Show Crypto.Argon2.Argon2Exception
instance GHC.Generics.Generic Crypto.Argon2.HashOptions
instance GHC.Enum.Bounded Crypto.Argon2.HashOptions
instance GHC.Show.Show Crypto.Argon2.HashOptions
instance GHC.Read.Read Crypto.Argon2.HashOptions
instance GHC.Classes.Ord Crypto.Argon2.HashOptions
instance GHC.Classes.Eq Crypto.Argon2.HashOptions
instance GHC.Enum.Enum Crypto.Argon2.Argon2Variant
instance GHC.Generics.Generic Crypto.Argon2.Argon2Variant
instance GHC.Enum.Bounded Crypto.Argon2.Argon2Variant
instance GHC.Show.Show Crypto.Argon2.Argon2Variant
instance GHC.Read.Read Crypto.Argon2.Argon2Variant
instance GHC.Classes.Ord Crypto.Argon2.Argon2Variant
instance GHC.Classes.Eq Crypto.Argon2.Argon2Variant
instance GHC.Exception.Exception Crypto.Argon2.Argon2Exception
