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


-- | BLAKE3 hashing algorithm
--   
--   Bindings to the official fast BLAKE3 implementations in assembly and
--   C, with support for AVX-512, AVX2 and SSE 4.1.
@package blake3
@version 0.2


-- | IO and low level tools.
module BLAKE3.IO

-- | BLAKE3 hashing.
hash :: forall len bin. (KnownNat len, ByteArrayAccess bin) => [bin] -> IO (Digest len)

-- | Initialize a <a>Hasher</a>.
init :: Ptr Hasher -> IO ()

-- | Update <a>Hasher</a> state with new data.
update :: forall bin. ByteArrayAccess bin => Ptr Hasher -> [bin] -> IO ()

-- | Finalize incremental hashin and obtain a <a>Digest</a>.
finalize :: forall len. KnownNat len => Ptr Hasher -> IO (Digest len)

-- | Finalize incremental hashing and obtain a <a>Digest</a> of length
--   <tt>len</tt> <i>after</i> the specified number of bytes of BLAKE3
--   output.
--   
--   <pre>
--   <a>finalize</a> h = <a>finalizeSeek</a> h 0
--   </pre>
finalizeSeek :: forall len. KnownNat len => Ptr Hasher -> Word64 -> IO (Digest len)

-- | Output from BLAKE3 algorithm, of <tt>len</tt> bytes.
--   
--   The default digest length for BLAKE3 is <a>DEFAULT_DIGEST_LEN</a>.
data Digest (len :: Nat)

-- | Obtain a digest containing bytes from a third-party source.
--   
--   This is useful if you want to use the <a>Digest</a> datatype in your
--   programs, but you are loading the pre-calculated digests from a
--   database or similar.
digest :: forall len bin. (KnownNat len, ByteArrayAccess bin) => bin -> Maybe (Digest len)

-- | Key used for keyed hashing mode.
--   
--   Obtain with <a>key</a>.
--   
--   See <a>hashKeyed</a>.
data Key

-- | Obtain a <a>Key</a> for use in BLAKE3 keyed hashing.
--   
--   See <a>hashKeyed</a>.
key :: ByteArrayAccess bin => bin -> Maybe Key

-- | Initialize a <a>Hasher</a> in keyed mode.
initKeyed :: Ptr Hasher -> Key -> IO ()

-- | Context for BLAKE3 key derivation. Obtain with <a>context</a>.
data Context

-- | Obtain a <a>Context</a> for BLAKE3 key derivation.
--   
--   The context should be hardcoded, globally unique, and
--   application-specific.
--   
--   A good format for the context string is:
--   
--   <pre>
--   [application] [commit timestamp] [purpose]
--   </pre>
--   
--   For example:
--   
--   <pre>
--   example.com 2019-12-25 16:18:03 session tokens v1
--   </pre>
context :: ByteArrayAccess bin => bin -> Maybe Context

-- | Initialize a <a>Hasher</a> in derivation mode.
--   
--   The input key material must be provided afterwards, using
--   <a>update</a>.
initDerive :: Ptr Hasher -> Context -> IO ()

-- | BLAKE3 internal state.
--   
--   Obtain with <a>hasher</a>, <a>hasherKeyed</a>.
data Hasher

-- | Obtain a <tt><a>Ptr</a> <a>Hasher</a></tt> to use with functions like
--   <a>initDerive</a>, etc.
modifyHasher :: Hasher -> (Ptr Hasher -> IO a) -> IO a
type HASHER_ALIGNMENT = 8

-- | In bytes.
type HASHER_SIZE = 1912

-- | In bytes.
type KEY_LEN = 32

-- | In bytes.
type BLOCK_SIZE = 64

-- | In bytes.
type DEFAULT_DIGEST_LEN = 32
type CHUNK_LEN = 1024
type MAX_DEPTH = 54
type MAX_SIMD_DEGREE = 16

-- | <pre>
--   void blake3_hasher_init(blake3_hasher *self)
--   </pre>
c_init :: Ptr Hasher -> IO ()

-- | <pre>
--   void blake3_hasher_init_keyed(blake3_hasher *self, const uint8_t key[<a>KEY_LEN</a>])
--   </pre>
c_init_keyed :: Ptr Hasher -> Ptr Word8 -> IO ()

-- | <pre>
--   void blake3_hasher_init_derive_key(blake3_hasher *self, const char *context)
--   </pre>
c_init_derive_key :: Ptr Hasher -> CString -> IO ()

-- | <pre>
--   void blake3_hasher_update(blake3_hasher *self, const void *input, size_t input_len)
--   </pre>
c_update :: Ptr Hasher -> Ptr Word8 -> CSize -> IO ()

-- | <pre>
--   void blake3_hasher_finalize(const blake3_hasher *self, uint8_t *out, size_t out_len)
--   </pre>
c_finalize :: Ptr Hasher -> Ptr Word8 -> CSize -> IO ()

-- | <pre>
--   void blake3_hasher_finalize_seek(const blake3_hasher *self, uint64_t seek, uint8_t *out, size_t out_len)
--   </pre>
c_finalize_seek :: Ptr Hasher -> Word64 -> Ptr Word8 -> CSize -> IO ()
instance Data.ByteArray.Sized.ByteArrayN BLAKE3.IO.HASHER_SIZE BLAKE3.IO.Hasher
instance Data.ByteArray.Types.ByteArrayAccess BLAKE3.IO.Hasher
instance GHC.Classes.Eq BLAKE3.IO.Context
instance GHC.Classes.Eq BLAKE3.IO.Hasher
instance GHC.Show.Show BLAKE3.IO.Hasher
instance Foreign.Storable.Storable BLAKE3.IO.Hasher
instance Data.ByteArray.Sized.ByteArrayN BLAKE3.IO.KEY_LEN BLAKE3.IO.Key
instance Data.ByteArray.Types.ByteArrayAccess BLAKE3.IO.Context
instance GHC.Show.Show BLAKE3.IO.Context
instance Data.String.IsString BLAKE3.IO.Context
instance GHC.Classes.Eq BLAKE3.IO.Key
instance GHC.Show.Show BLAKE3.IO.Key
instance Data.ByteArray.Types.ByteArrayAccess BLAKE3.IO.Key
instance Foreign.Storable.Storable BLAKE3.IO.Key
instance GHC.Classes.Eq (BLAKE3.IO.Digest len)
instance GHC.Show.Show (BLAKE3.IO.Digest len)
instance Data.ByteArray.Types.ByteArrayAccess (BLAKE3.IO.Digest len)
instance GHC.TypeNats.KnownNat len => Data.ByteArray.Sized.ByteArrayN len (BLAKE3.IO.Digest len)
instance GHC.TypeNats.KnownNat len => Foreign.Storable.Storable (BLAKE3.IO.Digest len)


-- | Haskell bindings to the fast <a>official BLAKE3 hashing implementation
--   in assembly and C</a>. With support for AVX-512, AVX2 and SSE 4.1.
--   
--   The original assembly and C implementation is released into the public
--   domain with CC0 1.0. Alternatively, it is licensed under the Apache
--   License 2.0, copyright of Jack O'Connor and Samuel Neves. See its
--   <a>LICENSE</a> for details.
--   
--   This Haskell library is the copyright of Renzo Carbonara, licensed
--   under the terms of the <a>Apache License 2.0</a>.
module BLAKE3

-- | BLAKE3 hashing.
--   
--   For incremental hashing, see <a>hasher</a>, <a>update</a> and
--   <a>finalize</a>:
--   
--   <pre>
--   <a>hash</a> = <a>finalize</a> <a>.</a> <a>update</a> <a>hasher</a>
--   </pre>
hash :: forall len bin. (KnownNat len, ByteArrayAccess bin) => [bin] -> Digest len

-- | Output from BLAKE3 algorithm, of <tt>len</tt> bytes.
--   
--   The default digest length for BLAKE3 is <a>DEFAULT_DIGEST_LEN</a>.
data Digest (len :: Nat)

-- | Obtain a digest containing bytes from a third-party source.
--   
--   This is useful if you want to use the <a>Digest</a> datatype in your
--   programs, but you are loading the pre-calculated digests from a
--   database or similar.
digest :: forall len bin. (KnownNat len, ByteArrayAccess bin) => bin -> Maybe (Digest len)

-- | BLAKE3 hashing with a <a>Key</a>.
--   
--   This can be used for MAC (message authentication code), PRF (pseudo
--   random function) and SHO (stateful hash object) purposes.
--   
--   For incremental hashing, see <a>hasherKeyed</a>, <a>update</a> and
--   <a>finalize</a>:
--   
--   <pre>
--   <a>hashKeyed</a> key = <a>finalize</a> <a>.</a> <a>update</a> (<a>hasherKeyed</a> key)
--   </pre>
hashKeyed :: forall len bin. (KnownNat len, ByteArrayAccess bin) => Key -> [bin] -> Digest len

-- | Key used for keyed hashing mode.
--   
--   Obtain with <a>key</a>.
--   
--   See <a>hashKeyed</a>.
data Key

-- | Obtain a <a>Key</a> for use in BLAKE3 keyed hashing.
--   
--   See <a>hashKeyed</a>.
key :: ByteArrayAccess bin => bin -> Maybe Key

-- | BLAKE3 key derivation.
--   
--   This can be used for KDF (key derivation function) purposes.
derive :: forall len ikm. (KnownNat len, ByteArrayAccess ikm) => Context -> [ikm] -> Digest len

-- | Context for BLAKE3 key derivation. Obtain with <a>context</a>.
data Context

-- | Obtain a <a>Context</a> for BLAKE3 key derivation.
--   
--   The context should be hardcoded, globally unique, and
--   application-specific.
--   
--   A good format for the context string is:
--   
--   <pre>
--   [application] [commit timestamp] [purpose]
--   </pre>
--   
--   For example:
--   
--   <pre>
--   example.com 2019-12-25 16:18:03 session tokens v1
--   </pre>
context :: ByteArrayAccess bin => bin -> Maybe Context

-- | BLAKE3 internal state.
--   
--   Obtain with <a>hasher</a>, <a>hasherKeyed</a>.
data Hasher

-- | Initial <a>Hasher</a> for incremental hashing.
hasher :: Hasher

-- | Initial <a>Hasher</a> for incremental <i>keyed</i> hashing.
hasherKeyed :: Key -> Hasher

-- | Update <a>Hasher</a> with new data.
update :: forall bin. ByteArrayAccess bin => Hasher -> [bin] -> Hasher

-- | Finish hashing and obtain a <a>Digest</a> of the specified
--   <tt>len</tt>gth.
finalize :: forall len. KnownNat len => Hasher -> Digest len

-- | Finalize incremental hashing and obtain a <tt>Digest</tt> of length
--   <tt>len</tt> <i>after</i> the specified number of bytes of BLAKE3
--   output.
--   
--   <pre>
--   <a>finalize</a> h = <a>finalizeSeek</a> h 0
--   </pre>
finalizeSeek :: forall len. KnownNat len => Hasher -> Word64 -> Digest len

-- | In bytes.
type KEY_LEN = 32

-- | In bytes.
type BLOCK_SIZE = 64

-- | In bytes.
type DEFAULT_DIGEST_LEN = 32