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


-- | Memory-hard password hash and proof-of-work function
--   
--   Argon2 is the key derivation function (KDF) selected as the winner of
--   the <a>Password Hashing Competition</a>. The API exposed by this
--   bindings provide access to the 3 specified variants
--   
--   <ul>
--   <li><tt>Argon2d</tt> (maximize resistance to GPU cracking
--   attacks),</li>
--   <li><tt>Argon2i</tt> (optimized to resist side-channel attacks),
--   and</li>
--   <li><tt>Argon2id</tt> (hybrid version combining <tt>Argon2d</tt> and
--   <tt>Argon2i</tt>)</li>
--   </ul>
--   
--   and allows to control various parameters (time cost, memory cost,
--   parallelism) of the Argon2 function. Moreover, it is also supported to
--   generate and verify the deprecated version 1.0 hashes, as well as the
--   current version 1.3 hashes.
--   
--   The Haskell API supports both raw binary hashes as well as the
--   ASCII-based <a>PHC string format</a>.
--   
--   This version provides bindings to the "<tt>20171227</tt>" release of
--   the <a>Argon2 reference implementation (libargon2)</a> of the Argon2
--   password-hashing function.
--   
--   Please refer to the <a>Argon2 specification</a> for more information.
@package argon2
@version 1.3.0.1


-- | This module provides low-level access to parts of the C API
--   
--   Prefer the <a>Crypto.Argon2</a> API when possible.
module Crypto.Argon2.FFI

-- | Compute Argon2 hash
--   
--   <pre>
--   int argon2_hash(const uint32_t t_cost, const uint32_t m_cost,
--                   const uint32_t parallelism, const void *pwd,
--                   const size_t pwdlen, const void *salt,
--                   const size_t saltlen, void *hash,
--                   const size_t hashlen, char *encoded,
--                   const size_t encodedlen, argon2_type type,
--                   const uint32_t version);
--   </pre>
--   
--   <h3><b>Parameters</b></h3>
--   
--   <ul>
--   <li><i>t_cost</i> Number of iterations</li>
--   <li><i>m_cost</i> Sets memory usage to m_cost kibibytes</li>
--   <li><i>parallelism</i> Number of threads and compute lanes</li>
--   <li><i>pwd</i> Pointer to password</li>
--   <li><i>pwdlen</i> Password size in bytes</li>
--   <li><i>salt</i> Pointer to salt</li>
--   <li><i>saltlen</i> Salt size in bytes</li>
--   <li><i>hash</i> Buffer where to write the raw hash</li>
--   <li><i>hashlen</i> Desired length of the hash in bytes</li>
--   <li><i>encoded</i> Buffer where to write the encoded hash</li>
--   <li><i>encodedlen</i> Size of the buffer (thus max size of the encoded
--   hash)</li>
--   <li><i>type</i> Variant of Argon2 hash</li>
--   <li><i>version</i> Version of Argon2 specification</li>
--   </ul>
argon2_hash :: Word32 -> Word32 -> Word32 -> Ptr a -> CSize -> Ptr b -> CSize -> Ptr c -> CSize -> CString -> CSize -> Argon2_type -> Argon2_version -> IO CInt

-- | Verify encoded hash
--   
--   <pre>
--   int argon2_verify(const char *encoded, const void *pwd,
--                     const size_t pwdlen, argon2_type type);
--   </pre>
--   
--   <h3><b>Parameters</b></h3>
--   
--   <ul>
--   <li><i>encoded</i> Pointer to zero-terminated encoded hash</li>
--   <li><i>pwd</i> Pointer to password</li>
--   <li><i>pwdlen</i> Password size in bytes</li>
--   <li><i>type</i> Variant of Argon2 hash</li>
--   </ul>
argon2_verify :: CString -> Ptr a -> CSize -> Argon2_type -> IO CInt

-- | Compute size of encoded hash
--   
--   <pre>
--   size_t argon2_encodedlen(uint32_t t_cost, uint32_t m_cost, uint32_t parallelism,
--                            uint32_t saltlen, uint32_t hashlen, argon2_type type);
--   </pre>
--   
--   <h3><b>Parameters</b></h3>
--   
--   <ul>
--   <li><i>t_cost</i> Number of iterations</li>
--   <li><i>m_cost</i> Sets memory usage to m_cost kibibytes</li>
--   <li><i>parallelism</i> Number of threads and compute lanes</li>
--   <li><i>salt</i> Pointer to salt</li>
--   <li><i>saltlen</i> Salt size in bytes</li>
--   <li><i>hashlen</i> Desired length of the hash in bytes</li>
--   <li><i>type</i> Variant of Argon2 hash</li>
--   </ul>
argon2_encodedlen :: Word32 -> Word32 -> Word32 -> Word32 -> Word32 -> Argon2_type -> CSize
type Argon2_type = (Word32)
pattern Argon2_d :: (Eq a, Num a) => a
pattern Argon2_i :: (Eq a, Num a) => a
pattern Argon2_id :: (Eq a, Num a) => a
type Argon2_version = Word32
pattern ARGON2_VERSION_10 :: (Eq a, Num a) => a
pattern ARGON2_VERSION_13 :: (Eq a, Num a) => a
pattern ARGON2_VERSION_NUMBER :: (Eq a, Num a) => a
pattern ARGON2_OK :: (Eq a, Num a) => a
pattern ARGON2_OUTPUT_PTR_NULL :: (Eq a, Num a) => a
pattern ARGON2_OUTPUT_TOO_SHORT :: (Eq a, Num a) => a
pattern ARGON2_OUTPUT_TOO_LONG :: (Eq a, Num a) => a
pattern ARGON2_PWD_TOO_SHORT :: (Eq a, Num a) => a
pattern ARGON2_PWD_TOO_LONG :: (Eq a, Num a) => a
pattern ARGON2_SALT_TOO_SHORT :: (Eq a, Num a) => a
pattern ARGON2_SALT_TOO_LONG :: (Eq a, Num a) => a
pattern ARGON2_AD_TOO_SHORT :: (Eq a, Num a) => a
pattern ARGON2_AD_TOO_LONG :: (Eq a, Num a) => a
pattern ARGON2_SECRET_TOO_SHORT :: (Eq a, Num a) => a
pattern ARGON2_SECRET_TOO_LONG :: (Eq a, Num a) => a
pattern ARGON2_TIME_TOO_SMALL :: (Eq a, Num a) => a
pattern ARGON2_TIME_TOO_LARGE :: (Eq a, Num a) => a
pattern ARGON2_MEMORY_TOO_LITTLE :: (Eq a, Num a) => a
pattern ARGON2_MEMORY_TOO_MUCH :: (Eq a, Num a) => a
pattern ARGON2_LANES_TOO_FEW :: (Eq a, Num a) => a
pattern ARGON2_LANES_TOO_MANY :: (Eq a, Num a) => a
pattern ARGON2_PWD_PTR_MISMATCH :: (Eq a, Num a) => a
pattern ARGON2_SALT_PTR_MISMATCH :: (Eq a, Num a) => a
pattern ARGON2_SECRET_PTR_MISMATCH :: (Eq a, Num a) => a
pattern ARGON2_AD_PTR_MISMATCH :: (Eq a, Num a) => a
pattern ARGON2_MEMORY_ALLOCATION_ERROR :: (Eq a, Num a) => a
pattern ARGON2_FREE_MEMORY_CBK_NULL :: (Eq a, Num a) => a
pattern ARGON2_ALLOCATE_MEMORY_CBK_NULL :: (Eq a, Num a) => a
pattern ARGON2_INCORRECT_PARAMETER :: (Eq a, Num a) => a
pattern ARGON2_INCORRECT_TYPE :: (Eq a, Num a) => a
pattern ARGON2_OUT_PTR_MISMATCH :: (Eq a, Num a) => a
pattern ARGON2_THREADS_TOO_FEW :: (Eq a, Num a) => a
pattern ARGON2_THREADS_TOO_MANY :: (Eq a, Num a) => a
pattern ARGON2_MISSING_ARGS :: (Eq a, Num a) => a
pattern ARGON2_ENCODING_FAIL :: (Eq a, Num a) => a
pattern ARGON2_DECODING_FAIL :: (Eq a, Num a) => a
pattern ARGON2_THREAD_FAIL :: (Eq a, Num a) => a
pattern ARGON2_DECODING_LENGTH_FAIL :: (Eq a, Num a) => a
pattern ARGON2_VERIFY_MISMATCH :: (Eq a, Num a) => a
pattern ARGON2_MIN_LANES :: (Eq a, Num a) => a
pattern ARGON2_MAX_LANES :: (Eq a, Num a) => a
pattern ARGON2_MIN_THREADS :: (Eq a, Num a) => a
pattern ARGON2_MAX_THREADS :: (Eq a, Num a) => a
pattern ARGON2_SYNC_POINTS :: (Eq a, Num a) => a
pattern ARGON2_MIN_OUTLEN :: (Eq a, Num a) => a
pattern ARGON2_MAX_OUTLEN :: (Eq a, Num a) => a
pattern ARGON2_MIN_MEMORY :: (Eq a, Num a) => a
pattern ARGON2_MAX_MEMORY_BITS :: (Eq a, Num a) => a
pattern ARGON2_MAX_MEMORY :: (Eq a, Num a) => a
pattern ARGON2_MIN_TIME :: (Eq a, Num a) => a
pattern ARGON2_MAX_TIME :: (Eq a, Num a) => a
pattern ARGON2_MIN_PWD_LENGTH :: (Eq a, Num a) => a
pattern ARGON2_MAX_PWD_LENGTH :: (Eq a, Num a) => a
pattern ARGON2_MIN_AD_LENGTH :: (Eq a, Num a) => a
pattern ARGON2_MAX_AD_LENGTH :: (Eq a, Num a) => a
pattern ARGON2_MIN_SALT_LENGTH :: (Eq a, Num a) => a
pattern ARGON2_MAX_SALT_LENGTH :: (Eq a, Num a) => a
pattern ARGON2_MIN_SECRET :: (Eq a, Num a) => a
pattern ARGON2_MAX_SECRET :: (Eq a, Num a) => a


-- | <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 (unsafe) 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 binary stream of bytes (of size <a>hashLength</a>).
hash :: HashOptions -> ByteString -> ByteString -> Either Argon2Status ByteString

-- | Encode a password with a given salt and <a>HashOptions</a> and produce
--   a textual encoding according to the <a>PHC string format</a> of the
--   result.
--   
--   Use <a>verifyEncoded</a> to verify.
hashEncoded :: HashOptions -> ByteString -> ByteString -> Either Argon2Status ShortText

-- | Verify that a given password could result in a given hash output.
--   Automatically determines the correct <a>HashOptions</a> based on the
--   encoded hash (using the <a>PHC string format</a> as produced by
--   <a>hashEncoded</a>).
--   
--   Returns <a>Argon2Ok</a> on successful verification. If decoding is
--   successful but the password mismatches, <a>Argon2VerifyMismatch</a> is
--   returned; if decoding fails, the respective <a>Argon2Status</a> code
--   is returned.
verifyEncoded :: ShortText -> ByteString -> Argon2Status

-- | Parameters that can be adjusted to change the runtime performance of
--   the hashing. See also <a>defaultHashOptions</a>.
data HashOptions
HashOptions :: !Word32 -> !Word32 -> !Word32 -> !Argon2Variant -> !Argon2Version -> !Word32 -> 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
--   <a>kibibytes</a>.
--   
--   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 variant of Argon2 to use.
[hashVariant] :: HashOptions -> !Argon2Variant

-- | Which version of Argon2 to use for generating hashes.
[hashVersion] :: HashOptions -> !Argon2Version

-- | Desired length of hash expressed in octets.
[hashLength] :: HashOptions -> !Word32

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

-- | Argon2id works as Argon2i for the first half of the first iteration
--   over the memory, and as Argon2d for the rest, thus providing both
--   side-channel attack protection and brute-force cost savings due to
--   time-memory tradeoffs.
Argon2id :: Argon2Variant

-- | Version of the Argon2 algorithm.
data Argon2Version

-- | Version 1.0 (deprecated)
Argon2Version10 :: Argon2Version

-- | Version 1.3 (See <a>this announcment</a> for more details)
Argon2Version13 :: Argon2Version

-- | 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>  = 3
--                 , <a>hashMemory</a>      = 2 ^ 12 -- 4 MiB
--                 , <a>hashParallelism</a> = 1
--                 , <a>hashVariant</a>     = <a>Argon2i</a>
--                 , <a>hashVersion</a>     = <a>Argon2Version13</a>
--                 , <a>hashLength</a>      = 2 ^ 5 -- 32 bytes
--                 }
--   </pre>
--   
--   For more information on how to select these parameters for your
--   application, see section 6.4 of the <a>Argon2 specification</a>.
defaultHashOptions :: HashOptions

-- | Returned status code for Argon2 functions.
--   
--   Not all <a>HashOptions</a> can necessarily be used to compute hashes.
--   If you supply unsupported or invalid <a>HashOptions</a> (or hashing
--   otherwise fails) an <a>Argon2Status</a> value will be returned to
--   describe the failure.
--   
--   Note that this enumeration contains some status codes which are not
--   expected to be returned by the operation provided by the Haskell API.
data Argon2Status

-- | OK (operation succeeded)
Argon2Ok :: Argon2Status

-- | Output pointer is <tt>NULL</tt>
Argon2OutputPtrNull :: Argon2Status

-- | Output is too short
Argon2OutputTooShort :: Argon2Status

-- | Output is too long
Argon2OutputTooLong :: Argon2Status

-- | Password is too short
Argon2PwdTooShort :: Argon2Status

-- | Password is too long
Argon2PwdTooLong :: Argon2Status

-- | Salt is too short
Argon2SaltTooShort :: Argon2Status

-- | Salt is too long
Argon2SaltTooLong :: Argon2Status

-- | Associated data is too short
Argon2AdTooShort :: Argon2Status

-- | Associated data is too long
Argon2AdTooLong :: Argon2Status

-- | Secret is too short
Argon2SecretTooShort :: Argon2Status

-- | Secret is too long
Argon2SecretTooLong :: Argon2Status

-- | Time cost is too small
Argon2TimeTooSmall :: Argon2Status

-- | Time cost is too large
Argon2TimeTooLarge :: Argon2Status

-- | Memory cost is too small
Argon2MemoryTooLittle :: Argon2Status

-- | Memory cost is too large
Argon2MemoryTooMuch :: Argon2Status

-- | Too few lanes
Argon2LanesTooFew :: Argon2Status

-- | Too many lanes
Argon2LanesTooMany :: Argon2Status

-- | Password pointer is <tt>NULL</tt>, but password length is not 0
Argon2PwdPtrMismatch :: Argon2Status

-- | Salt pointer is <tt>NULL</tt>, but salt length is not 0
Argon2SaltPtrMismatch :: Argon2Status

-- | Secret pointer is <tt>NULL</tt>, but secret length is not 0
Argon2SecretPtrMismatch :: Argon2Status

-- | Associated data pointer is <tt>NULL</tt>, but ad length is not 0
Argon2AdPtrMismatch :: Argon2Status

-- | Memory allocation error
Argon2MemoryAllocationError :: Argon2Status

-- | The free memory callback is <tt>NULL</tt>
Argon2FreeMemoryCbkNull :: Argon2Status

-- | The allocate memory callback is <tt>NULL</tt>
Argon2AllocateMemoryCbkNull :: Argon2Status

-- | <tt>Argon2_Context</tt> context is <tt>NULL</tt>
Argon2IncorrectParameter :: Argon2Status

-- | There is no such version of Argon2
Argon2IncorrectType :: Argon2Status

-- | Output pointer mismatch
Argon2OutPtrMismatch :: Argon2Status

-- | Not enough threads
Argon2ThreadsTooFew :: Argon2Status

-- | Too many threads
Argon2ThreadsTooMany :: Argon2Status

-- | Missing arguments
Argon2MissingArgs :: Argon2Status

-- | Encoding failed
Argon2EncodingFail :: Argon2Status

-- | Decoding failed
Argon2DecodingFail :: Argon2Status

-- | Threading failure
Argon2ThreadFail :: Argon2Status

-- | Some of encoded parameters are too long or too short
Argon2DecodingLengthFail :: Argon2Status

-- | The password does not match the supplied hash
Argon2VerifyMismatch :: Argon2Status

-- | Internal error or unrecognized status code
Argon2InternalError :: Argon2Status
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.Enum.Enum Crypto.Argon2.Argon2Version
instance GHC.Generics.Generic Crypto.Argon2.Argon2Version
instance GHC.Enum.Bounded Crypto.Argon2.Argon2Version
instance GHC.Show.Show Crypto.Argon2.Argon2Version
instance GHC.Read.Read Crypto.Argon2.Argon2Version
instance GHC.Classes.Ord Crypto.Argon2.Argon2Version
instance GHC.Classes.Eq Crypto.Argon2.Argon2Version
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.Bounded Crypto.Argon2.Argon2Status
instance GHC.Enum.Enum Crypto.Argon2.Argon2Status
instance GHC.Show.Show Crypto.Argon2.Argon2Status
instance GHC.Read.Read Crypto.Argon2.Argon2Status
instance GHC.Classes.Ord Crypto.Argon2.Argon2Status
instance GHC.Classes.Eq Crypto.Argon2.Argon2Status
instance Control.DeepSeq.NFData Crypto.Argon2.Argon2Status
instance GHC.Exception.Type.Exception Crypto.Argon2.Argon2Status
instance Control.DeepSeq.NFData Crypto.Argon2.HashOptions
instance Control.DeepSeq.NFData Crypto.Argon2.Argon2Version
instance Control.DeepSeq.NFData Crypto.Argon2.Argon2Variant
