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


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


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

-- | BLAKE3 hashing.
hash :: forall (len :: Nat) digest bin. (ByteArrayN len digest, ByteArrayAccess bin) => Maybe Key -> [bin] -> IO digest

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

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

-- | Finalize incremental hashing and obtain a the BLAKE3 output of the
--   specified <tt>len</tt>gth.
finalize :: forall (len :: Nat) output. ByteArrayN len output => Ptr Hasher -> IO output

-- | Finalize incremental hashing and obtain the specified <tt>len</tt>gth
--   of BLAKE3 output starting at the specified offset.
--   
--   <pre>
--   <a>finalize</a> h = <a>finalizeSeek</a> h 0
--   </pre>
finalizeSeek :: forall (len :: Nat) output. ByteArrayN len output => Ptr Hasher -> Word64 -> IO output

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

-- | 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 derivation mode.
--   
--   The input key material must be provided afterwards, using
--   <a>update</a>.
initDerive :: ByteArrayAccess context => 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_raw(blake3_hasher *self, const void *context, size_t context_len)
--   </pre>
c_init_derive_key_raw :: Ptr Hasher -> Ptr Word8 -> CSize -> IO ()

-- | <pre>
--   void blake3_hasher_update(blake3_hasher *self, const void *input, size_t input_len)
--   </pre>
--   
--   Uses <a>c_update__unsafe</a> FFI call for <tt>input_len</tt> of up to
--   16 KiB, and <a>c_update__safe</a> otherwise.
c_update :: Ptr Hasher -> Ptr Word8 -> CSize -> IO ()

-- | <pre>
--   void blake3_hasher_update(blake3_hasher *self, const void *input, size_t input_len)
--   </pre>
--   
--   Like <tt>c_update_safe</tt>, but marked <tt>safe</tt> for FFI
--   purposes. Suitable when <tt>input_len</tt> is small. See
--   <a>c_update</a>.
c_update__safe :: Ptr Hasher -> Ptr Word8 -> CSize -> IO ()

-- | <pre>
--   void blake3_hasher_update(blake3_hasher *self, const void *input, size_t input_len)
--   </pre>
--   
--   Like <a>c_update__safe</a>, but marked <tt>unsafe</tt> for FFI
--   purposes. Suitable when <tt>input_len</tt> is big. See
--   <a>c_update</a>.
c_update__unsafe :: 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 GHC.Internal.TypeNats.KnownNat len => Data.ByteArray.Types.ByteArrayAccess (BLAKE3.IO.Digest len)
instance Data.ByteArray.Types.ByteArrayAccess BLAKE3.IO.Hasher
instance Data.ByteArray.Types.ByteArrayAccess BLAKE3.IO.Key
instance Data.ByteArray.Sized.ByteArrayN BLAKE3.IO.HASHER_SIZE BLAKE3.IO.Hasher
instance Data.ByteArray.Sized.ByteArrayN BLAKE3.IO.KEY_LEN BLAKE3.IO.Key
instance GHC.Internal.TypeNats.KnownNat len => Data.ByteArray.Sized.ByteArrayN len (BLAKE3.IO.Digest len)
instance GHC.Classes.Eq (BLAKE3.IO.Digest len)
instance GHC.Classes.Eq BLAKE3.IO.Hasher
instance GHC.Classes.Eq BLAKE3.IO.Key
instance GHC.Classes.Ord (BLAKE3.IO.Digest len)
instance GHC.Internal.Show.Show (BLAKE3.IO.Digest len)
instance GHC.Internal.Show.Show BLAKE3.IO.Hasher
instance GHC.Internal.Show.Show BLAKE3.IO.Key
instance GHC.Internal.TypeNats.KnownNat len => GHC.Internal.Foreign.Storable.Storable (BLAKE3.IO.Digest len)
instance GHC.Internal.Foreign.Storable.Storable BLAKE3.IO.Hasher
instance GHC.Internal.Foreign.Storable.Storable BLAKE3.IO.Key


-- | Haskell bindings to the fast <a>official BLAKE3 hashing implementation
--   in assembly and C</a>. With support for AVX-512, AVX2, SSE 2, 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>init</a>, <a>update</a> and
--   <a>finalize</a>:
--   
--   <pre>
--   <a>hash</a> yk = <a>finalize</a> <a>.</a> <a>update</a> (<a>init</a> yk)
--   </pre>
hash :: forall (len :: Nat) digest bin. (ByteArrayN len digest, ByteArrayAccess bin) => Maybe Key -> [bin] -> digest

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

-- | 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.
--   
--   The key derivation <tt>context</tt> should be hardcoded, globally
--   unique, application-specific well-known string.
--   
--   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>
derive :: forall (len :: Nat) okm ikm context. (ByteArrayN len okm, ByteArrayAccess ikm, ByteArrayAccess context) => context -> [ikm] -> okm

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

-- | Initial <a>Hasher</a> for incremental hashing.
init :: Maybe Key -> Hasher

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

-- | Finalize incremental hashing and obtain a the BLAKE3 output of the
--   specified <tt>len</tt>gth.
finalize :: forall (len :: Nat) output. ByteArrayN len output => Hasher -> output

-- | Finalize incremental hashing and obtain the specified <tt>len</tt>gth
--   of BLAKE3 output starting at the specified offset.
--   
--   <pre>
--   <a>finalize</a> h = <a>finalizeSeek</a> h 0
--   </pre>
finalizeSeek :: forall (len :: Nat) output. ByteArrayN len output => Hasher -> Word64 -> output

-- | In bytes.
type KEY_LEN = 32

-- | In bytes.
type BLOCK_SIZE = 64

-- | In bytes.
type DEFAULT_DIGEST_LEN = 32
